Sending

Send email

The fields, limits and options of a send request.

Send with POST /v1/send. The API answers 202 Accepted straight away and delivers in the background.

Your app posts to /v1/send and gets 202 queued. SNDR DKIM-signs and delivers the email; the result (delivered, bounced or failed) goes to your webhook endpoint.

curl -X POST https://api.sndr.sh/v1/send \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@mail.acme.com>",
    "to": ["customer@example.com"],
    "subject": "Hello from SNDR",
    "html": "<p>It works.</p>"
  }'

Request fields

fromstringrequired

The sender: hello@mail.acme.com or Acme <hello@mail.acme.com>. Its domain must be verified.

tostring[]required

Recipients, 1 to 1,000 addresses. Always an array in the HTTP API.

ccstring[]

Copied recipients, up to 100.

bccstring[]

Hidden recipients, up to 100.

reply_tostring

Where replies go, if not to from.

subjectstringrequired

One line, up to 998 characters. Optional when the template has a subject.

htmlstring

HTML body. Send html, text or both.

textstring

Plain-text body for clients that don’t show HTML.

template_idstring

A saved template. Its subject and bodies fill any field you leave empty.

variablesobject

Values for {{name}} placeholders in the subject and bodies, e.g. {"name": "Sara"}.

attachmentsobject[]

Files: { "filename", "content", "content_type" }, with content base64-encoded.

headersobject

Extra email headers, e.g. {"X-Campaign": "welcome"}.

Limits

Limit	Value
Recipients (`to` + `cc` + `bcc`)	1,000 per request
Attachments	10 files, 10 MiB total after decoding
Request body	16 MiB
Subject	998 characters, one line

Retry safely

Add an Idempotency-Key header with a unique value, such as your order ID. A retry with the same key returns the first response instead of sending the email again.

Terminal

-H "Idempotency-Key: order-1234-receipt"

Suppressed recipients

Addresses on your suppression list (hard bounces, complaints, unsubscribes) are removed before sending. If every to address is suppressed, the request fails with suppressed.

Response

202 Accepted

{
  "id": "eml_01HXKQ8B3N",
  "from": "Acme <hello@mail.acme.com>",
  "to": ["customer@example.com"],
  "subject": "Hello from SNDR",
  "status": "queued",
  "created_at": "2026-01-15T10:30:00Z"
}

status starts as queued and ends as delivered, bounced or failed. Read it with GET /v1/emails/{id}.