Why does the email API return 202 instead of 200?

Because sending is queued. Your key, sender, and template are checked inline, then the email waits in the queue so a slow provider never blocks your request. Idempotent replays can return 200.

How do I retry a send safely?

Send an Idempotency-Key header. It's unique per company and lasts 24 hours, so a retry returns the original result instead of sending a second copy.

What kind of API key do I need to send email?

A "Send + manage" key, the default in Settings → API & MCP. "Manage only" and "Read only" keys never send. A bad key gets 401; a valid key without permission gets 403.

Is there a Node or Python SDK?

Not yet. The examples here use plain HTTP, so they work in any language without one.

Is the email API a paid upgrade?

No. The REST API and the MCP server are included on every tier, free included.

Email API for transactional and marketing email.

One REST call sends an email and returns an ID you can trace to the inbox. The same API triggers your automations.

Start for free Read the API reference

✓Free to start. Unlimited contacts on every tier.

API trace

Email API

Accepted now. Observable later.

Request

POST /api/v1/emails

Authorization: Bearer aem_…

Idempotency-Key: welcome-8f21

{ "to": "[email protected]", "template": "welcome" }

202 Accepted

{ "id": "msg_7ca31", "status": "queued" }

POST/api/v1/emails

202Queued with message ID

Follow-upWebhook or GET by ID

Stable IDs make retries safeInspect

[ 01 / 06 ]Send

How do I send an email with the API?

POST a published template and its props. You get back an ID straight away.

202 Accepted. Retry with the same Idempotency-Key and it never sends twice.

Read the API reference

Terminal

curl -X POST https://sendandretain.com/api/v1/emails \
  -H "Authorization: Bearer $AEM_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-user_123" \
  -d '{ "to": "[email protected]", "template": "welcome", "props": { "firstName": "Jane" } }'

Accepted response

{ "id": "msg_7ca31", "status": "queued" }

[ 02 / 06 ]Trigger

How do I trigger an email automation from my app?

Record the event. Any automation listening for it enrols the contact.

Automations are created paused, so an event only sends email once you've turned its automation on.

Terminal

curl -X POST https://sendandretain.com/api/v1/events \
  -H "Authorization: Bearer $AEM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "name": "signup", "properties": { "plan": "trial" } }'

[ 03 / 06 ]Coverage

What does the email API include?

The whole system, not just a send endpoint.

Send

One recipient per email, from a published template, with an idempotency key.

Events

Record what users do and let automations react to it.

Contacts

Upsert one contact or import many, with attributes and tags.

Message status

Read any email by ID, from queued to delivered, bounced, or complained.

Signed webhooks

Delivery events pushed to your endpoint, signed and replayable.

Keys with roles

Send + manage, Manage only, or Read only. Only a key that can send can call the send endpoint.

[ 04 / 06 ]How it works

Why does the API return 202, not 200?

Because the email is queued, not sent, when the call returns. Setup mistakes still fail straight away; only the delivery work waits in the queue.

An unpublished template or unverified sender fails inline with a 4xx, not a surprise later.
Idempotency keys are unique per company and last 24 hours, so a retry never sends twice.
Unsubscribes, bounces, the pause switch, and the daily cap are checked right before it sends.
Webhooks are signed over the ID, timestamp, and body together.

Message trace

Email API

Receipt accepted

Details

delivered

To[email protected]

From[email protected]

Templatewelcome

Sourceapi

ProviderSend & Retain

Delivery events

RequestIdempotency key verified
SafetySuppression cleared
ProviderDelivery accepted
WebhookDelivered

Queued is not deliveredInspect

[ 05 / 06 ]Size

How much can the API do?

REST operations

Templates, automations, domains, contacts, segments, metrics, and more.

MCP tools

The same core for your AI agent, through the same send checks.

[ 06 / 06 ]Your stack

Questions people ask us

Everything else is in the docs.

Send your first email in one API call.

Create a Send + manage key, send a test, and follow its ID to the inbox.