Email API
Send transactional and promotional email with one POST request, then look each email up to see whether it was delivered, bounced, opened or clicked.
/emails/Send email
Send an email to up to 50 recipients. Each recipient becomes its own email and costs 1 email credit. Every check runs before anything is charged. Returns 201 Created with one entry per recipient: queued, pending_balance if the project is out of credits and waiting on an auto top-up, or suppressed if the recipient can't be reached.
Body Parameters
fromstringrequiredThe sender, as a bare address such as [email protected] or with a display name, such as Acme <[email protected]>. The address's domain must be an active sending domain on this project, matched exactly. The display name is up to 100 characters, with no line breaks, @ < > " \ or =?. The separate from_name and from_address fields are refused with a 400.
tostring | string[]requiredOne recipient address, or an array of up to 50. Plain addresses only, so no display names and no comma-separated string. Each recipient is sent its own email and is stored lower-cased.
subjectstringrequiredUp to 998 characters, with no line breaks.
htmlstringrequiredThe HTML body.
textstringThe plain-text part. Leave it out and Sailup derives one from html.
reply_tostringA plain address for replies. Leave it out for no Reply-To.
typestringrequiredtransactional or promotional. There is no default. See Transactional and promotional.
Response Fields
countintegerHow many emails were created, one per recipient.
total_quantityintegerCredits the request cost, the sum of every email's quantity.
messages[].idstringThe email's ID. Use it with Get an email, and to match the data.id of its webhook events.
messages[].fromstringWhat the recipient sees: the display name and address, or the bare address.
messages[].statusstringqueued on a normal send, pending_balance while waiting for an auto top-up, or suppressed when the recipient bounced, complained or, for promotional email, unsubscribed before.
messages[].quantityintegerCredits this email cost: 1, or 0 when it was never charged or was refunded. A pending_balance email shows 1 and is charged when the top-up lands.
messages[].failure_codestring | nullWhy the email failed. Set only when status is failed. See Failure codes.
{
"from": "Acme <[email protected]>",
"to": "[email protected]",
"subject": "Your Acme login code",
"html": "<p>Your login code is <strong>482913</strong>. It expires in 10 minutes.</p>",
"text": "Your login code is 482913. It expires in 10 minutes.",
"reply_to": "[email protected]",
"type": "transactional"
}{
"count": 1,
"total_quantity": 1,
"messages": [
{
"id": "ab8527d5-aec2-4240-8b27-34a14eb547ec",
"from": "Acme <[email protected]>",
"to": "[email protected]",
"reply_to": "[email protected]",
"subject": "Your Acme login code",
"type": "transactional",
"status": "queued",
"quantity": 1,
"failure_code": null,
"created_at": "2026-11-03T01:02:41.286650Z",
"updated_at": "2026-11-03T01:02:41.286655Z"
}
]
}Transactional and promotional
Every email declares a type. It decides which recipients can be reached, how many emails the project can send in a day, and whether Sailup adds an unsubscribe link. Both types cost the same: 1 credit per email, with no segments.
transactionaltypeFor login codes, receipts and password resets. There is no unsubscribe footer. Refused after a hard bounce, or after a spam complaint about an earlier transactional email. Unsubscribes do not block it. Keeps sending when the domain's promotional mail is paused. Capped at 3,000 a day per project.
promotionaltypeFor offers, newsletters and announcements. Sailup appends an unsubscribe footer and adds one-click List-Unsubscribe headers when it sends. The body you sent is stored unchanged. Refused after the recipient unsubscribed, hard-bounced or complained. Capped at 1,000 a day per project.
Daily caps reset at midnight UTC. A send over the cap is rejected with email_daily_limit_reached. Contact support if your project needs a higher cap.
const res = await fetch("https://api.sailup.io/v1/emails/", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.SAILUP_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: "Acme <[email protected]>",
to: batch.map((customer) => customer.email), // up to 50
subject: "Our November offers",
html: offerHtml,
type: "promotional",
}),
});
if (!res.ok) {
const { error } = await res.json();
// Promotional mail is paused on this domain. Transactional still sends.
if (error === "promotional_sending_paused") retryLater(batch);
} else {
const { messages } = await res.json();
// Unsubscribed, bounced or complained: not sent and not charged.
messages
.filter((email) => email.status === "suppressed")
.forEach((email) => markUnreachable(email.to));
}Sending domains
Every email is sent from a domain on your project. Add one under Email domains in the dashboard, add the DNS records it shows you, and wait for it to turn active. Domains are managed in the dashboard only. There is no API endpoint for them.
The from domain is matched exactly. [email protected] needs mail.acme.com registered, and acme.com does not cover it. A domain that is missing or still pending returns domain_not_verified.
Sailup can pause a domain whose mail is causing delivery problems. If only its promotional mail is paused, promotional sends return promotional_sending_paused and transactional mail keeps going. If the whole domain is suspended, every send returns domain_suspended.
Opens and clicks are recorded only after the domain's optional tracking record, a go. CNAME on your domain, is verified. Without it, an email's events stop at delivery, bounce and complaint.
{
"error": "domain_not_verified",
"message": "The sending domain has not been verified."
}/emails/List emails
List the emails this project has sent, newest first. Filters combine, so ?status=bounced&type=promotional returns promotional bounces. An unknown filter value returns 400 rather than an empty list. Message bodies are never returned.
Query Parameters
statusstringOnly emails with this status. See Statuses.
typestringtransactional or promotional.
pageintegerPage number to return. Defaults to 1.
page_sizeintegerNumber of emails per page. Defaults to 30, maximum 1000.
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "9d48733d-8a11-4330-ad11-405ae532f14c",
"from": "Acme <[email protected]>",
"to": "[email protected]",
"reply_to": "",
"subject": "October newsletter",
"type": "promotional",
"status": "bounced",
"quantity": 1,
"failure_code": null,
"created_at": "2026-11-03T01:02:42.975671Z",
"updated_at": "2026-11-03T01:02:42.975674Z"
}
]
}/emails/{email_id}/Get an email
Get one email by its ID, with everything that has happened to it since, newest first. Returns 404 for an unknown ID or an email that belongs to another project.
Path Parameters
email_idstringrequiredThe email's id, from the send response, the list, or a webhook's data.id.
Response Fields
quantityintegerCredits this email cost, or 0 when it was never charged or was refunded.
failure_codestring | nullWhy the email failed, when status is failed.
events[].eventstringOne of delivered, bounced, complained, opened, clicked or unsubscribed. unsubscribed is recorded when a promotional recipient uses the unsubscribe link.
events[].urlstringThe link that was clicked, for clicked. Empty otherwise.
events[].ip_addressstring | nullKnown for opens and clicks. null otherwise.
events[].user_agentstringThe recipient's mail client or browser. Empty when unknown.
{
"id": "0423d821-edcd-4207-9004-07323bf06229",
"from": "Acme <[email protected]>",
"to": "[email protected]",
"reply_to": "[email protected]",
"subject": "Your Acme login code",
"type": "transactional",
"status": "delivered",
"quantity": 1,
"failure_code": null,
"created_at": "2026-11-03T01:02:43.084141Z",
"updated_at": "2026-11-03T01:02:43.084144Z",
"events": [
{
"id": "4d1c21cc-a318-4704-a856-866b3b590f22",
"event": "clicked",
"url": "https://acme.com/account",
"ip_address": "102.176.65.12",
"user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_1 like Mac OS X)",
"created_at": "2026-11-03T01:02:43.084590Z"
},
{
"id": "c817c237-a771-4543-95c6-875f412904be",
"event": "opened",
"url": "",
"ip_address": "102.176.65.12",
"user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_1 like Mac OS X)",
"created_at": "2026-11-03T01:02:43.084499Z"
},
{
"id": "9e77bd63-bcde-4cf0-bce2-cb4648782ce4",
"event": "delivered",
"url": "",
"ip_address": null,
"user_agent": "",
"created_at": "2026-11-03T01:02:43.084341Z"
}
]
}Statuses
An email moves forward through these values. The outcomes Sailup can send as a webhook are listed on the Webhooks page.
pending_balancestatusAccepted while the project waits for an auto top-up. Not charged yet. It is charged and sent when the top-up lands.
queuedstatusCharged and waiting to be handed off. An email still queued 23 hours later, for example because its domain lost verification, becomes failed.
sentstatusHanded off for delivery, with no outcome yet.
deliveredstatusAccepted by the recipient's mail server. It can still change to bounced on a late bounce, or to complained.
bouncedstatusA hard bounce. The address is suppressed for all future email from the project.
complainedstatusThe recipient marked it as spam. A complaint about a transactional email suppresses the address for all email. A complaint about a promotional one suppresses it for promotional email.
failedstatusCould not be sent. failure_code says why. An email that fails before Sailup hands it to the mail server is refunded automatically, so its quantity becomes 0.
suppressedstatusNot sent, because the recipient was on the suppression list, either when you sent it or when Sailup tried later. Never charged, or refunded, so its quantity is 0.
pending_balance → queued → sent → delivered
↘ bounced
↘ complained
↘ failed
↘ suppressedFailure codes
A failed email carries a failure_code in its response, the list, Get an email and its email.failed webhook. It is null for every other status.
expiredrefundedNot sent within 23 hours, for example because its domain lost verification.
promotional_pausedrefundedA promotional email from a domain whose promotional mail was paused before it went out.
domain_unavailablerefundedThe sending domain was removed or paused before it went out.
rejectedchargedThe recipient's mail server refused it.
Errors
A rejected send is never charged and never stored. Errors come in two shapes. Business rules return an error code you can branch on. Field validation returns Validation failed with an errors list. Every validation message starts with its field name, such as to: This field is required. A suppressed recipient is not an error: it comes back in the response with a status of suppressed.
domain_not_verified400The from domain is not registered on this project, or is not active yet.
domain_suspended400Sailup paused all sending from the from domain.
promotional_sending_paused400A promotional send while the domain's promotional mail is paused. Transactional mail still sends.
email_daily_limit_reached400The project already sent today's cap for this type.
insufficient_balance400No email credits and no email auto top-up switched on.
invalid_email_address400An address that is not a plain address, such as one with a quoted local part. The message names the field.
invalid_from_name400The display name in from is longer than 100 characters or contains a line break, @, =? or one of < > " \.
invalid_subject400subject contains a line break or another control character.
A missing, invalid or revoked API key, or a suspended account, returns 401 Unauthorized.
{
"error": "domain_not_verified",
"message": "The sending domain has not been verified."
}{
"message": "Validation failed",
"errors": [
"subject: Use 998 characters or fewer."
]
}