Emails

Send a batch of emails

Queue up to 100 emails in a single request. The body is a JSON array of email objects, each using the same shape as the single-send endpoint. Validation runs on every item before any are queued — a malformed item rejects the whole batch with 400. Suppressed recipients (to, cc and bcc) are dropped per row; a row left with no deliverable To recipient is recorded with status "failed". The batch is accepted whole or not at all: every email is recorded and queued, or none is, so there is no partial success to reconcile. A 4xx means nothing was queued. After a 5xx or a lost response, retry with the same Idempotency-Key: you get the first answer if the batch was accepted, or a fresh attempt if it was not.

post/v1/emails/batch

Request

  • Base URL: https://smtpfa.st/api
  • URL: https://smtpfa.st/api/v1/emails/batch
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

A unique key for the whole batch; up to 255 characters are used. Repeating a request with the same key and body within 24 hours returns the first result instead of sending again. The same key with a different body is a 409, as is a retry while the first request with the key is still running.

Request body

fromstring email

Sender email address (must belong to a verified domain)

subjectstring

Email subject line

headersobject

Custom headers, e.g. X-Entity-Ref-ID

scheduled_atstring date-time

Send later, up to 30 days ahead (ISO 8601)

category'transactional' | 'marketing'

Defaults to marketing. Label receipts, password resets and other transactional mail transactional so a marketing opt-out does not block them; unlabelled mail is treated as marketing. Over SMTP, set the X-SMTPfast-Category header instead; it is removed before sending. An email whose html or text (for a template, the rendered body) contains an unsubscribe placeholder is always marketing. A marketing email carries the one-click List-Unsubscribe header and is not sent to anyone who unsubscribed. A transactional email has no List-Unsubscribe header and still goes to addresses whose suppression has scope marketing (a recipient's own unsubscribe, or a manual suppression created with scope marketing), but not to addresses with scope all: hard bounces, complaints, and manual suppressions, which block everything by default. Transactional means mail the recipient needs because of an action or account; labelling promotions transactional is not allowed. Any other value is refused with 400.

track_clicksboolean

Not in Resend, which sets tracking per domain. Rewrite this email's links through the click tracker (true) or send them exactly as written (false). Left out, the account's tracking settings apply, including the setting for transactional email, except that a contact-form relay (every recipient on the From domain or a parent or subdomain of it, Reply-To on an unrelated domain, not sent from an inbox) gets no click tracking. Over SMTP, set the X-SMTPfast-Track-Clicks header to true or false instead; it is removed before sending. To keep one link out of tracking, such as a password reset link with a token, add data-smtpfast-track="off" to its <a> tag; the attribute is removed before sending. null is the same as leaving it out; any other value that is not true or false is refused with 400.

track_opensboolean

Not in Resend. Add the open-tracking pixel to this email (true) or not (false). Left out, the account's tracking settings apply. Over SMTP, set the X-SMTPfast-Track-Opens header to true or false instead; it is removed before sending. null is the same as leaving it out; any other value that is not true or false is refused with 400.

htmlstring

HTML body of the email. Include {{unsubscribe_url}} (or the Resend-compatible {{{RESEND_UNSUBSCRIBE_URL}}}) anywhere in the body and SMTPfast substitutes the per-recipient unsubscribe link at send time. An email with the placeholder is always marketing, and a marketing email gets the same URL on the RFC 8058 List-Unsubscribe header.

textstring

Plain text fallback body. Supports the same {{unsubscribe_url}} placeholder as the HTML body.

Example request

[
  {
    "from": "hello@yourapp.com",
    "to": "user1@example.com",
    "subject": "Welcome!",
    "html": "<h1>Hello User 1!</h1>"
  },
  {
    "from": "hello@yourapp.com",
    "to": [
      "user2@example.com",
      "user3@example.com"
    ],
    "subject": "Weekly digest",
    "html": "<h1>Your week</h1>",
    "scheduled_at": "2026-04-10T14:00:00Z"
  }
]

Response

Batch accepted

batch_idstring required

Identifier for the batch as a whole

countinteger required

Number of emails created (matches input length)

Example response

{
  "batch_id": "batch_abc123",
  "count": 2,
  "emails": [
    {
      "id": "email_abc123",
      "status": "queued"
    }
  ],
  "data": [
    {
      "id": "email_abc123"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.