Send an email
Validate and accept a transactional email, returning 202 Accepted with the message id once the message is saved and (unless every recipient is suppressed) queued for sending. 202 means acceptance, not delivery. The outcome arrives later in the message's last_event and events timeline. In live mode the from address domain must be a verified sending domain. Requires the send scope. Honors the optional Idempotency-Key header.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Header Parameters
Opt-in idempotency key, 1–256 characters (no charset restriction). A repeated key with the same body within 24 hours replays the original 2xx response verbatim; the same key with a different body returns 409.
>= 1, <= 256Body
fromstringrequiredSender address. In live mode the domain must be a verified sending domain owned by the organization.
toanyrequiredA single address or an array of addresses.
ccanyA single address or an array of addresses.
bccanyA single address or an array of addresses.
reply_toanyA single address or an array of addresses.
subjectstringhtmlstringHTML body. At least one of html, text, or template is required.
textstringPlain-text body.
headersobjectArbitrary additional headers as a string map.
attachmentsarray<object>Files to attach. Validated when the request is received: a malformed entry returns a 422 whose param names it by index (for example attachments.0.content). The total base64 across all attachments must not exceed 41,943,040 bytes, reported as param: attachments. See the Attachments guide.
attachments.filenamestringrequiredThe name shown to the recipient. Must be a non-empty string.
>= 1attachments.contentstringrequiredThe file's bytes, base64-encoded. Bare base64 with no data: URI prefix. Line-wrapped base64 and the URL-safe alphabet (- and _) are both accepted.
>= 1attachments.contentTypestringMIME type, for example application/pdf. Derived from filename when omitted. Note the camelCase spelling; content_type is ignored.
attachments.cidstringContent-ID. Setting it makes the part inline (referenced from HTML as cid:<value>) rather than a listed attachment.
tagsarray<object>Up to 75 message tags.
<= 75 elementstags.namestringrequiredTag name; must match [A-Za-z0-9_-]+.
tags.valuestringrequiredTag value; must match [A-Za-z0-9_-]+.
scheduled_atstring<date-time>ISO 8601 send time, up to 90 days ahead. A past or omitted value sends immediately.
templateobjecttemplate.idstringrequiredThe template id (tmpl_…) to render at accept time.
template.variablesobjectFlat key/value variables substituted into {{name}} placeholders.
type"transactional" | "marketing"The kind of mail, as the sender declares it. Omitting the field means transactional. A marketing send is subject to extra compliance rules — it accepts exactly one recipient across to/cc/bcc, the organization must have a postal address on file, and it draws on a separate monthly marketing allowance.
"transactional" | "marketing""transactional"Response
The email was accepted.
object"email"required"email"idstringrequiredThe accepted message id (a bare ULID, no prefix).
status"queued" | "canceled"requiredqueued normally. canceled when every recipient was suppressed, in which case nothing was queued and nothing will be sent.
"queued" | "canceled"type"transactional" | "marketing"requiredThe kind of mail, as the sender declares it. Omitting the field means transactional. A marketing send is subject to extra compliance rules — it accepts exactly one recipient across to/cc/bcc, the organization must have a postal address on file, and it draws on a separate monthly marketing allowance.
"transactional" | "marketing""transactional"toarray<string>requiredccarray<string>requiredbccarray<string>requiredfromstringrequiredsubjectstringrequiredscheduled_atstring<date-time>requiredcreated_atstring<date-time>required