Send an email

POST/v1/email

Queue a message for delivery. emitd validates it, checks the suppression list, rate-limits per tenant, and hands it to SES. You get a 202 back immediately with a message_id.

Body parameters

Field	Type	Notes
`from` required	string	A verified sender on one of your authenticated domains.
`to`	string[]	Recipients. At least one of to/cc/bcc is required; 50 max per call.
`cc`, `bcc`, `reply_to`	string[] / string	Optional additional addresses.
`subject`	string	Required unless a template supplies it.
`html_body`, `text_body`	string	At least one is required unless a template supplies the body.
`message_stream`	string	`outbound` (default) or `broadcast` — keeps transactional and promotional reputation apart.
`template_alias`, `template_model`	string / object	Render a server-side template. `{{ variable }}` tokens are filled from the model (HTML is auto-escaped).
`tag`	string	An arbitrary label for filtering activity + analytics.
`scheduled_at`	integer	Epoch milliseconds in the future — the message is held and sent at that time. Reschedule with `PATCH /v1/email/{id}` or cancel with `DELETE /v1/email/{id}` while it's still scheduled.
`attachments`	object[]	Each needs `filename` + `content_type`, with either base64 `content` inline or an `r2_key` from `POST /v1/attachments` for larger files.

Request

POST /v1/email

{
  "from": "you@yourdomain.com",
  "to": ["ada@lovelace.io"],
  "cc": [],
  "bcc": [],
  "reply_to": "support@yourdomain.com",
  "subject": "Your receipt #4021",
  "html_body": "<h1>Thanks!</h1>",
  "text_body": "Thanks!",
  "message_stream": "outbound"
}

Response

202 Accepted

HTTP/2 202
{
  "message_id": "msg_2h8Kd0Rk9Qa",
  "status": "queued"
}

Sending with a template

Reference a template by alias and pass a model — emitd renders the active version server-side before sending.

POST /v1/email

{
  "from": "you@yourdomain.com",
  "to": ["ada@lovelace.io"],
  "template_alias": "receipt",
  "template_model": { "name": "Ada", "total": "$48.00" }
}

Safe retries with Idempotency-Key

Pass an Idempotency-Key header on any send. If the request is retried — a timeout, a crashed worker, a network blip — the same key returns the original result instead of sending twice. Keys are scoped to your account and don't expire on their own.

Sending in batches

POST /v1/email/batch accepts up to 100 messages in one call, each with the same shape as a single send. Results come back per-message, so one invalid recipient never fails the rest of the batch. Batch sends accept Idempotency-Key too.