Quickstart: send a transactional email with the API
Send your product's email (receipts, password resets, notifications) through Mailbase: verify your domain, create an API key with the email:send scope, then POST to /api/v1/send.
Before you start
- A Mailbase workspace and a domain you control, so you can publish DNS records.
- On the free plan, sending from your own domain needs a verified card (nothing is charged); it then allows 3,000 emails a month, 100 a day. Paid plans start at 50,000 a month.
- The API is HTTP only: there is no SMTP relay.
1. Verify your domain
Open Settings, then Domains & health, and connect your domain (a subdomain such as mail.example.com keeps product mail apart from the rest). Mailbase shows the SPF, DKIM and DMARC records to publish at your DNS host and re-checks them until they verify.
Then add a sender address on that domain, for example no-reply@mail.example.com, and make it the default: /api/v1/send uses the default sender unless you pass a senderId.
Both steps also exist over the API once you have a key with the sending:write scope: POST /api/v1/domains returns the records, POST /api/v1/domains/{id}/verify re-checks them, and POST /api/v1/senders adds the address.
curl https://mailbase.studio/api/v1/domains \
-H "Authorization: Bearer mb_live_..." \
-H "Content-Type: application/json" \
-d '{ "domain": "mail.example.com" }'
curl https://mailbase.studio/api/v1/senders \
-H "Authorization: Bearer mb_live_..." \
-H "Content-Type: application/json" \
-d '{ "email": "no-reply@mail.example.com", "name": "Example", "set_default": true }'2. Create an API key
Open Settings, then API & webhooks, and create a token with the email:send scope (add events:read if you will read delivery events). It is shown once and stored hashed: put it in your backend's secret store, never in browser or mobile code. Check it with /api/v1/me.
curl https://mailbase.studio/api/v1/me \
-H "Authorization: Bearer mb_live_..."3. Send the email
One POST with the recipient, a subject and an HTML or text body. Set transactional to true for receipts, resets and notifications: the email then carries no unsubscribe header, still reaches someone who unsubscribed from your marketing, and is not held back by the per-domain warm-up or the frequency caps. Addresses that bounced permanently or complained are still skipped.
Send an Idempotency-Key with every request. If the call times out and you retry with the same key and body, recipients already accepted are not mailed again.
curl https://mailbase.studio/api/v1/send \
-H "Authorization: Bearer mb_live_..." \
-H "Idempotency-Key: receipt-4821" \
-H "Content-Type: application/json" \
-d '{
"to": "ada@example.com",
"subject": "Your receipt #4821",
"html": "<p>Thanks for your order. Your receipt is attached to your account.</p>",
"text": "Thanks for your order. Your receipt is attached to your account.",
"transactional": true
}'4. Read the response
A request that was processed answers 202 with one entry per recipient, under sent or failed. ok is true only when nothing failed. Keep the id of each send to match the events later.
| status in failed | Meaning |
|---|---|
| suppressed | The address bounced, complained or was erased; it is not mailed. |
| deferred | Not sent now (a non-transactional send hit a frequency cap); retryAt says when. |
| failed | Amazon SES refused it; error says why. Retrying with the same key is safe. |
| unknown | The outcome could not be confirmed. Do not resend with a new key; the events will settle it. |
{
"ok": true,
"campaignId": "…",
"sent": [
{ "id": "…", "email": "ada@example.com", "providerMsgId": "…", "status": "sent", "sentAt": "2026-11-17T09:41:00.000Z" }
],
"failed": []
}When the request itself is refused
| Status | Meaning |
|---|---|
| 400 | Invalid body: a bad address, no subject, no html, text or templateId, or more than 100 recipients. |
| 401 / 403 | The token is missing, revoked, or lacks the email:send scope. |
| 409 | held_for_review: scam screening was unsure and a person will look; retry later with the same key. Also returned when an Idempotency-Key is reused with a different body. |
| 422 | blocked_scam: the message was refused by scam screening. |
| 429 | A quota or rate limit: the monthly plan quota, the workspace's daily limit, or the API rate limit. Retry-After says when to retry where it applies. |
| 503 | No sending account is set up for the workspace, or screening is briefly unavailable. |
Send a stored template instead
Build the email once as an MJML template in the app, then send it by id with merge values. The subject comes from the template unless you pass one, and the HTML is rendered exactly as the app's preview shows it.
curl https://mailbase.studio/api/v1/send \
-H "Authorization: Bearer mb_live_..." \
-H "Idempotency-Key: reset-7f3a2c" \
-H "Content-Type: application/json" \
-d '{
"to": "ada@example.com",
"templateId": "6f1c…",
"mergeValues": { "first_name": "Ada", "reset_url": "https://app.example.com/reset/…" },
"transactional": true
}'Follow what happened
Amazon SES reports deliveries, bounces and complaints, and Mailbase attaches them to the send. Poll them with GET /api/v1/events (filter by kind, email or since, paginated by cursor), or add a webhook endpoint in Settings, then API & webhooks, to receive email.delivered, email.bounced and email.complained as they happen, signed with HMAC-SHA256.
curl "https://mailbase.studio/api/v1/events?kind=bounced&since=2026-11-17T00:00:00Z" \
-H "Authorization: Bearer mb_live_..."Limits worth knowing
- Up to 100 recipients per request; each gets their own copy.
- A new workspace ramps its daily volume up over its first days, starting at 50 emails on the first day. Plan a migration a week ahead.
- The monthly quota is your plan's. Past it, an email pack adds sends that never expire; otherwise the API answers 429 until the next month.
- Every message is screened for scams and phishing before it leaves, transactional or not.
- Mail goes out through Amazon SES in eu-west-1 (Ireland).