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.
`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

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.french-web.com/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.

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

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

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

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

Send Transactional Email

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

curl https://mailbase.french-web.com/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

List campaigns in the token's workspace.

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

Audiences

List audiences or create a new static audience with contacts.

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

curl https://mailbase.french-web.com/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.

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"
}