Developer API

Mailbase REST API

A workspace-scoped API for transactional email, audience sync, campaign visibility, and operational checks. Tokens are generated in Settings → Developer API.

Authentication

Every request uses a bearer token. Tokens are shown once, stored hashed by Mailbase, can be created with an expiry, and can be revoked from the workspace settings screen.

Authorization: Bearer mb_live_...

Scope	Allows
email:send	Send transactional email through the workspace sender setup.
campaigns:read	List campaigns and delivery stats.
audiences:read	List audiences and contact counts.
audiences:write	Create audiences and import contacts.
contacts:read	Read contact profiles and suppression status.
contacts:write	Create, update, suppress, or resubscribe contacts.
events:read	Read delivery, engagement, and reply events.
events:write	Record behavioural contact events, including conversion value.
templates:read	Read email templates.
templates:write	Create and update email templates.
webhooks:write	Create and manage outgoing webhook endpoints.
analytics:read	Read analytics endpoints as they are added.

OpenAPI

GET /api/v1/openapi.json

The current machine-readable API contract is available as OpenAPI 3.1. It is checked against the implemented /api/v1 routes in tests.

curl https://mailbase.studio/api/v1/openapi.json

Idempotency

Mutating API requests that send or create records accept an Idempotency-Key header. Reusing the same key with the same payload returns the original response; reusing it with a different payload returns a conflict.

Rate Limits

Authenticated API requests are limited by both bearer token and workspace. Successful and limited responses include RateLimit-* plus token/workspace-specific headers so integrations can back off safely.

Subject	Default limit	Notes
Token	120 requests / minute	Each bearer token has its own request window.
Workspace	600 requests / minute	All API tokens in a workspace share this ceiling.

Response

HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 42
X-RateLimit-Token-Limit: 120
X-RateLimit-Workspace-Limit: 600

Health Check

GET /api/v1/me

Use this endpoint to verify a token and identify the workspace it belongs to.

Request

curl https://mailbase.studio/api/v1/me \
  -H "Authorization: Bearer mb_live_..."

Response

{
  "workspace": { "id": "...", "name": "Acme", "slug": "acme" },
  "scopes": ["email:send", "campaigns:read"]
}

Send Transactional Email

POST /api/v1/send

Sends through the workspace's configured useSend connection and default sender. Mailbase records the send for quota, analytics, and future webhook matching.

Request

curl https://mailbase.studio/api/v1/send \
  -H "Authorization: Bearer mb_live_..." \
  -H "Idempotency-Key: invoice-123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your invoice is ready",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready.",
    "transactional": true
  }'

For non-transactional sends, Mailbase adds one-click List-Unsubscribe headers and skips contacts already marked unsubscribed, bounced, complained, or suppressed. Use transactional: true only for service messages that do not require marketing unsubscribe handling.

Field	Type	Required	Notes
to	string or string[]	Yes	Recipient email address or batch list.
subject	string	Yes	Email subject.
html	string	One of html/text	HTML body.
text	string	One of html/text	Plain-text body.
senderId	uuid	No	Optional configured sender; default sender is used otherwise.
tags	object	No	Forwarded to useSend when supported.
transactional	boolean	No	Set true for service email; marketing sends default to suppression enforcement.

Campaigns

GET /api/v1/campaigns

List campaigns in the token's workspace.

curl https://mailbase.studio/api/v1/campaigns \
  -H "Authorization: Bearer mb_live_..."

Audiences

GET · POST /api/v1/audiences

List audiences or create a new static audience with contacts.

List

curl https://mailbase.studio/api/v1/audiences \
  -H "Authorization: Bearer mb_live_..."

Create

curl https://mailbase.studio/api/v1/audiences \
  -H "Authorization: Bearer mb_live_..." \
  -H "Idempotency-Key: audience-launch-list-1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Launch list",
    "contacts": [
      { "email": "marie@example.com", "firstName": "Marie" }
    ]
  }'

Outgoing Webhooks

Configure signed event webhooks in Settings → Developer API. Mailbase sends JSON envelopes for email, reply, audience, and campaign events to each active endpoint.

Headers

Mailbase-Event: email.delivered
Mailbase-Delivery: 0f6f...
Mailbase-Timestamp: 1779624000
Mailbase-Signature: v1=<hex hmac sha256>

Verify the signature by computing HMAC-SHA256 over timestamp + "." + rawBody with the endpoint signing secret, then compare it with the v1= value from Mailbase-Signature.

Error Format

Errors return JSON with a stable error string.

{
  "error": "Missing scope: email:send"
}