EMAIL API · GUIDE
Email API request fields and limits
Send JSON with a verified sender, at least one recipient, a subject, and a text or HTML message body.
Request fields
Every request requires from, a recipient group, and either a published template_id or the legacy subject plus body/text/html fields. Supply recipients using top-level to or recipients with a to field in every group. Templates use the published default version and replace double-brace placeholders such as {{name}}; variable values are HTML-escaped in HTML templates.
The JSON request body is limited to 30 MB. HTTPS URL attachments may total up to 1 GB per email and are streamed by the background sender; inline base64 attachments are limited to 20 MB total. The SMTP relay and recipient mail servers may enforce lower message-size limits; MIME encoding also increases the final message size. HTTPS attachment URLs must resolve to public IP addresses and cannot redirect; local file paths are not accepted.
| Field | Type | Format | Required | Explanation |
|---|---|---|---|---|
| from | string or object | email@example.com or { name, email } | Yes | Sender address must belong to the verified domain assigned to the API key. |
| template_id | string | Published template ID, e.g. order-confirmation | When using a template | Uses the published default version; omit subject and body fields when provided. |
| recipients | object[] | [{ to: address[], cc?, bcc?, variables? }] | One of recipients or to | Each group is sent separately and must contain at least one to address. |
| to | string, string[], or address[] | email@example.net or { name, email } | When recipients is omitted | Primary recipient(s); maximum 50 recipients across to, cc, and bcc. |
| cc, bcc | string, string[], or address[] | email@example.net or { name, email } | No | Optional copy and blind-copy recipients, top-level or per recipient group. |
| variables | object | { name: "Asha", order_id: "A-1042" } | When template placeholders need values | Replaces {{variable}} placeholders in the template subject and body. |
| subject | string | Plain text; maximum 998 characters | Without template_id | Subject for a non-template message; line breaks are not allowed. |
| body, text, html | string or object | { text, html } or plain string | Without template_id | Message content. Use body or top-level text/html; text is limited to 100,000 and HTML to 500,000 characters. |
| domain | string | example.com | No | Optional assertion; must match the sender address domain. |
| reply_to | string[] or address[] | [{ email: "support@example.com" }] | No | Optional reply-to addresses. |
| attachments | object[] | [{ fileName, filePath: "https://..." }] or [{ filename, content_base64: "..." }] | No | Up to 10 items; each needs filename/fileName and exactly one source: content_base64, file (base64 data URI or HTTPS URL), url, or filePath (HTTPS URL). Optional content_type sets MIME type. Public HTTPS sources may total 1 GB per email; inline base64 is limited to 20 MB total. |