Send transactional email
Send receipts, alerts and other one-to-one email from your own server, from any xstate mailbox you can send from.
Your server can send email from an xstate mailbox with one HTTP request. The message leaves from the same address people already write from, so replies land in that mailbox's inbox like any other mail.
Use it for email a person is waiting for: receipts, password resets, alerts, sign-in codes, order updates. It is not for newsletters or other bulk mail. The limits are the same as for mail you send by hand.
POST https://api.xstate.com/v1/emails1. Create a token
- In xstate, open Settings → API keys → Personal Tokens and click Create token.
- Give it a name, such as "Billing server", and choose the mailboxes it may send from. You can pick any mailbox
you can send from yourself: your own, or a shared one such as
billing@you have full access to. - Choose when it ends: never, or in 30 days, 90 days or 1 year.
- Copy the token. It starts with
xst_live_and is shown this once. xstate keeps only a hash of it, so nobody can show it to you again. If you lose it, create a new one.
A token is yours. It sends as you, and it can never do more than you can. See Tokens.
2. Send an email
Send the token in the Authorization header and the message as JSON.
curl https://api.xstate.com/v1/emails \
-H "Authorization: Bearer $XSTATE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "billing@acme.com", "name": "Acme Billing" },
"to": ["ann@example.com"],
"subject": "Your receipt",
"html": "<p>Thanks for your order. Your total was <b>$42.00</b>.</p>"
}'In Node.js:
const res = await fetch('https://api.xstate.com/v1/emails', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.XSTATE_TOKEN}`,
'Content-Type': 'application/json',
'Idempotency-Key': `receipt-${order.id}`,
},
body: JSON.stringify({
from: { email: 'billing@acme.com', name: 'Acme Billing' },
to: [order.email],
subject: 'Your receipt',
html: `<p>Thanks for your order. Your total was <b>${order.total}</b>.</p>`,
}),
})
const email = await res.json()
if (!res.ok) throw new Error(email.error.message)In Python:
import os, requests
res = requests.post(
"https://api.xstate.com/v1/emails",
headers={
"Authorization": f"Bearer {os.environ['XSTATE_TOKEN']}",
"Idempotency-Key": f"receipt-{order_id}",
},
json={
"from": {"email": "billing@acme.com", "name": "Acme Billing"},
"to": [customer_email],
"subject": "Your receipt",
"html": "<p>Thanks for your order.</p>",
},
)
res.raise_for_status()
email = res.json()The answer is 201 with the message as xstate recorded it:
{
"id": "em_8jnw4ta5wjaac2om7b18vp7y",
"status": "sent",
"from": { "email": "billing@acme.com", "name": "Acme Billing" },
"subject": "Your receipt",
"recipients": [
{ "email": "ann@example.com", "type": "to", "status": "sent", "detail": null, "updatedAt": "2026-11-16T13:43:53.884Z" }
],
"savedToSent": false,
"tags": {},
"createdAt": "2026-11-16T13:43:53.845Z"
}201 means the message is on its way. Keep the id if you want to check delivery later.
Fields
An address is either a string, "ann@example.com", or an object with a name, { "email": "ann@example.com", "name": "Ann Lee" }. A field xstate doesn't know is refused, so a misspelled name can't be ignored silently.
| Field | Required | What it is |
|---|---|---|
from | Yes | An address of a mailbox the token was given: its main address or one of its aliases. With a name, that name is shown to the recipient. |
to | Yes | 1 or more addresses. |
cc, bcc | No | More addresses. to, cc and bcc together hold at most 50, each address once. |
subject | Yes | Up to 998 characters. |
text | One of the two | The plain-text body, up to 1 MB. Left out, it is made from html. |
html | One of the two | The HTML body, up to 2 MB. |
replyTo | No | Up to 5 addresses replies should go to instead of from. |
attachments | No | Up to 20 files, 25 MB in total. See Attachments. |
headers | No | Up to 20 extra headers. Only names starting with X-, and List-Unsubscribe and List-Unsubscribe-Post. |
tags | No | Up to 10 labels of your own, such as { "kind": "receipt" }. They are not sent; you can filter the send log by them. |
saveToSent | No | true puts a copy in the mailbox's Sent folder. Defaults to false. |
Showing the message in Sent
By default nothing is added to the mailbox: a few thousand receipts would bury the conversations people have there. The message is still recorded in the send log.
Send "saveToSent": true when the message is part of a conversation someone will follow in xstate. It then sits
in the Sent folder exactly like mail written by hand, and a reply appears under it.
Replies always arrive in the mailbox's inbox, whichever you choose.
Attachments
Each file is an object with its name, its type and its content in base64:
{
"attachments": [
{ "name": "invoice.pdf", "type": "application/pdf", "content": "JVBERi0xLjQK..." },
{ "name": "logo.png", "type": "image/png", "content": "iVBORw0KGgo...", "contentId": "logo" }
]
}Give an image a contentId to show it inside the HTML with <img src="cid:logo">. Other files appear as
attachments.
Files go through the same checks as attachments added in xstate. Programs and other
risky file types are refused with attachment_blocked.
Safe retries
Networks fail. If a request times out, you can't tell whether the email went out. Send an Idempotency-Key
header with a value that is unique to the message, such as receipt- and the order number, and retry with the
same key:
- The first request sends the email.
- A retry with the same key and the same body sends nothing. It returns the first answer again, with status
200and the headerIdempotent-Replay: true. - The same key with a different body is refused with
409 idempotency_conflict.
A key is remembered for 24 hours and can be up to 255 characters.
Check delivery
GET https://api.xstate.com/v1/emails/em_8jnw4ta5wjaac2om7b18vp7yIt returns the same object as when you sent it, with the status of each recipient kept up to date:
| Recipient status | What it means |
|---|---|
queued | Being sent right now. |
sent | Handed over for delivery. Most mail stays here for a few seconds. |
delivered | The recipient's mail server accepted it. Mail to another xstate address is delivered at once. |
bounced | It could not be delivered. detail holds the reason the other server gave. |
complained | The recipient marked it as spam. |
suppressed | Not sent. The address bounced before, or marked your mail as spam. |
The message's own status sums them up: queued, sent, then delivered once every recipient has it.
bounced or complained when that happened for every recipient, and partial when it happened for some.
xstate does not track opens or clicks, and adds nothing to your email to do so.
Suppressed addresses
xstate will not send to an address that hard-bounced before, or to someone who marked your organization's mail as spam. Sending to them again is what gets a sender blocked.
If some recipients of a message are suppressed, the rest still get it, and the suppressed ones come back with
that status. If all of them are, or everyone in to is, nothing is sent and the answer is
422 all_recipients_suppressed.
The send log
GET https://api.xstate.com/v1/emailsLists what you sent through the API, newest first, as { "emails": [...], "nextCursor": "..." }. A token sees
messages its owner sent from the mailboxes that token can use. Messages are kept for 30 days. The log holds the
subject, the addresses and the statuses, never the body or the attachments.
| Query | What it does |
|---|---|
limit | 1 to 100 messages a page. Defaults to 25. |
cursor | The nextCursor of the page before, to get the next one. null means there are no more. |
status | Only messages with at least one recipient in this status, for example status=bounced. |
from | Only messages sent from this address. |
tag.<name> | Only messages with this tag, for example tag.kind=receipt. |
Limits
API mail and mail sent by hand share the same limits, counted together:
| Limit | Amount |
|---|---|
| Recipients on one message | 50 |
| Attachments on one message | 20 files, 25 MB in total |
| Outside recipients per mailbox | 100 an hour, 500 a day |
| Outside recipients per organization | 400 an hour, 2,000 a day |
| Requests per token | 300 a minute |
An outside recipient is an address that isn't on xstate. Mail between xstate addresses isn't counted.
Past a sending limit the answer is 429 send_limit_reached, with details.retryAfter: the number of seconds
after which there is certainly room again. Because the limits are shared, a script that uses up a mailbox's hour
also stops the people in that mailbox from sending until it has passed.
Bounces and spam complaints
Mail you send through the API counts toward the mailbox's reputation like all its other mail. If too much of a mailbox's recent mail bounces or is marked as spam, xstate pauses all sending from that mailbox: through the API, in xstate and from mail apps. Reading mail keeps working. If it is true of the whole organization, every mailbox is paused.
The API then answers 403 sending_suspended, and the organization's owners and admins get an email that names
the tokens that sent from the mailbox recently. To avoid it, send only to addresses people gave you, and stop
sending to addresses that bounce.
Errors
Every error has the same shape, with a code your code can check and a message for people:
{ "error": { "code": "from_not_allowed", "message": "This token can’t send from sales@acme.com. Use an address of a mailbox the token was given." } }| Status | Code | What happened, and what to do |
|---|---|---|
| 400 | invalid_input | A field is missing or wrong. The message says which. |
| 400 | invalid_json | The body isn't a JSON object. |
| 401 | invalid_token | The token is missing, mistyped, revoked or expired. Create a new one. |
| 403 | from_not_allowed | from isn't an address of a mailbox this token was given. |
| 403 | no_mailboxes | You can no longer send from any of the token's mailboxes. Get access back, or give the token another mailbox. |
| 403 | api_tokens_disabled | An owner or admin turned API tokens off for the organization. |
| 403 | sending_suspended | The mailbox or organization is paused for bounces or complaints. |
| 403 | attachment_blocked | An attachment is a file type xstate doesn't send. |
| 404 | email_not_found | No such message, or it isn't one this token can see. |
| 409 | idempotency_conflict | This Idempotency-Key was used for a different message. |
| 409 | request_in_progress | An earlier request with this Idempotency-Key is still being sent. Retry in a few seconds. |
| 413 | attachments_too_large | The attachments are over 25 MB in total. |
| 422 | all_recipients_suppressed | Every recipient is suppressed. Nothing was sent. |
| 429 | send_limit_reached | A sending limit was reached. Wait details.retryAfter seconds. |
| 429 | rate_limited | Too many requests. Wait a minute. |
A 5xx answer or a timeout means xstate couldn't tell you what happened. Retry with the same Idempotency-Key.
Tokens
- Keep a token on your server. Put it in your server's secrets or environment. Never put it in a website, a mobile app or a repository: anyone who has it can send email as you from its mailboxes.
- It only sends. A token can't read mail, and can't be used anywhere else in xstate.
- It follows your access. If you lose access to one of its mailboxes, the token can't send from that mailbox from the next request on. With no mailbox left it stops working, and starts again if access comes back.
- It ends when you leave. If you leave the organization or are removed, your tokens are revoked for good, and the owners and admins are told which ones stopped. Someone else then creates a token for the same mailbox.
- Revoking is immediate. Revoke a token in Settings → API keys → Personal Tokens. You can rename a token or change its mailboxes there too, without changing the token itself.
- To replace a token, create a new one, switch your server to it, then revoke the old one.
- Owners and admins see every member's tokens, can revoke any of them, and can turn API tokens off for the whole organization. They never see a token itself.
- You get an email when a token is created on your account, and a week before one ends. You can have 20 tokens.
More on how tokens are stored and checked: Security.