---
title: "Send a transactional email"
method: POST
path: "/emails"
tags: ["Emails"]
---

# Send a transactional email

`POST /emails`

## Request

- Base URL: `https://api.supersendtx.com`
- URL: `https://api.supersendtx.com/emails`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- SendEmailRequest: `subject` is required unless `template` is provided (subject comes from the published template). Provide `html` and/or `text`, or `template` (mutually exclusive). React Email is compiled client-side by the Node SDK (`react` option) — do not send `react` to the HTTP API.
  - `from` union, required
    - string, email
    - object
      - `email` string, email, required
      - `name` string
  - `to` union, required
    - string, email
    - string[]
  - `subject` string: Required unless using `template` (optional override when sending with a template).
  - `html` string
  - `htmlBody` string: Alias for html
  - `html_body` string: Alias for html
  - `text` string
  - `textBody` string: Alias for text
  - `text_body` string: Alias for text
  - `plain_body` string: Alias for text
  - `template` SendTemplateRef: Reference a published template by UUID or alias. Mutually exclusive with html/text.
    - `id` string, required: Template UUID or alias
    - `variables` object: Values for `{{variable}}` placeholders (HTML-escaped in html body)
  - `reply_to` union
    - string, email
    - string[]
  - `replyTo` union: Alias for reply_to
    - string, email
    - string[]
  - `cc` union
    - string
    - string[]
  - `bcc` union
    - string
    - string[]
  - `tags` union: Key/value tags stored with the email. SuperSend TX derives a single tag for delivery metadata.
    - EmailTag[]
      - `name` string, required
      - `value` string, required
    - object
  - `tag` string: Optional delivery tag override.
  - `headers` object: Custom headers after server-side safety filtering.
  - `attachments` EmailAttachment[]: Not supported for batch sends or scheduled sends in v1.
    - `name` string, required: Filename sent to the recipient.
    - `filename` string: Alias for name.
    - `content_type` string, required
    - `contentType` string: Alias for content_type.
    - `data` string, byte, required: Base64-encoded attachment content (10MB decoded max).
    - `content` string, byte: Alias for data (base64 string expected over HTTP).
    - `content_id` string: Optional Content-ID for inline attachments.
    - `contentId` string: Alias for content_id.
  - `scheduled_at` string, date-time: Schedule delivery for a future ISO 8601 timestamp. Returns status `scheduled`.
  - `scheduledAt` string, date-time: Alias for scheduled_at.
  - `unsubscribe` boolean: Opt in to managed unsubscribe for this send. Injects RFC 8058 `List-Unsubscribe` headers and replaces `{{unsubscribe_url}}` in subject/html/text. When sending with a template, inherits the template's `unsubscribe_enabled` setting unless overridden here.
  - `category` 'transactional' | 'product' | 'newsletter': Optional send-level category override. Defaults to the template's category when sending with a template, otherwise `transactional`. Product and newsletter categories support category-scoped opt-out and auto-enable managed unsubscribe.

## Response `200`

Email accepted for delivery

- SendEmailResponse
  - `id` string, required: Public message ID (`msg_…`)
  - `status` string, required

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `403`: From domain not verified, sandbox/verified-domain sender used for non-account recipients, or send to other recipients without a paid plan
- `404`: `template.id` does not match a template id or alias on this account
- `409`: Idempotency key conflict (payload mismatch or concurrent request)
- `422`: Recipient is suppressed or opted out of the email category, or the mail server refused the message (`upstream_error`)
- `429`: Send rate limit exceeded (`rate_limited` — too many sends this minute or hour; retry after `Retry-After` seconds), or Free plan send limit reached (`plan_limit` — daily or monthly; paid plans meter overage instead)
- `502`: Upstream mail server error
- `503`: Mail delivery temporarily unavailable
- `504`: The mail server could not confirm the send (timeout, dropped connection, or unreadable reply). The email may still be delivered.

---

[API](https://skmtc.dev/ranla/apis/supersend-tx-api.md) · [All operations](https://skmtc.dev/ranla/apis/supersend-tx-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ranla/apis/supersend-tx-api/revisions/e3e782652f50?raw)