Developer quickstart
A REST API and an MCP server for sending, receiving, reading threads, and managing domains and mailboxes. Both run on your own server.
Give this app email in 10 minutes once your server is running
One MCP call sets up everything an app needs: the app, its key, a subdomain that sends and receives with no DNS work, a signed webhook, an inbox for one of your users and one for your agent, and a first conversation between the two. Your coding agent can run every step below by itself. The same call fits an app with users, an AI agent, or an assistant working for one person: end_user_id names whoever the inbox is for.
You need your server running (Install eMailPlane), a sign-in to its dashboard, Docker, Node 22 or later and the sandbox folder from your beta invite. The computer you run these steps on must reach your server's address: a server that connects through eMailPlane's network answers only on itself (what your server exposes).
Before minute 0: build the setup tool
The setup tool is the eMailPlane MCP server, run on your computer so your app's key is saved there and nowhere else. It is not published as a ready image yet, so build it once, from the top of the sandbox folder:
docker build -t emailplane-mcp:local apps/mcp
Minute 0: a setup key
In your server's dashboard, open Apps, then Setup grants. Create one that may create apps and issue keys, with the key permissions send, read:inbox, manage:inboxes, manage:mailboxes and manage:webhooks. It expires by itself. Use your own server's address below, then paste the setup key at the silent prompt, so it is not shown and not kept in your shell history.
export EMAILPLANE_API_URL=https://mail.example.com
read -rs EMAILPLANE_SETUP_KEY && export EMAILPLANE_SETUP_KEY
Minute 1: a private folder for the key
The tool saves your app's key and webhook secret here, never in its answer.
mkdir -p "$HOME/.emailplane/keys" && chmod 700 "$HOME/.emailplane/keys"
Minute 2: connect the MCP server
For this step the MCP server runs on your machine, so the key lands in your folder. In Claude Code, from the same shell:
claude mcp add emailplane-setup -- sh -c 'exec docker run --rm -i --user "$(id -u):$(id -g)" -e EMAILPLANE_API_URL -e EMAILPLANE_API_KEY="$EMAILPLANE_SETUP_KEY" -e EMAILPLANE_KEY_DIR=/keys -v "$HOME/.emailplane/keys:/keys" emailplane-mcp:local'
The saved command holds no key: it reads the setup key from your shell each time the server starts, so start Claude Code from this shell. Any other MCP client runs the same docker run as a local (stdio) server.
Minute 3: one call
Ask your agent: "Use the emailplane-setup server to make this tool call. Then show me each step and where it saved the files. Never print a key." The call:
{
"tool": "app_bootstrap",
"arguments": {
"app": "acme",
"webhook_url": "https://acme.example.com/hooks/email"
}
}
app is your app's name (lowercase letters, digits and dashes). webhook_url is the https address where your app takes webhooks. Optional: env (dev, staging or prod), end_user_id, agent_id and subdomain.
Minute 4-6: what it does
| Step | What it makes | When it is already there |
|---|---|---|
app | Your app, with its own sending address | Found by name and environment |
key | A key with the five permissions above, saved in your folder first and switched on after | Read back from its file |
domain | acme on our shared zone, sending and receiving with no DNS work | Found by name |
webhook | A signed webhook to your webhook_url; its secret is saved in your folder | Found by address |
end_user_inbox | An inbox for one of your users (demo-user) | The same inbox, same address |
agent_inbox | An inbox for your agent (agent) | The same inbox, same address |
conversation | Your agent writes to your user's inbox and the user replies, in one thread | Found by its Idempotency-Key, never sent twice |
The answer marks each step created or existing and lists the two addresses and the two files. It never contains a key or a secret. A new shared-zone subdomain sends nothing until it has a sending allowance, and it says so. If your plan has no shared-zone subdomain, that step says refused and the rest still runs: the inboxes use your app's own address.
Minute 7: give your app its key
KEY_FILE=$(ls -t "$HOME"/.emailplane/keys/app-credential-*.json | head -1)
export EMAILPLANE_API_KEY=$(node -e 'console.log(JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).token)' "$KEY_FILE")
HOOK_FILE=$(ls -t "$HOME"/.emailplane/keys/webhook-secret-*.json | head -1)
export EMAILPLANE_WEBHOOK_SECRET=$(node -e 'console.log(JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).secret)' "$HOOK_FILE")
Put both in your app's secret store, never in a file you commit. Keep the folder out of shared backups.
Minute 8: read the conversation
curl -sS "$EMAILPLANE_API_URL/v1/inbound/threads" -H "Authorization: Bearer $EMAILPLANE_API_KEY"
GET /v1/inbound/threads lists the thread: your agent's message and your user's reply. Each reply also reaches your webhook as a signed message.received event.
Minute 9: run it again
Make the same call again. Every step says existing and changed is false: nothing is made twice and nothing is sent twice. If a run stopped part-way (a dropped connection, a closed laptop), the same call finishes it from where it stopped.
Minute 10: hand it to your coding agent
Paste this into Claude Code, Codex, Cursor or any coding agent working in your app's repository:
Add email to this app with eMailPlane.
Read $EMAILPLANE_API_URL/llms.txt (my server's own guide) before writing code.
The API address is in the EMAILPLANE_API_URL environment variable and the key
is in EMAILPLANE_API_KEY. Never print, log or commit the key.
1. Call GET $EMAILPLANE_API_URL/v1/tokens/self and show me the key's scopes.
2. Add one sendEmail() helper that POSTs to /v1/emails and sends an
Idempotency-Key derived from the business event (for example the order id),
so retries never send twice.
3. Give each of my users their own inbox with
PUT /v1/ext/end-users/{my user id}/inbox; it returns the same inbox every time.
4. Before sending to a list, call POST /v1/sends/preflight and respect its answer.
5. Read replies with GET /v1/inbound, paging with next_cursor, and verify
webhooks with EMAILPLANE_WEBHOOK_SECRET.
6. Handle errors by their stable "code"; each error also says whether a retry
can work ("retryable") and whether a person must act ("human_action").
Ask me before sending to any address that isn't mine.
Installing eMailPlane on your server, by hand or by your coding agent, is one command: see Install eMailPlane.
API basics
Your apps call the API on your own server, at EMAILPLANE_API_URL. Every request carries a bearer token with only the scopes it needs.
What your server exposes
| Where | What | Who can reach it |
|---|---|---|
https://mail.<your-domain> | /v1/* (the API) and /mcp (the MCP server) | Public on a server that sends directly. Every call needs a bearer key, except the few that must work before anyone has one, such as the error catalog (/v1/errors), the one-click unsubscribe links in your mail and signing in to the dashboard |
https://mail.<your-domain> | /healthz and /llms.txt | Public, no key: whether the server is healthy, and your server's own guide for agents |
https://mail.<your-domain> | Every other path | Your server's dashboard, behind its own sign-in |
| Inside your server | The database, the queue, the virus scanner and the mail server's admin | Private: never published |
When your server connects through eMailPlane's network (the installer chooses this when your server already runs a website or another mail server): eMailPlane opens no public web port, so the API, /mcp and the dashboard are private to that server. Apps in Docker on it join the emailplane network and use https://mail.<your-domain>; other programs on it use port 11443 on the server's own loopback address. Nothing outside the server can call them today.
Serverless apps (for example on Vercel, Netlify, AWS Lambda or Cloudflare Workers) call https://mail.<your-domain> over the internet like any other client, with the key in their host's secret store, so they need a server that sends directly. Webhooks go the other way, to your app's public https address.
| Call | What it does |
|---|---|
GET /v1/tokens/self | Who am I: the token's scopes, the inbox it is limited to, its sending limits and what is left today |
POST /v1/emails | Send an email. Returns 202 with id, message_id and state |
POST /v1/sends/preflight | Ask whether a send would be accepted, where it would stop and how much headroom is left, without sending |
GET /v1/emails/:id | The state of one message |
GET /v1/events | Delivery events for your service (accepted, delivered, deferred, bounced, complained), filterable |
POST /v1/app/test-mode/connect | Connect a test-mode app with your app's own key, no approval: it can send only to test recipients. Safe to repeat |
POST /v1/app/test-mode/disconnect | Disconnect a test-mode app by name with your app's own key, no approval. Safe to repeat |
GET /v1/inbound | Mail your service received, newest first, with next_cursor paging |
GET /v1/inbound/threads | Received mail grouped into conversations |
GET /v1/inbound/threads/:id | One conversation, every message in order |
PUT /v1/ext/end-users/:externalId/inbox | The inbox for one of your users, by your own id for them: created the first time, the same inbox after that |
POST /v1/webhooks | Register a URL that gets signed events, such as message.received when a reply arrives (webhooks) |
POST /v1/mail-domains | Add a domain; POST /v1/mail-domains/:id/verify checks its DNS |
POST /v1/mailboxes | Create a mailbox a person can use in any mail app |
GET /v1/templates | Versioned templates you can render and promote |
GET /v1/agents/activity | What each agent did: what it read, sent and drafted, and what it was refused (no message content) |
GET /v1/openapi.json | The whole API as an OpenAPI 3.1 description, generated from the server itself. Send any key of your server |
GET /v1/errors | Every error code, what it means and what to do |
Send an email
curl -sS "$EMAILPLANE_API_URL/v1/emails" \
-H "Authorization: Bearer $EMAILPLANE_API_KEY" \
-H "Idempotency-Key: order-1042-shipped" \
-H "Content-Type: application/json" \
-d '{
"from": "orders@yourapp.com",
"to": ["customer@example.com"],
"subject": "Your order has shipped",
"text": "It is on the way."
}'
202 Accepted means the message is safely queued, not yet delivered. Follow it with GET /v1/emails/:id or GET /v1/events. Sending the same Idempotency-Key again returns the first answer instead of sending twice.
Attach a calendar invite
Add an attachments list to send a .ics file with an RSVP, a change or a cancellation. Gmail and Outlook show it as an event the recipient can add to their calendar.
curl -sS "$EMAILPLANE_API_URL/v1/emails" \
-H "Authorization: Bearer $EMAILPLANE_API_KEY" \
-H "Idempotency-Key: gathering-77-moved" \
-H "Content-Type: application/json" \
-d '{
"from": "events@yourapp.com",
"to": ["guest@example.com"],
"subject": "New time: Saturday 7pm",
"text": "The gathering moved to Saturday at 7pm.",
"attachments": [{
"filename": "invite.ics",
"content_type": "text/calendar; method=REQUEST",
"content_base64": "'"$(base64 -w0 invite.ics)"'"
}]
}'
Attachments are for small files your app generates, not for sharing documents:
| Types | text/calendar (.ics; method REQUEST, CANCEL or PUBLISH, matching the file's METHOD) and text/plain (.txt) |
|---|---|
| Limits | 3 files, 256 KiB each, 512 KiB in all; UTF-8 text |
| Anything else | Refused with 400 request.invalid, naming the file and a stable reason. Nothing is sent, so you can send again without the file. A file is never dropped from a message that is sent. |
The calendar goes into the signed message, so DKIM still passes.
Your own unsubscribe link
If your app keeps its own unsubscribe list, put your link on the message with list_unsubscribe, and add list_unsubscribe_post: true for one-click unsubscribe (RFC 8058, what Gmail and Yahoo ask of bulk senders). It works on both streams and replaces ours; a message never carries two.
{ "stream": "bulk",
"list_unsubscribe": ["https://yourapp.com/unsubscribe/7f3a", "mailto:unsubscribe@yourapp.com"],
"list_unsubscribe_post": true }
The link must be on a domain you have verified, or a subdomain of one. Proving you own the domain is enough: your mail can go from mail.yourapp.com while the link is on yourapp.com. A link anywhere else is refused with 400 (reasons).
Without your own link, bulk mail carries ours. On a server whose web address is not public (for example one sending through our delivery network), that is an email address: when the recipient uses it, the address is blocked for your app straight away.
Over SMTP
Port 587 takes the same message: attachments as multipart/mixed parts, and your own List-Unsubscribe and List-Unsubscribe-Post headers. The same rules apply, and a refusal comes back as a 550 before the message is accepted.
Errors
Every error has the same shape: a stable machine-readable code, whether trying again can work, whether a person has to act, what to do, and a link to the code's page. Errors never repeat an email address or a token back to you, so they are safe to paste into a bug report or an agent transcript.
{ "error": {
"code": "request.invalid", "message": "...", "field": "cursor",
"retryable": false, "human_action": false,
"remedy": "Fix the field named in `field`, then send again.",
"docs_url": "https://emailplane.com/developers/errors/#request-invalid"
} }
A test-mode app, no approval needed
A test bed or a CI job often needs its own app that it can connect, throw away and connect again on its own. A test-mode app is that: it can send only to test recipients, so connecting it needs no one's approval.
curl -X POST "$EMAILPLANE_API_URL/v1/app/test-mode/connect" -H "Authorization: Bearer $EMAILPLANE_API_KEY" \
-H 'content-type: application/json' -d '{"name": "testbed"}'
- Who can: any live app-wide key of your connected app (not an inbox's key, and not a test-mode app's own key). Up to 5 test-mode apps per organisation. On your own server:
emailplane connect --app testbed --test-mode --with-app <your connected app>. - Who it can mail:
ix-test-sink@emailplane.exchange(any+tag) and the app's own eMailPlane addresses. Anything else is refused withrecipient.test_mode_only, even where your account could otherwise send;GET /v1/sends/readinessanswers it as reasontest_mode_only. - Safe to repeat: the same name is the same app. Each connect hands back a fresh
sendkey and retires the previous one, so a retry always ends with exactly one working key (at most 30 connects of one test-mode app an hour). A name that belongs to a normal app is refused (test_mode.name_taken). - Disconnect:
POST /v1/app/test-mode/disconnectwith{"name": "testbed"}(oremailplane disconnect --app testbed --test-mode --with-app <app>). Connecting it again brings the same app back. - Audited: every connect and disconnect is in the audit log with the key that did it, the time, the app and
test_mode: true. No address or mail content. - Making it a normal app takes the owner's approval, exactly as today (
emailplane connect --app testbed). Its test-mode key stops working then; the approval issues real keys. - Your delivery log:
GET /v1/eventswith the app's own send key; filter bytype,message_id,recipient_hash,sinceanduntil. The connect answer says so too.
Mail your agents send says so
Mail written by an AI agent carries an EMP-Agent-Disclosure header, covered by the DKIM signature, and one plain sentence at the end: "This message was written and sent by an AI agent." followed by a link to the page that checks it, where anyone can see which company's agent sent it and what it may do (from the signed EMP-Agent-Receipt header). When a person approved the message first, it says that instead. This is on for agents (keys limited to one inbox, and anything sent through MCP); your app's own receipts and password resets are not marked. You can turn the sentence off in an agent's send policy, but not the header. Telling people they are talking to an AI may be your legal duty, for example under Article 50 of the EU AI Act; this makes it the default, it does not make you compliant by itself.
Webhooks
When something happens, eMailPlane POSTs a signed JSON event to your https address: a reply arrives, a message is delivered or bounces, a draft waits for a person. Events carry ids and verdicts, never message content or an email address; fetch the details with your key.
Register an endpoint
curl -sS "$EMAILPLANE_API_URL/v1/webhooks" \
-H "Authorization: Bearer $EMAILPLANE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://acme.example.com/hooks/email", "events": ["message.received", "message.bounced"]}'
Leave out events to get them all. The answer shows secret (whsec_...) this once and never again: keep it as EMAILPLANE_WEBHOOK_SECRET. To change a secret, register a new endpoint, then delete the old one. The address must be public https on port 443; an app has up to 10 endpoints. The key needs manage:webhooks.
What arrives
A POST with content-type: application/json, user-agent: eMailPlane-Webhooks/1 and three headers:
| Header | What it is |
|---|---|
x-ix-webhook-id | This delivery's id, also id in the body. The same on every retry and redrive: use it to drop duplicates |
x-ix-webhook-timestamp | When this attempt was signed, in Unix seconds. Every retry is signed again |
x-ix-webhook-signature | v1= and the hex HMAC-SHA256 of {timestamp}.{raw body}, keyed with your secret |
The body has id, type, event_id (the same id the event stream uses), occurred_at, and the event's own fields.
Verify every delivery
- Use the raw body bytes, before any JSON parsing: parsed and re-written JSON will not match.
- Refuse a timestamp more than 5 minutes from your clock. This is your replay window; the snippets use 5 minutes. A retry is signed again, so a real delivery is never stale.
- Compare
v1=+ hex(HMAC-SHA256(secret, timestamp + "." + body)) with the signature in constant time. - Skip an
x-ix-webhook-idyou have already handled. - Store the event, answer
2xx, then do the slow work.
Node 18 or later. This exact code is tested against our signer:
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SECONDS = 300; // the replay window: 5 minutes
// body: the raw request body (Buffer or string). headers: Node's req.headers or a Fetch Headers.
export function verifyWebhook(body, headers, secret, nowMs = Date.now()) {
const get = (name) => String((typeof headers.get === 'function' ? headers.get(name) : headers[name]) ?? '');
const timestamp = get('x-ix-webhook-timestamp');
const signature = get('x-ix-webhook-signature');
if (!/^\d{1,12}$/.test(timestamp)) return false;
if (Math.abs(nowMs / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;
const expected = 'v1=' + createHmac('sha256', secret).update(`${timestamp}.`).update(body).digest('hex');
const a = Buffer.from(signature);
const b = Buffer.from(expected);
return a.length === b.length && timingSafeEqual(a, b);
}
With Express, take the body raw: app.post('/hooks/email', express.raw({ type: 'application/json' }), (req, res) => ...) and pass req.body. With Fetch (Next.js, Workers, Bun, Deno): verifyWebhook(Buffer.from(await request.arrayBuffer()), request.headers, secret).
Python 3.8 or later. Pass request.get_data() in Flask or request.body in Django, and request.headers:
import hashlib, hmac, time
TOLERANCE_SECONDS = 300 # the replay window: 5 minutes
def verify_webhook(body: bytes, headers, secret: str, now=None) -> bool:
timestamp = headers.get("x-ix-webhook-timestamp", "")
signature = headers.get("x-ix-webhook-signature", "")
if not (timestamp.isascii() and timestamp.isdigit() and len(timestamp) <= 12):
return False
if abs((time.time() if now is None else now) - int(timestamp)) > TOLERANCE_SECONDS:
return False
mac = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256)
return hmac.compare_digest(signature.encode(), ("v1=" + mac.hexdigest()).encode())
Go. Read the body with io.ReadAll(r.Body), then call Verify(body, r.Header, secret, time.Now()):
package webhook
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"net/http"
"strconv"
"time"
)
const tolerance = 5 * time.Minute // the replay window
func Verify(body []byte, h http.Header, secret string, now time.Time) bool {
ts := h.Get("x-ix-webhook-timestamp")
sec, err := strconv.ParseInt(ts, 10, 64)
if err != nil || len(ts) > 12 {
return false
}
if d := now.Sub(time.Unix(sec, 0)); d > tolerance || d < -tolerance {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(ts + "."))
mac.Write(body)
want := "v1=" + hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(h.Get("x-ix-webhook-signature")), []byte(want))
}
Retries, pausing and failed deliveries
A 2xx answer within 30 seconds is success. Anything else is tried again: another status, a timeout, a refused connection. A redirect is followed up to 3 times, https only, and each new address is checked again. A delivery gets 10 attempts. The waits between them are 30 s, 1 min, 2 min, 4 min, 8 min, 16 min, 32 min, 1 h 4 min, 2 h 8 min, so the last attempt comes about 4 hours 16 minutes after the first. Then the delivery is failed and stays in the dead-letter queue until you send it again. Delivery is at least once: drop duplicates by x-ix-webhook-id.
| Call | What it does |
|---|---|
GET /v1/webhooks/:id | One endpoint: its events, whether it is paused, and how many deliveries are pending or failed |
GET /v1/webhooks/:id/deliveries | Its last 100 deliveries: state (pending, delivered, failed, cancelled), attempts, last HTTP status and reason, next attempt |
GET /v1/webhooks/dlq | The dead-letter queue: the last 100 failed deliveries across your endpoints |
POST /v1/webhooks/dlq/:id/redrive | Send one failed delivery again, due now, with 10 fresh attempts and the same id. 409 if it has not failed |
POST /v1/webhooks/:id/pause | Hold deliveries, for a deploy or an outage. Events are still recorded, and nothing is lost |
POST /v1/webhooks/:id/resume | Send what was held on the next pass. A delivery waiting between retries keeps its wait |
DELETE /v1/webhooks/:id | Remove the endpoint; its pending deliveries are cancelled |
Events
Each event is recorded once, then sent to your webhooks and to the event stream, GET /v1/events/stream (Server-Sent Events, kept for 7 days; reconnect with Last-Event-ID and nothing is missed). So every event below is on the stream too, with the webhook's event_id as its id. A webhook gets every event it subscribed to; on the stream a key sees what its scopes allow: received mail and its conversations (messages, threads, waits, terms) with read:inbox; the fate of sent mail (message.delivered, .bounced, .complained, recipient.*) with send or read:analytics; drafts with any of those three; domain events with admin; authority.changed and app.disconnected with any scope.
| Event | When |
|---|---|
message.received | Mail arrived for your app |
message.matched | Received mail matched one of your inbound rules, with the message, thread and rule ids and the route. It goes to the webhook the rule names, or to your subscribed webhooks when the rule names none |
message.human_replied | A person answered from their own mailbox |
message.delivered | The recipient's server accepted your message |
message.bounced | Your message bounced |
message.complained | The recipient reported it as spam |
recipient.bounced, recipient.complained, recipient.unsubscribed | A person hard-bounced, complained or unsubscribed. We already stop your mail to them (sign-in mail still reaches someone who unsubscribed or complained); update your own records |
draft.created, draft.approved, draft.rejected, draft.expired | A send held for a person's decision, and the decision |
draft.withdrawn | The program that wrote a pending draft took it back before anyone decided (ids only, never content) |
wait.resolved | A wait (POST /v1/waits) ended |
thread.owner_changed | A conversation changed hands: a person answered it, or it was handed to a person or back |
thread.marked | A triage mark was set or cleared |
conversation.contract_proposed, conversation.budget_tripped, conversation.expired, conversation.circuit_reset | A conversation's agreed terms were proposed, ran out of budget, expired or were reset |
domain.verified, domain.verification_gave_up | A domain's DNS check passed, or 72 hours of checking ended |
domain.registration_expiring | A verified domain's registration ends in 30 days, and again at 7, with its end date and the days left. Renew it with your registrar or mail to that domain stops |
domain.nameservers_changed | A verified domain moved to other nameservers, with the old and new ones. Re-check its email records there, then verify the domain again |
authority.changed | What a key may do changed: a key was revoked, an inbox burned, an agent paused or resumed, or a policy changed. It names the change, the key or inbox it applies to and a revision number; it never grants anything |
app.disconnected | The app was disconnected. Sent to every endpoint it had, even a paused one or one that did not subscribe |
message.received:
{
"id": "0b6f2c1e-4a8d-4f6e-9a51-3c2d7e9f1a20",
"type": "message.received",
"event_id": "48213",
"occurred_at": "2026-11-11T01:14:03.512Z",
"message_id": "5f1d3a9e-2c47-4b8a-9e6d-1a2b3c4d5e6f",
"thread_id": "a3e9b0c2-7d14-4f5a-8b6c-9d0e1f2a3b4c",
"route": "agent",
"inbox_ids": ["c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f"],
"sender": { "trust_tier": 2, "tier": "verified", "flags": [], "auth": {
"dkim": [{ "result": "pass", "aligned": true }],
"spf": { "result": "pass", "aligned": true, "asserted_by": "edge" },
"dmarc": { "result": "pass", "policy": "reject" } } },
"screening": { "trust_tier": 2, "automated": false, "reply_needed": null,
"needs_human": null, "withheld_reason": null, "source": "rule" }
}
route is the part of your address before the @ that the mail came to. Read the message with GET /v1/inbound/:message_id.
message.delivered, message.bounced and message.complained share one shape; recipient.* events use it too:
{
"id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
"type": "message.bounced",
"event_id": "48214",
"occurred_at": "2026-11-11T01:15:42.000Z",
"message_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"thread_id": null,
"lifecycle_event_id": "90311",
"reason_code": "dsn_5.1.1",
"smtp_code": 550,
"enhanced_status": "5.1.1"
}
reason_code names the report behind the event, for example dsn_5.1.1 from a bounce report or arf_abuse from a spam complaint. smtp_code and enhanced_status are null when the report had none. message_id is the id that POST /v1/emails returned.
Debug a missing email
H="Authorization: Bearer $EMAILPLANE_API_KEY"
curl -sS "$EMAILPLANE_API_URL/v1/emails/$ID" -H "$H" # 1
curl -sS "$EMAILPLANE_API_URL/v1/events?message_id=$ID" -H "$H" # 2
curl -sS "$EMAILPLANE_API_URL/v1/suppressions/check" -H "$H" \
-H "Content-Type: application/json" -d '{"address": "customer@example.com"}' # 3
curl -sS "$EMAILPLANE_API_URL/v1/webhooks/$HOOK/deliveries" -H "$H"
curl -sS "$EMAILPLANE_API_URL/v1/webhooks/dlq" -H "$H"
curl -sS -X POST "$EMAILPLANE_API_URL/v1/webhooks/dlq/$DELIVERY/redrive" -H "$H" # 4
- Where it is now:
state, andprogresssays in words where the message is (on your server, handed on, retrying, delivered, bounced, not sent) and what happens next. - Every step it took, with the
smtp_code,enhanced_statusand the recipient's mail domain for each step. - Will this person's mail be refused?
"suppressed": truemeans the person bounced, complained or unsubscribed. A send to them is refused, and trying again never helps. - The event happened but your app never heard: a delivery's
last_reasonsays why.delivered: it worked.http_<status>: your endpoint answered that status.network: no connection, or no answer in 30 seconds.bad_redirect: an unreadableLocation.too_many_redirects: more than 3.blocked:dns_failureorblocked:dns_empty: the name did not resolve.blocked:proxy_refused: our outbound proxy could not connect to you.blocked:scheme_not_https,blocked:port_not_443,blocked:userinfo_in_url,blocked:no_host,blocked:denied_range,blocked:not_globally_routableorblocked:unparseable_address: the URL, or a redirect, is not a public https address on port 443. Fix it, then redrive. If nothing is listed, check the endpoint subscribed to that event and is not paused (GET /v1/webhooks/:id).
Waiting for a reply instead? GET /v1/inbound lists what arrived, newest first, and the event stream shows each message.received as it lands.
Try it on your laptop: the sandbox
The sandbox runs the real eMailPlane API and MCP server on your machine with Docker, with a capture sink instead of delivery. You need no domain and no server, and nothing it sends leaves your machine: every message lands in the sink, and recipients are limited to example.com, example.net and example.org. The sandbox and the emailplane-api command line tool are included with your beta invite; download them from your account.
emailplane-api dev up # build and start it (Docker Compose)
eval "$(emailplane-api dev env)" # point this shell, your app or your agent at it
emailplane-api whoami
emailplane-api inbox create --purpose signup
emailplane-api dev inject --to <inbox address> --fixture otp # a verification email from a verified sender
emailplane-api wait --inbox <inbox id> --from someone@example.com --otp
emailplane-api dev outbox # what your app sent; or open http://localhost:8025
emailplane-api dev check # the whole flow end to end
| Address | What |
|---|---|
http://localhost:8787 | The API |
http://localhost:8788/mcp | The MCP server (HTTP) |
http://localhost:8025 | The capture sink: every message the sandbox sent |
There is no internet-facing mail server in the sandbox. emailplane-api dev inject hands it a received message the way one would, signed as example.com when you want a verified sender. Mailboxes for people (IMAP) and virus scanning are not in the sandbox.
Command line
emailplane-api covers the calls an agent builder makes most: whoami, inbox create|list|burn, send, draft, receive, read, wait, activity, policy, errors and openapi. It reads EMAILPLANE_API_URL and EMAILPLANE_API_KEY (the same two settings as your app), prints JSON, and never prints your key. It is not the emailplane command on your mail server, which installs and runs the server.
MCP
The eMailPlane MCP server gives an agent 55 tools over the same API and the same token scopes: whoami, sending, preflight, inboxes for agents, reading mail and threads, waiting for a reply or a code, drafts for approval, the activity log, templates, domains, mailboxes and API keys, plus app_bootstrap, which sets up a whole app in one call (10 minutes once your server is running). MCP setup
Status
| Capability | Status |
|---|---|
| Send API with idempotency keys, preflight, suppression and delivery events | In private beta |
| Receive mail and read it as threads through the API | In private beta |
| Domains, mailboxes for people, and IMAP login from any mail app | In private beta |
| Virus scanning of inbound mail on your server | In private beta |
| MCP server (55 tools) | In private beta |
Reply to a message in its thread (in_reply_to) | In private beta |
Signed webhooks when mail arrives (message.received, message and thread ids only) | In private beta |
Wait for a reply, a code or a link for up to 30 days (POST /v1/waits, MCP thread_await) | In private beta |
Remote MCP endpoint at https://mail.<your-domain>/mcp, on a server that sends directly | In private beta |
| Separate addresses and keys for each agent | In private beta |
| Sender trust labels and untrusted-content wrapping for agents | In private beta |
| Drafts and approval policies (approve in the dashboard or by replying APPROVE) | In private beta |
| Approving a draft with a passkey | Coming soon |
| An event stream | In private beta |
A local sandbox (Docker) with a capture sink, and the emailplane-api command line tool | In private beta |
| An activity log of what each agent read, sent, drafted and was refused | In private beta |
| AI disclosure on mail agents send (header and footer) | In private beta |
| One error shape with retry and next-step hints, and a page per code | In private beta |
| OpenAPI description, generated from the server | In private beta |
npx emailplane-api and signing in from the command line | Coming soon |
Machine-readable versions
This site publishes /llms.txt, a full-text /llms-full.txt, and a Markdown version of every page: add index.html.md to any page's address, for example /pricing/index.html.md, or ask the page's own address for Markdown: curl -H 'Accept: text/markdown' https://emailplane.com/pricing/. The plans, their prices and the capabilities marked as in beta above are also in each page's JSON-LD (schema.org SoftwareApplication with featureList and offers).