Skip to Content
SendlySendly
API ReferenceEmails

Send a transactional email

POST
/api/v1/emails

Send one transactional email and receive its delivery status in the same response. Accepts a template id or an inline subject + body.

This is the send to reach for when you need to know what happened. The legacy POST /api/emails answers with row ids and no status, so telling an accepted send from a refused one costs a second request; here the receipt carries status, and from reports the sender actually used — which is worth reading, since a template may have supplied it.

Exactly ONE recipient. A single receipt cannot describe a fan-out, so to takes one address: use cc/bcc to copy others on the same message, and POST /api/emails/batch to send different ones.

202 Accepted is the success answer, and PENDING the usual status: the message is queued for the sending pipeline, not yet handed to the provider. Later states (DELIVERED, BOUNCED, …) arrive by webhook.

An optional Idempotency-Key header (1–255 chars, 24h TTL) makes a retry safe: the first request wins and a retry carrying the same key AND body replays its receipt. Reusing a key with a different body answers 422 rather than serving 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/v1/emails. Either template or subject+body is required, and to names exactly one recipient; copy others with cc and bcc. Errors are RFC 9457 application/problem+json.

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. This send has exactly one to, so there is one message and the copies are delivered with it: 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. This send has exactly one to, so there is one message and the copies are delivered with it: 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
to*|

The single recipient. Use cc/bcc to copy others on the same message. 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.

Response Body

Email queued

application/json
  1. response

Receipt for a single transactional send.

id*string

The Email row this send created. Quote it in support requests.

Formatuuid
status*string

Delivery status at the moment of the response — PENDING for a send the worker has not picked up yet, which is the usual answer. Later states arrive via webhooks, not here.

Value in"PENDING""SENDING""SENT""DELIVERED""RECEIVED""BOUNCED""FAILED""REJECTED""RENDERING_FAILURE""DELIVERY_DELAY""CANCELLED"
to*string

The recipient the message was queued for.

Formatemail
from*string

The sender actually used. Worth reading rather than assuming: it is resolved server-side and may come from the template when the request named none.

Formatemail
Example Request
curl -X POST 'https://api.sendly.now/api/v1/emails' \  -H 'Content-Type: application/json' \  -d '{  "to": "user@example.com"}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "PENDING",  "to": "user@example.com",  "from": "user@example.com"}