Sender address. Its domain must be one you added and verified in the dashboard; a display name is allowed ("Acme <[email protected]>").
headers
any
No
Extra headers to add to the message, as a name-to-value object.
html_body
string | null
No
HTML body. Send html_body, text_body or both; omit both only when template_alias renders the content.
idempotency_key
string | null
No
Optional idempotency key. If provided, a duplicate send with the same key (per account) returns the original email instead of creating a new one.
metadata
any
No
Free-form key-value data stored with the email and returned in webhooks.
reply_to
string | null
No
Address replies are sent to.
send_at
string | null
No
Time to send the email (ISO 8601). Omit to send immediately.
stream
string | null
No
Message stream slug. Routes this email through the named stream, enabling separate reputation tracking for transactional vs. marketing email. Defaults to "transactional". The stream must exist for the account.
Per-email tracking override. When false, disables open/click tracking for this email even if the account has tracking enabled. When true, enables tracking even if the account default is off. Omit to use account default.
transactional
boolean | null
No
Whether this is a transactional email (password reset, receipt, notification). When true or omitted, List-Unsubscribe headers are omitted so Gmail routes the message to the Primary inbox instead of Promotions. Set to false for marketing or newsletter emails that need one-click unsubscribe. Only an explicit true reaches a recipient who unsubscribed: omitting the field keeps the unsubscribe in force.
Responses
Status
Description
202
Email accepted for delivery. data is one email when to holds one address, and one email per address when it holds several.
401
Unauthorized (code AUTH_MISSING, AUTH_MALFORMED or AUTH_INVALID_KEY)
403
The sender domain is not on the account (code SENDER_DOMAIN_NOT_REGISTERED), sending is paused, or a card check is required
422
Validation error, a suppressed recipient (code RECIPIENT_SUPPRESSED), or an attachment was refused (code ATTACHMENT_REFUSED)
429
Rate limit or quota exceeded
503
The attachment scanner could not answer; retry after the Retry-After delay (code ATTACHMENT_SCAN_UNAVAILABLE)
Send up to 500 emails in a single request. Returns an operation_id for tracking, a data array of queued emails, and an errors array for any per-email failures. Partial success is supported. An email refused by a send-rate limit or the new-account allowance is also listed in rate_limited with code RATE_LIMIT_EXCEEDED and retry_after_seconds. When no email was accepted and every refusal is such a limit, the response is 429 with a retry-after header set to the longest wait; the body is the same.
Request Body
Field
Type
Required
Description
emails
SendEmailRequest[]
Yes
The emails to send, each shaped like the body of POST /v1/emails.
Responses
Status
Description
202
Batch accepted for delivery
401
Unauthorized
422
Validation error, or no email was accepted and not all refusals were rate limits
429
Every email was refused by a send-rate limit or the new-account allowance, or the account's request limit was hit. The retry-after header holds the longest wait.
Send an email to all active subscribers in a contact list
Request Body
Field
Type
Required
Description
contact_list_id
string
Yes
from_address
string
Yes
headers
any
No
html_body
string | null
No
reply_to
string | null
No
send_at
string | null
No
subject
string | null
No
tags
string[]
No
template_alias
string | null
No
template_data
any
No
text_body
string | null
No
tracking
boolean | null
No
transactional
boolean
No
Whether this is a transactional broadcast. Defaults to false because bulk sends are typically marketing emails that need List-Unsubscribe headers for Gmail/Yahoo compliance. Set to true only for operational bulk sends (e.g. account migration notices) where unsubscribe headers are inappropriate.