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

StepWhat it makesWhen it is already there
appYour app, with its own sending addressFound by name and environment
keyA key with the five permissions above, saved in your folder first and switched on afterRead back from its file
domainacme on our shared zone, sending and receiving with no DNS workFound by name
webhookA signed webhook to your webhook_url; its secret is saved in your folderFound by address
end_user_inboxAn inbox for one of your users (demo-user)The same inbox, same address
agent_inboxAn inbox for your agent (agent)The same inbox, same address
conversationYour agent writes to your user's inbox and the user replies, in one threadFound 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

WhereWhatWho 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.txtPublic, no key: whether the server is healthy, and your server's own guide for agents
https://mail.<your-domain>Every other pathYour server's dashboard, behind its own sign-in
Inside your serverThe database, the queue, the virus scanner and the mail server's adminPrivate: 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.

CallWhat it does
GET /v1/tokens/selfWho am I: the token's scopes, the inbox it is limited to, its sending limits and what is left today
POST /v1/emailsSend an email. Returns 202 with id, message_id and state
POST /v1/sends/preflightAsk whether a send would be accepted, where it would stop and how much headroom is left, without sending
GET /v1/emails/:idThe state of one message
GET /v1/eventsDelivery events for your service (accepted, delivered, deferred, bounced, complained), filterable
POST /v1/app/test-mode/connectConnect 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/disconnectDisconnect a test-mode app by name with your app's own key, no approval. Safe to repeat
GET /v1/inboundMail your service received, newest first, with next_cursor paging
GET /v1/inbound/threadsReceived mail grouped into conversations
GET /v1/inbound/threads/:idOne conversation, every message in order
PUT /v1/ext/end-users/:externalId/inboxThe inbox for one of your users, by your own id for them: created the first time, the same inbox after that
POST /v1/webhooksRegister a URL that gets signed events, such as message.received when a reply arrives (webhooks)
POST /v1/mail-domainsAdd a domain; POST /v1/mail-domains/:id/verify checks its DNS
POST /v1/mailboxesCreate a mailbox a person can use in any mail app
GET /v1/templatesVersioned templates you can render and promote
GET /v1/agents/activityWhat each agent did: what it read, sent and drafted, and what it was refused (no message content)
GET /v1/openapi.jsonThe whole API as an OpenAPI 3.1 description, generated from the server itself. Send any key of your server
GET /v1/errorsEvery 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:

Typestext/calendar (.ics; method REQUEST, CANCEL or PUBLISH, matching the file's METHOD) and text/plain (.txt)
Limits3 files, 256 KiB each, 512 KiB in all; UTF-8 text
Anything elseRefused 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.

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"
} }

All error codes

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"}'

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:

HeaderWhat it is
x-ix-webhook-idThis delivery's id, also id in the body. The same on every retry and redrive: use it to drop duplicates
x-ix-webhook-timestampWhen this attempt was signed, in Unix seconds. Every retry is signed again
x-ix-webhook-signaturev1= 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

  1. Use the raw body bytes, before any JSON parsing: parsed and re-written JSON will not match.
  2. 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.
  3. Compare v1= + hex(HMAC-SHA256(secret, timestamp + "." + body)) with the signature in constant time.
  4. Skip an x-ix-webhook-id you have already handled.
  5. 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.

CallWhat it does
GET /v1/webhooks/:idOne endpoint: its events, whether it is paused, and how many deliveries are pending or failed
GET /v1/webhooks/:id/deliveriesIts last 100 deliveries: state (pending, delivered, failed, cancelled), attempts, last HTTP status and reason, next attempt
GET /v1/webhooks/dlqThe dead-letter queue: the last 100 failed deliveries across your endpoints
POST /v1/webhooks/dlq/:id/redriveSend one failed delivery again, due now, with 10 fresh attempts and the same id. 409 if it has not failed
POST /v1/webhooks/:id/pauseHold deliveries, for a deploy or an outage. Events are still recorded, and nothing is lost
POST /v1/webhooks/:id/resumeSend what was held on the next pass. A delivery waiting between retries keeps its wait
DELETE /v1/webhooks/:idRemove 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.

EventWhen
message.receivedMail arrived for your app
message.matchedReceived 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_repliedA person answered from their own mailbox
message.deliveredThe recipient's server accepted your message
message.bouncedYour message bounced
message.complainedThe recipient reported it as spam
recipient.bounced, recipient.complained, recipient.unsubscribedA 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.expiredA send held for a person's decision, and the decision
draft.withdrawnThe program that wrote a pending draft took it back before anyone decided (ids only, never content)
wait.resolvedA wait (POST /v1/waits) ended
thread.owner_changedA conversation changed hands: a person answered it, or it was handed to a person or back
thread.markedA triage mark was set or cleared
conversation.contract_proposed, conversation.budget_tripped, conversation.expired, conversation.circuit_resetA conversation's agreed terms were proposed, ran out of budget, expired or were reset
domain.verified, domain.verification_gave_upA domain's DNS check passed, or 72 hours of checking ended
domain.registration_expiringA 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_changedA verified domain moved to other nameservers, with the old and new ones. Re-check its email records there, then verify the domain again
authority.changedWhat 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.disconnectedThe 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
  1. Where it is now: state, and progress says in words where the message is (on your server, handed on, retrying, delivered, bounced, not sent) and what happens next.
  2. Every step it took, with the smtp_code, enhanced_status and the recipient's mail domain for each step.
  3. Will this person's mail be refused? "suppressed": true means the person bounced, complained or unsubscribed. A send to them is refused, and trying again never helps.
  4. The event happened but your app never heard: a delivery's last_reason says why. delivered: it worked. http_<status>: your endpoint answered that status. network: no connection, or no answer in 30 seconds. bad_redirect: an unreadable Location. too_many_redirects: more than 3. blocked:dns_failure or blocked: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_routable or blocked: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
AddressWhat
http://localhost:8787The API
http://localhost:8788/mcpThe MCP server (HTTP)
http://localhost:8025The 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

CapabilityStatus
Send API with idempotency keys, preflight, suppression and delivery eventsIn private beta
Receive mail and read it as threads through the APIIn private beta
Domains, mailboxes for people, and IMAP login from any mail appIn private beta
Virus scanning of inbound mail on your serverIn 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 directlyIn private beta
Separate addresses and keys for each agentIn private beta
Sender trust labels and untrusted-content wrapping for agentsIn private beta
Drafts and approval policies (approve in the dashboard or by replying APPROVE)In private beta
Approving a draft with a passkeyComing soon
An event streamIn private beta
A local sandbox (Docker) with a capture sink, and the emailplane-api command line toolIn private beta
An activity log of what each agent read, sent, drafted and was refusedIn 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 codeIn private beta
OpenAPI description, generated from the serverIn private beta
npx emailplane-api and signing in from the command lineComing 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).