POST/v1/emails/send

Send email

Send or schedule a transactional email. Either reference a published template, or supply your own html/text inline.

Authentication

Requires a Bearer token (API key) in the Authorization header.

Headers

Idempotency-Keystring

A unique key to prevent the same email from being sent twice. If you retry a request with the same key, we'll return the original response instead of sending a duplicate.

Request body

templateIdstring

Published template to use (key or UUID). When omitted, you must provide from, subject, and at least one of html or text.

tostring (email)required

Recipient email address(es). Can be a single address or an array.

ccstring (email)

CC recipient(s).

bccstring (email)

BCC recipient(s).

fromstring

Sender address. Required without templateId; overrides the template sender when both are provided. Accepts `Sender Name <email@domain.com>` or just `email@domain.com`.

subjectstring

Subject line. Required without templateId; overrides the template subject when both are provided. Supports variable substitution when using a template.

htmlstring

HTML email body. Cannot be used with templateId. At least one of html or text is required when sending without a template.

textstring

Plain text email body. Cannot be used with templateId. If omitted and html is provided, a plain text version is generated automatically.

replyTostring (email)

Reply-to address(es). Overrides the template's reply-to when provided.

variablesobject

Key-value pairs for template variable substitution. Only used with templateId. Keys must match variables defined in the template.

scheduledAtstring (date-time)

ISO 8601 datetime for scheduled delivery. If set to a future time, the email will be queued and sent at the specified time. If omitted, the email is sent immediately.

addContactboolean

When true, a contact record is created for the recipient if one does not already exist.

headersobject

Custom email headers as key-value pairs. Reserved headers (From, To, Subject, etc.) are not allowed.

attachmentsarray

File attachments. Each must have a filename and exactly one of content (base64) or path (HTTPS URL).

Response

200—Email sent or scheduled successfully

{
  "success": true,
  "id": "string",
  "status": "sent"
}

400—Validation error (template not found, variable errors)

{
  "success": false,
  "message": "string"
}

403—Forbidden

{
  "success": false,
  "message": "string"
}

409—Conflict (e.g. a request with the same Idempotency-Key is still in flight)

{
  "success": false,
  "message": "string"
}

422—Idempotency-Key was reused with a different request body

{
  "success": false,
  "message": "string"
}

500—Server error

{
  "success": false,
  "message": "string"
}