Send an email
POST /emails
{
"from": "Acme <hello@yourdomain.com>",
"to": "someone@example.com",
"subject": "Your receipt",
"html": "<p>Thanks.</p>"
}
| Field | Type | Notes |
|---|---|---|
from | string | Required. Name <addr> or a bare address. The domain must be one you have verified. |
to | string or array | Required. |
subject | string | Required. |
html | string | One of html or text is required. |
text | string | |
cc, bcc | string or array | |
reply_to | string or array | |
headers | object | Extra headers to set. |
attachments | array | `{ filename, content (base64) |
tags | object | Yours, for your own filtering. |
scheduled_at | string | RFC 3339. Omit to send now. |
Recipient fields accept a bare string or an array — both are correct.
Header: Idempotency-Key: <your key>. A repeat with the same key returns
the original message rather than sending twice.
Send one on every request you would retry. Without it, a timeout or a 500
leaves you unable to tell “not sent” from “sent, response lost”. Any unique
value works, and your own order or ticket id has the useful property that two
parts of your system retrying the same business event collapse onto one message.
Keys are scoped to your account and honoured for 24 hours; past that the
identifier is free again, so a stable one of yours is never permanently spent.
{ "id": "1042", "status": "queued" }
A partially suppressed send still goes. If three of fifty recipients are
suppressed, the other forty-seven are sent and the three are dropped. Only when
every recipient is suppressed do you get a suppressed error — one dead
address must not fail forty-nine good ones.
Limits
| Recipients | 50 per message, counting to, cc and bcc together |
| Body | 25 MB of html plus text |
| Attachments | 20 per message, 10 MB each |
Over any of them is 422 validation_error, naming which.