Documentation
Transactional email API documentation
v1A transactional email API for UK senders — send receipts, password resets, and welcome messages from your own domain, with full delivery tracking. Sending runs through London (eu-west-2).
Send email
POST /v1/emails
Send a single transactional email.
Send batch
POST /v1/emails/batch
Queue up to 100 emails in one request.
Retrieve email
GET /v1/emails/:id
Retrieve the current status and metadata of a sent email.
List emails
GET /v1/emails
Page through every email you've sent, newest first.
Suppressions
GET/POST/DELETE /v1/suppressions
See, add, and release the addresses we refuse to mail.
Manage the account
GET/POST/DELETE /v1/domains · /v1/api-keys · /v1/webhooks
Add domains, mint keys and register endpoints from a script.
Domains & DNS
Verify a sending domain: DNS records, DMARC, and troubleshooting.
Errors
Error types, HTTP status codes, and how to handle them.
Node SDK
Install and use the yourmail TypeScript client.
Webhooks
Receive real-time delivery events from YourMail via signed HTTP webhooks.
OpenAPI spec
OpenAPI 3.1
The whole API as one machine-readable file — generate a client in any language, or import it into Postman.
For AI agents
llms.txt
The whole API in one plain-text file, written to be pasted into an agent's context — auth, endpoints, limits, error semantics and the rules for integrating it.
How a message travels
Five steps, and knowing them makes the rest of these pages read as one system rather than nine endpoints.
You verify a domain
Add the DNS records we generate and the domain moves to verified. From then on any local part on it sends — hello@, receipts@, no-reply@ — with no mailbox needing to exist behind the address. Before you have a domain, test mode sends from a shared address to your own inbox so you can wire the whole integration up first.
You call the send endpoint
One POST, or the zero-dependency SDK. The request is validated, the sending domain is checked against the ones you have proved you control, suppressed recipients are refused, and your quota is charged. Pass an idempotency key and a retry cannot send twice.
The message is queued, then dispatched
The API answers as soon as the message is accepted, with an id. Dispatch happens just behind it, paced against the account's sending rate — so a burst is smoothed rather than rejected. A message given a future scheduledAt waits until then and can be cancelled up to the moment it goes.
Delivery events arrive
Amazon SES reports back what happened — delivered, bounced, complained, opened, clicked, delayed. Each one updates the message's status, and a hard bounce or a complaint writes the address to your suppression list so the next send to it is refused rather than damaging your reputation.
Your app is told
Every status change fans out to your webhook endpoints as a signed POST, with exponential-backoff retries. If you would rather poll, the same information is on the retrieve and list endpoints. Either way there is no state your application has to reconstruct by guessing.
Which page answers what
The grid above is organised by endpoint. Most questions are not, so here is the same set organised by what you are trying to find out.
- I want to send my first email in five minutes.
- Start here — it goes from an API key to a delivered message without needing DNS first. Quickstart.
- My mail is going to spam, or bouncing.
- SPF, DKIM and DMARC alignment, bounce handling, the Gmail and Yahoo bulk sender rules and one-click unsubscribe are all in the deliverability guides.
- How many can I send, and what happens when I hit the limit?
- Quotas, the daily caps, the new-account ramp and how to have them lifted are on Limits & account review.
- Why did this request fail?
- Every error type, its HTTP status and what to do about it — and every error body carries a link back to its own entry — on Errors.
- I am wiring this into a framework.
- Working integrations for Next.js, Node and Express, React Email and Convex are in the framework guides.
- I want an agent to write the integration.
- Point it at llms.txt.