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

# Send a transactional email

`POST /emails`

## Request

- Base URL: `https://sending.dev/api/v1`
- URL: `https://sending.dev/api/v1/emails`
- Auth: HTTP bearer

Queues a transactional email (idempotent on `idempotencyKey`). Every address field accepts both `a@b.com` and `Name <a@b.com>`; `to`, `cc` and `bcc` also accept multiple recipients, as an array or comma-separated in the same string (at most 50 per message, one quota unit each). Required scope: `email:send`.

## Request body

- SendEmailInput
  - `to` union, required: Email recipients (To header). One or more recipients: 'a@b.com', 'Name <a@b.com>', several comma-separated addresses, or an array.
    - string
    - string[]
  - `from` string, required
  - `subject` string
  - `html` string
  - `text` string: Plain-text body. With html it is the multipart alternative; alone (no html, no templateId) it sends a text-only email: no open tracking, links left as written.
  - `replyTo` union: Reply-To: one or more addresses ('a@b.com', 'Name <a@b.com>', comma-separated or an array, at most 10). A plain "Reply" goes to all of them.
    - string
    - string[]
  - `cc` union: Visible copies (Cc header). One or more recipients: 'a@b.com', 'Name <a@b.com>', several comma-separated addresses, or an array.
    - string
    - string[]
  - `bcc` union: Hidden copies, in no header. One or more recipients: 'a@b.com', 'Name <a@b.com>', several comma-separated addresses, or an array.
    - string
    - string[]
  - `templateId` string
  - `variables` object
  - `attachments` object[]: Email attachments (max 20, 10 MB each, 25 MB in total). For each item provide exactly one source: `id`, `content` (base64) or `url`.
    - `id` string, uuid: Id of an attachment already uploaded with POST /v1/attachments.
    - `filename` string: File name shown to the recipient. Required with `content` or `url`.
    - `content` string: File content in base64, without the `data:` prefix.
    - `url` string, uri: Public https URL to download the file from (private hosts are blocked).
    - `contentType` string: Content-Type override; when absent, it is inferred from the file name.
    - `contentId` string: Content-ID for inline images referenced in the HTML as `cid:<value>`: the attachment becomes `inline` instead of appearing at the end of the message.
  - `idempotencyKey` string, required
  - `disableTracking` boolean
  - `disableUtm` boolean

## Response `200`

Send already processed for this idempotencyKey.

- SendResult
  - `id` string
  - `status` string, required
  - `idempotencyKey` string

## Other responses

- `202`: Email queued.
- `401`: Missing or invalid token.
- `402`: Plan quota exceeded.
- `403`: Insufficient scope.
- `404`: `templateId` does not exist for the tenant (`template_not_found`).
- `409`: Recipient is suppressed: bounce/complaint/unsubscribe (`suppressed`).
- `422`: Invalid input.
- `502`: Upstream provider error (e.g. SES).

---

[API](https://skmtc.dev/sending/apis/sending-dev-api.md) · [All operations](https://skmtc.dev/sending/apis/sending-dev-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sending/apis/sending-dev-api/revisions/9fe78d2918a1?raw)