Send email
Sends a transactional email immediately or at a scheduled time. Provide the HTML or plain-text body inline. The from address must belong to a verified sending domain in the project.
to accepts email addresses or a single audience id — a topic (top_<ulid>) or segment (seg_<ulid>). Multiple direct addresses without cc or bcc fan out to one message per address, and the response reports the first accepted message plus a messages entry per recipient. Each fan-out message has its own delivery status, tracking, and unsubscribe links. If multiple to addresses are combined with cc or bcc, SES receives one shared message and its status is aggregate. An audience must be the only recipient and cannot be combined with cc or bcc, and at most 50 recipients fan out per request — the fan-out is paced to the project’s per-second send limit.
Emails are delivered through Amazon SES. Delivery events are available through webhooks and the email timeline endpoint.
Requirements
- Permission:
emails:send. - Safe retries: place
idempotencyKeyin the JSON body; Apollo Signal does not use an idempotency header. - HTTP rate limit: 300 requests per 60 seconds per API key.
Authorizations
Project-bound Apollo Signal API key. Keys begin with ap_signal_ and must carry the permission shown on the operation.
Body
Email message including sender, recipients (addresses or a topic / segment id), subject, body content, and optional scheduling and tracking configuration.
Email content and delivery options. from, to, and subject are required, and at least one of html or text must be supplied.
Sender address. Its domain must be verified in the authenticated project.
Email subject. The request is rejected when this field is omitted.
Recipient addresses, or one topic (top_…) or segment (seg_…) identifier. A single string is accepted. Audience sends are capped at 50 resolved recipients and cannot include cc or bcc.
Base64-encoded attachments. The decoded total must fit the configured attachment limit, and the message may contain at most 500 MIME parts including bodies.
Blind-carbon-copy recipient addresses. These count toward the project's per-message recipient limit.
Carbon-copy recipient addresses. These count toward the project's per-message recipient limit.
Allowed time window for an optimal non-transactional send. Required when optimization may delay the message.
HTML body. Supply html, text, or both.
Project-scoped key that returns the original send result when the request is retried.
Caller-defined string metadata associated with the send.
Address that receives replies instead of the sender address.
ISO 8601 send time or optimal. Explicit times must be 30 seconds to 30 days in the future; omit to send immediately.
Delivery category. transactional messages are never delayed by optimal-time scheduling. Defaults to transactional.
transactional, marketing, notification, digest Caller-defined string labels used to categorize the email.
Exercises the send flow without delivering to real recipients. Defaults to false.
Plain-text body. Supply html, text, or both.
Per-message overrides for the project's tracking settings.
Response
Email accepted for delivery. The id can be used to retrieve status or cancel. For a recipient fan-out, messages lists one entry per recipient message; each entry can be tracked independently.