API reference

A JSON API over HTTPS. 32 endpoints, all versioned under /v1. Last updated November 1, 2026.

• Authentication
• Errors
• Idempotency
• Limits
• Sending
• Message status
• Suppressions
• Webhooks
• Sending domains
• Statistics and account
• Team
• Sandbox

Authentication

Every request carries an API key as a bearer token. Keys are created under API keys and shown once.

Authorization: Bearer zm_live_...

A key carries a set of scopes, and a request outside them is refused with 403 insufficient_scope naming the scope it wanted.

Errors

An error is JSON with a stable machine code and a sentence for a human. Match on error; message may be reworded or translated.

{
  "error": "insufficient_scope",
  "message": "This API key lacks the email:messages.send scope."
}

Codes you may see on a 422 include invalid_from, invalid_email, invalid_domain, invalid_url, subject_too_long, body_too_large, file_too_large, reserved_header, too_many_headers and duplicate_header. A few older validation failures return error as a sentence with no code; treat an unrecognised error value as a refusal you should not retry unchanged.

Idempotency

Send an Idempotency-Key header and a retry of the same request will not send a second message. Keys are remembered for 24 hours.

Idempotency-Key: order-18472-receipt

It is a guard against sending twice, not a cache of responses: a request that arrives while the first is still in flight is refused rather than answered from a half-finished send.

Limits

Sending

One address per request. A 2xx means we have accepted the message and taken responsibility for it, not that it has arrived — poll the message or take a webhook for that.

Request fields

The from address is set on the key, not in the request, so a leaked key cannot send as somebody else.

# Send one
curl -X POST https://zedmail.com/v1/email/send \
  -H "Authorization: Bearer $ZEDMAIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-18472-receipt" \
  -d '{
    "to": "jane@example.com",
    "subject": "Your receipt",
    "html": "<p>Thank you.</p>",
    "tags": ["receipt"]
  }'

=> 200
{ "status": "queued", "message_id": "msg_4f68af67910b67a097" }

Message status

/v1/email/{id} answers "what happened to this message". /v1/recipients/{email} answers "did this person get it", which the first cannot, because the asker rarely has a message id.

Statuses

Only the last four are final. blocked is the one people miss: the message was not sent because transport encryption could not be established, so the address is still good.

Suppressions

A suppressed address is refused before a send is attempted. Reasons are bounce, complaint, unsubscribe, manual and soft_bounce_threshold. A blocked message never creates a suppression — the address is still valid.

Webhooks

These manage endpoints. The payloads, the signature scheme and the retry schedule are documented on the Webhooks page in your account, where the examples can name your own endpoints and secret.

Sending domains

You may only send from a domain you have verified. Verification checks DKIM, SPF and DMARC as a receiver reads them.

Statistics and account

from and to query parameters take YYYY-MM-DD. The three /v1/account/* routes mirror the shape of Amazon SES's equivalents, so a migration can keep its existing calls.

Team

Invitations and members. The /invites routes are declared before /{id} and ids are UUID-constrained, so the literal invites segment can never be read as a user id.

Sandbox

A new account sends only to addresses it has verified. This adds one.

Elsewhere

• Webhook payloads, signature verification and the retry schedule
• FAQ  ·  Data Processing Agreement  ·  Changelog
• /mcp — a JSON-RPC wrapper over these endpoints for agents, filtered by the same scopes.

Something missing or wrong here? Tell us and it gets fixed — this page is checked against the router on every deploy, but only the code can say what it does.