Skip to Content
xstate

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/emails

1. Create a token

  1. In xstate, open Settings → API keys → Personal Tokens and click Create token.
  2. 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.
  3. Choose when it ends: never, or in 30 days, 90 days or 1 year.
  4. 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.

FieldRequiredWhat it is
fromYesAn 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.
toYes1 or more addresses.
cc, bccNoMore addresses. to, cc and bcc together hold at most 50, each address once.
subjectYesUp to 998 characters.
textOne of the twoThe plain-text body, up to 1 MB. Left out, it is made from html.
htmlOne of the twoThe HTML body, up to 2 MB.
replyToNoUp to 5 addresses replies should go to instead of from.
attachmentsNoUp to 20 files, 25 MB in total. See Attachments.
headersNoUp to 20 extra headers. Only names starting with X-, and List-Unsubscribe and List-Unsubscribe-Post.
tagsNoUp to 10 labels of your own, such as { "kind": "receipt" }. They are not sent; you can filter the send log by them.
saveToSentNotrue 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 200 and the header Idempotent-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_8jnw4ta5wjaac2om7b18vp7y

It returns the same object as when you sent it, with the status of each recipient kept up to date:

Recipient statusWhat it means
queuedBeing sent right now.
sentHanded over for delivery. Most mail stays here for a few seconds.
deliveredThe recipient's mail server accepted it. Mail to another xstate address is delivered at once.
bouncedIt could not be delivered. detail holds the reason the other server gave.
complainedThe recipient marked it as spam.
suppressedNot 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/emails

Lists 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.

QueryWhat it does
limit1 to 100 messages a page. Defaults to 25.
cursorThe nextCursor of the page before, to get the next one. null means there are no more.
statusOnly messages with at least one recipient in this status, for example status=bounced.
fromOnly 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:

LimitAmount
Recipients on one message50
Attachments on one message20 files, 25 MB in total
Outside recipients per mailbox100 an hour, 500 a day
Outside recipients per organization400 an hour, 2,000 a day
Requests per token300 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." } }
StatusCodeWhat happened, and what to do
400invalid_inputA field is missing or wrong. The message says which.
400invalid_jsonThe body isn't a JSON object.
401invalid_tokenThe token is missing, mistyped, revoked or expired. Create a new one.
403from_not_allowedfrom isn't an address of a mailbox this token was given.
403no_mailboxesYou can no longer send from any of the token's mailboxes. Get access back, or give the token another mailbox.
403api_tokens_disabledAn owner or admin turned API tokens off for the organization.
403sending_suspendedThe mailbox or organization is paused for bounces or complaints.
403attachment_blockedAn attachment is a file type xstate doesn't send.
404email_not_foundNo such message, or it isn't one this token can see.
409idempotency_conflictThis Idempotency-Key was used for a different message.
409request_in_progressAn earlier request with this Idempotency-Key is still being sent. Retry in a few seconds.
413attachments_too_largeThe attachments are over 25 MB in total.
422all_recipients_suppressedEvery recipient is suppressed. Nothing was sent.
429send_limit_reachedA sending limit was reached. Wait details.retryAfter seconds.
429rate_limitedToo 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.

On this page