Sending

Messages

Send email — inline or templated — and read its full lifecycle back.

A message is a single email to a single recipient. Send inline HTML, or reference a template by slug or id and pass variables.

Send a message

POST/v1/messagesSend (or schedule) one email.

`to`requiredstring	Recipient address, or `{ email, name }`.
`subject`string	Required unless the template supplies one.
`html / text`string	Inline body. Omit when using a template.
`template`string	A template slug. Use `template_id` for the id.
`variables`object	Values merged into the template (Handlebars).
`from / reply_to`string	Override the sender / reply-to (must be a verified sender).
`type`enum	`transactional` (default) or `marketing` — meters against the right wing.
`send_at`string	ISO 8601 — schedule for later instead of sending now.
`idempotency_key`string	Exactly-once — see Idempotency.
`tags / metadata`array / object	Your own labels; echoed back on events.

send-template.ts

const msg = await mail.messages.create({
  to: { email: "ada@example.com", name: "Ada" },
  template: "welcome",
  variables: { name: "Ada", action_url: "https://acme.com/start" },
  tags: ["onboarding"],
  idempotencyKey: `welcome-${user.id}`,
});
// → { id: "msg_…", status: "queued", … }

Retrieve, audit & prove

GET/v1/messagesList messages (paginated, filterable).

GET/v1/messages/:idFetch one message and its current status.

GET/v1/messages/:id/auditThe append-only lifecycle trail of every event.

GET/v1/messages/:id/proofA signed, verifiable proof bundle for the message.

audit.ts

const { trail } = await mail.messages.audit(msg.id);
// queued → sending → sent → delivered → opened …
const proof = await mail.messages.proof(msg.id); // { bundle, signature }

noteSuppressed, bounced, and unsubscribed recipients are checked automatically before every send — you can't accidentally email someone who opted out.

PreviousRate limits Next Templates