Skip to Content
SendlySendly
API ReferenceEmails

Send a single transactional email

POST
/api/emails

Send a single transactional email. Accepts a template ID or an inline subject + body. An optional Idempotency-Key request header (1–255 chars, 24h TTL) ensures replay safety: the first request wins and a retry carrying the same key AND the same body replays its response. Reusing a key with a DIFFERENT body answers 422 IDEMPOTENCY_KEY_REUSED — a key names one request, so it is never silently served another request's result. A request with a new key is always a new send. Without an Idempotency-Key, identical content sent again within 24h is deduplicated.

Requires the emails:send scope — Send emails from your verified domains.

headerAuthorizationBearer <API Key>

API key authentication. Use a sk_* (FULL) or pk_* (SENDING_ONLY) key as the bearer token. Public keys (pk_*) are restricted to the email-send endpoints and the self-serve list subscribe/unsubscribe pair; every other endpoint — event tracking included — answers 403 for them. In scope terms (used by /api/v1/* operations): FULL keys hold every scope; SENDING_ONLY keys hold only emails:send.

Idempotency-Key?string

Replay-safety key (24h TTL). Reuse it only to retry the identical request.

Length1 <= length <= 255
application/json
  1. body

Body for POST /api/emails — send a single transactional email. Either template or subject+body is required.

to*||array<|>

One address, an object with an address and a name, or an array of either. to, cc and bcc together may name at most 50 recipients per request (per batch entry); a larger send must be split into a batch or several requests.

subject?string
Match^[^\r\n]*$
Length1 <= length <= 998
body?string
Length1 <= length
template?string
Formatuuid
subscribed?boolean
name?string

The sender's display name, shown beside the from address (Acme <hello@acme.com>). Used only when from does not carry a name of its own: a name inside the from object wins, and a send that names neither falls back to the template's from-name, then the project name. It is not the recipient's name; put that in to.

from?|
reply?string
Formatemail
headers?

Extra header fields to add to the message, as name → value. A name must be an RFC 5322 field-name (printable ASCII, no spaces or colons) and must not be one Sendly writes itself: From, Sender, Reply-To, To, Cc, Bcc, Subject, Date, Message-ID, MIME-Version, Content-Type, Content-Transfer-Encoding, Content-Disposition, Return-Path, DKIM-Signature, DomainKey-Signature, Received, Authentication-Results, List-Unsubscribe, List-Unsubscribe-Post, and any X-SES-, X-Sendly-, Resent-* or ARC-* header. A reserved name, in any letter case, fails validation and nothing is sent.

listUnsubscribe?string

Your own RFC 8058 one-click unsubscribe endpoint for this recipient. Sendly adds List-Unsubscribe: <url> and List-Unsubscribe-Post: List-Unsubscribe=One-Click, which is what lets Gmail, Yahoo and Apple Mail show their own Unsubscribe button. The mail client POSTs List-Unsubscribe=One-Click to this URL with no cookies and no confirmation page, so it must unsubscribe on that request alone and should carry a token that identifies the recipient. Must be https. Use it for opt-out mail you manage yourself, such as notifications; Sendly's own campaigns and workflows already carry one.

Formaturi
Lengthlength <= 2048
data?

Arbitrary JSON value (string, number, boolean, null, array, or object).

attachments?array<>
Itemsitems <= 10
tags?array<>
Itemsitems <= 10
cc?array<>

Addresses copied on the message: each receives it, and every recipient sees them in the Cc header. A copied address is a recipient of the message, so it counts like one: toward your usage and the monthly allowance, the daily and hourly sending limits, and the per-recipient price. An address on your suppression list is skipped (and not charged), and the message still goes to everyone else. Addresses are lowercased and de-duplicated; an address already in to, or a bcc already in cc, is not copied twice. When to names several addresses Sendly sends one message per to, and the copies are stored on, and delivered with, the FIRST to's message only, so a copied address receives one copy of the send, not one per to. That also means the copies depend on that first message: if it is cancelled, fails or is blocked, they are not sent. A message that carries copies has no open or click tracking, because an open or a click by a copied person cannot be told apart from the recipient's, and its subject and body must not use {{unsubscribeUrl}}, {{subscribeUrl}}, {{manageUrl}} or {{id}}: they resolve to the first recipient's own account links, so a copied address would hold the power to unsubscribe them. A send that does is refused with 422 validation_error and nothing is sent.

Itemsitems <= 50
bcc?array<>

Addresses blind-copied on the message: each receives it, and none is named in any header the other recipients can read. A copied address is a recipient of the message, so it counts like one: toward your usage and the monthly allowance, the daily and hourly sending limits, and the per-recipient price. An address on your suppression list is skipped (and not charged), and the message still goes to everyone else. Addresses are lowercased and de-duplicated; an address already in to, or a bcc already in cc, is not copied twice. When to names several addresses Sendly sends one message per to, and the copies are stored on, and delivered with, the FIRST to's message only, so a copied address receives one copy of the send, not one per to. That also means the copies depend on that first message: if it is cancelled, fails or is blocked, they are not sent. A message that carries copies has no open or click tracking, because an open or a click by a copied person cannot be told apart from the recipient's, and its subject and body must not use {{unsubscribeUrl}}, {{subscribeUrl}}, {{manageUrl}} or {{id}}: they resolve to the first recipient's own account links, so a copied address would hold the power to unsubscribe them. A send that does is refused with 422 validation_error and nothing is sent.

Itemsitems <= 50

Response Body

Email accepted / sent

application/json
  1. response

Successful response for POST /api/emails. data.emails[i].email is the queued email id for recipient i; poll GET /api/emails/{id} for its delivery status.

success*true
Value intrue
data*

Result of a send (executeSendEmail): one emails entry per recipient — a single request with an array to fans out to several — plus the send timestamp.

Example Request
curl -X POST 'https://api.sendly.now/api/emails' \  -H 'Content-Type: application/json' \  -d '{  "to": "user@example.com"}'
Example Response
{  "success": true,  "data": {    "emails": [      {        "contact": {          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "email": "user@example.com"        },        "email": "bd2f409a-4b68-41eb-89af-5a917d812282"      }    ],    "timestamp": "2019-08-24T14:15:22Z"  }}