Send emails

Everything routes through one send path: REST and the SMTP relay share the same quota, suppression checks, and tracking pipeline. POST /emails requires from and to; everything else is optional:

{
  "from": "Acme <hi@acme.com>",
  "to": ["user@example.com"],
  "cc": [],
  "bcc": [],
  "reply_to": "support@acme.com",
  "subject": "Hello",
  "html": "<p>Hi {{name}}</p>",
  "text": "Hi",
  "headers": { "X-Entity-Ref": "order-123" },
  "tags": { "campaign": "onboarding" },
  "data": { "name": "Sam" },
  "scheduled_at": "2026-09-01T09:00:00Z",
  "template": "welcome-email",
  "stream_id": null,
  "attachments": [
    { "filename": "invoice.pdf", "content_type": "application/pdf", "content": "<base64>" }
  ]
}

• to, cc, bcc, and reply_to each accept a single address string or an array.
• data holds structured template variables; tags are flat string metadata.
• Reference a template by template (its stable alias) or template_id (UUID).
• stream_id picks the message stream; omitted, it defaults to your transactional stream.
• scheduled_at queues the send for the future; see Schedule & cancel.
• For attachments and inline images, see Attachments.

The API responds immediately with the email object (status: "queued", or "scheduled" for future sends); delivery happens asynchronously and every state change becomes an event you can receive by webhook or the live event stream.

Retrieving what you sent

• GET /emails/{id}: one email, including status and provider message id.
• GET /emails: cursor-paginated list, filterable by status, to, from, subject, tag, stream_id, and an after/before time range (RFC 3339). See Pagination.
• GET /emails/{id}/events: the delivery event timeline for one email.

Email status moves through: queued or scheduled → sending → sent → delivered, or ends in bounced, complained, failed, canceled, or suppressed.