Send an email

POST/v1/email

Queue a message for delivery. Relay 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.

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 — Relay 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" }
}