Emails

Send an email

Queue a single email for delivery. The email is validated, queued, and sent asynchronously via the configured sending provider. Recipients on domains reserved for documentation and tests (example.com, example.net, example.org, and anything under .test, .example, .invalid or .localhost) are refused with 400; for test sends use an address at simulator.amazonses.com, such as success@simulator.amazonses.com.

post/v1/emails

Request

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

Headers

Idempotency-Keystring

A unique key; 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.

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

{
  "template": {
    "id": "order-confirmation",
    "variables": {
      "PRODUCT": "Desk lamp",
      "PRICE": 49
    }
  },
  "attachments": [
    {
      "content_type": "image/png"
    }
  ],
  "from": "hello@yourapp.com",
  "subject": "Welcome!",
  "tags": [
    {
      "name": "category",
      "value": "welcome"
    }
  ],
  "headers": {
    "X-Entity-Ref-ID": "abc-123"
  },
  "scheduled_at": "2026-04-10T14:00:00Z",
  "category": "transactional",
  "html": "<h1>Hello!</h1><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p>",
  "text": "Hello! (plain text fallback)"
}

Response

Email accepted. A repeat with the same Idempotency-Key and body returns the same id.

idstring required

Example response

{
  "id": "email_abc123"
}

Changes

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