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, 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.
`analytics:read`	Reserved for analytics endpoints.

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

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.

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 "Content-Type: application/json" \
  -d '{
    "name": "Launch list",
    "contacts": [
      { "email": "marie@example.com", "firstName": "Marie" }
    ]
  }'

Error Format

Errors return JSON with a stable error string.

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