Send an email

Send HTML, plain text or both, to one or many recipients.

curl -X POST 'https://api.sendsend.email/v1/emails' \
  -H "Authorization: Bearer $SENDSEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "from": "Acme <hello@mail.example.com>",
  "to": [
    "delivered@example.com"
  ],
  "subject": "Welcome to Acme",
  "html": "<p>Thanks for signing up!</p>",
  "text": "Thanks for signing up!",
  "tags": {
    "application_reference": "signup_123"
  }
}'

Fields

Field	Notes
`from`	An address or `Name <address>`. The domain must be verified in the same project for live sends.
`to`	A list of addresses. Up to 50 recipients in total across to, cc and bcc.
`cc`	Optional list. Visible to all recipients.
`bcc`	Optional list. Hidden from other recipients.
`reply_to`	Optional. Where replies go.
`subject`	Up to 998 characters, no line breaks.
`html`, `text`	Send both when you can. A plain-text part helps deliverability.
`tags`	Up to 10 of your own key/value references, such as an order id. They come back on webhooks.

Always send a plain-text part

Messages with both html and text score better with mailbox providers and display correctly in every client.

Retries

Add an Idempotency-Key so a retry can never deliver twice. See Idempotency.

Send later

Add scheduled_at with an ISO 8601 time that includes an offset, from now up to 30 days ahead. The message waits, holding its quota, and goes out at that time.

{
  "from": "Acme <hello@mail.acme.com>",
  "to": ["maria@example.com"],
  "subject": "Your trial ends tomorrow",
  "text": "...",
  "scheduled_at": "2026-10-08T09:00:00-04:00"
}

Until its time, you can reschedule or cancel it, and cancelling gives the quota back. The account, domain and suppression checks run again when it is actually sent, so a message scheduled before your account is paused does not go out afterward.

Attachments

Add up to 10 files in attachments, each with a filename and base64 content (and optionally content_type). All files together can be up to 10 MB.

"attachments": [
  { "filename": "invoice-2041.pdf", "content": "JVBERi0xLjQK..." }
]

Instead of content you can give a path, an https address we download for you. Redirects are not followed, private network addresses are refused, and the file counts toward the same 10 MB.

Images inside the message

Give an attachment a content_id and show it inline with <img src="cid:logo"> in your HTML.

"html": "<img src='cid:logo' alt='Acme'>",
"attachments": [
  { "filename": "logo.png", "path": "https://acme.com/logo.png", "content_id": "logo" }
]

Executables and scripts (.exe, .js, .bat and similar) are refused, because mailbox providers block them.
We keep the file only until the message has been handed to the mail provider, then delete it. The name, type and size stay on the message.
Attachments are not available in a batch.

Custom headers and unsubscribe links

Add up to 20 of your own headers with headers, for example a reference id. Headers SendSend sets itself (From, To, Subject, DKIM and so on) cannot be overridden.

"headers": {
  "X-Entity-Ref-ID": "order-1234",
  "List-Unsubscribe": "<https://acme.com/unsubscribe/abc>, <mailto:unsubscribe@acme.com>",
  "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
}

An unsubscribe header is a good idea for any email a person might not expect, such as receipts and notifications. Mailbox providers show an Unsubscribe button instead of a spam button. It must use https or mailto, and List-Unsubscribe-Post only works together with List-Unsubscribe. Unsubscribe requests need to be honoured: add the address to your suppression list.

Sending many at once

Use the batch endpoint to queue up to 100 messages in one request. Every message is checked first, so one invalid message rejects the whole request before anything is queued. After that, each message succeeds or fails on its own and the response says which.

Suppressed recipients

Addresses that bounced permanently or complained are suppressed automatically. A message to a suppressed address is skipped, and a request where every recipient is suppressed is rejected with recipient_suppressed.

Attachments

Attachments are not supported yet.

See the full Send an email reference.