API Reference

Everything is JSON over HTTPS at https://maildesk.email. Machine-readable spec: GET /v0/openapi.json (no key needed). The same operations are exposed as native MCP tools — see MCP.

Authentication

Pass your key as a bearer token on every request:

Authorization: Bearer ap_your_key_here

Keys carry scopes — read, write, admin. Self-serve signup keys get read + write. Check what a key can do with GET /v0/me.

No key yet? POST /v0/signup {"email": "you@example.com"}, then trade the emailed 6-digit code via POST /v0/signup/verify {"email", "code"} — the response contains your key (shown exactly once; re-verifying with the same email rotates it, which doubles as lost-key recovery). Or sign up on the landing page.

Quickstart

# 1. create an inbox — returns a working address in one call
curl -X POST https://maildesk.email/v0/inboxes \
  -H "authorization: Bearer $KEY" -d '{"username":"my-agent"}'

# 2. read its mail (every inbound message carries an injection_score)
curl "https://maildesk.email/v0/inboxes/my-agent@maildesk.email/messages" \
  -H "authorization: Bearer $KEY"

# 3. send from it
curl -X POST https://maildesk.email/v0/inboxes/my-agent@maildesk.email/messages \
  -H "authorization: Bearer $KEY" \
  -d '{"to":"someone@example.com","subject":"hello","text":"from my agent"}'

# 4. grab a verification code the moment it arrives
curl "https://maildesk.email/v0/inboxes/my-agent@maildesk.email/otp" \
  -H "authorization: Bearer $KEY"

Polling for new mail

cursor=0
while true; do
  batch=$(curl -s "https://maildesk.email/v0/inboxes/$INBOX/messages?direction=inbound&since=$cursor" \
    -H "authorization: Bearer $KEY")
  # ... process $batch (newest first) ...
  new_cursor=$(echo "$batch" | jq '[.[].created_at] | max // empty')
  [ -n "$new_cursor" ] && cursor=$new_cursor
  sleep 15
done

Prefer an empty-inbox workflow? DELETE /v0/messages/:id each message after handling it instead of tracking a cursor. Prefer push? Register a webhook for message.received.

Inboxes

Anywhere a path says :inbox, the inbox id and the full address are interchangeable.

Create an inbox. Body (all optional): username (local part — lowercased, limited to a-z0-9._-, random if omitted), name (human label), domain (defaults to the default domain). Returns 201 with the Inbox, including its address. 409 if the address exists.

List all inboxes.

Fetch one inbox.

Delete an inbox and everything in it (messages, threads, attachments).

Messages

List messages, newest first. Query params:

Param	Type	Meaning
since	epoch‑ms	Only messages with created_at > since — the poll cursor
direction	inbound | outbound	Filter by direction
limit	1–200	Batch size (default 50)

Send an email from this inbox. Body: to (required), subject, text, html. Returns 201 with {message, delivery}.

One message with full body, attachments, and injection-safety analysis.

Delete a message (and its attachments) once you've handled it — it never reappears in a poll.

Attachment metadata: {id, filename, content_type, size, has_content}.

Raw attachment bytes with the original content type. 410 if the content was too large to store inline (metadata only).

The Message object

Field	Type	Notes
id	string	msg_…
inbox_id	string
thread_id	string	Messages sharing a normalized subject share a thread
direction	string	inbound or outbound
from_addr / to_addr	string
subject	string?
text / html	string?	Real inbound mail is fully MIME-parsed (multipart, quoted-printable, charsets)
preview	string?	Short plain-text excerpt for list views
injection_score	int?	0–100 prompt-injection risk (inbound only)
injection_level	string?	low / medium / high
injection_flags	array	{code, weight, detail} — explainable signals behind the score
otp_code	string?	Auto-extracted verification code, if found
labels	array	e.g. ["otp"]
created_at	epoch‑ms	Use as the since cursor

OTP extraction

The most recent auto-extracted verification code, or {"code": null} if none yet. Pass ?since=<epoch-ms of when you triggered the send> to ignore older codes. Response: {code, message_id, from, received_at}.

Injection safety

Every inbound message is scored 0–100 for prompt-injection risk before your agent reads it. Gate tool use on it:

msg = get_message(id)
if msg.injection_level == "high":
    quarantine(msg)          # don't let the model act on it
elif msg.injection_level == "medium":
    require_confirmation(msg)
else:
    process(msg)

injection_flags names each signal (e.g. instruction_override, secret_exfiltration, look-alike sender domains, hidden HTML) with its weight — the score is explainable, not a black box.

Webhooks admin

Push instead of poll. Events: message.received, message.sent, or *.

Body: url (required), secret (random UUID if omitted), events (default ["*"]). Deliveries are signed: x-agentpost-signature is the hex HMAC-SHA256 of the raw body with your secret.

API keys admin

Body: name, scopes (subset of read/write/admin; default ["read","write"]). The raw key appears once in the 201 response.

What key am I? Returns {name, scopes, master}.

Domains

List configured domains (readable so you can pick one when creating inboxes). Writes — POST /v0/domains, PATCH/DELETE /v0/domains/:domain, POST /v0/domains/:domain/default — require admin.

Simulated inbound

Inject a fake inbound email for testing — it runs the same pipeline as real mail (injection scoring, OTP extraction, webhooks). Body: from, to (must match an existing inbox), subject, text, html, optional attachments [{filename, content_type, content_b64}]. Note: text is stored verbatim — real inbound mail is MIME-parsed before it reaches this pipeline.

MCP

Point any MCP client at POST https://maildesk.email/mcp with the same bearer key (plain JSON-RPC 2.0 responses — the broadly compatible subset of streamable HTTP). Tools:

Tool	REST equivalent
create_inbox	POST /v0/inboxes
list_inboxes	GET /v0/inboxes
list_messages	GET /v0/inboxes/:inbox/messages (supports since)
get_message	GET /v0/messages/:id
send_message	POST /v0/inboxes/:inbox/messages
delete_message	DELETE /v0/messages/:id
wait_for_otp	GET /v0/inboxes/:inbox/otp
list_domains	GET /v0/domains

Errors

Errors are JSON: {"error": "<what went wrong>", "docs": "https://maildesk.email/docs"}. Resource misses name the resource ("inbox radar@… not found"); a path that doesn't exist returns 404 {"error": "no such route: GET /v0/whatever"} — with or without a key, so the surface is probeable. 401 means missing/invalid key, 403 names the missing scope, 429 is a rate cap (see below).

Rate limits

Cap	Self-serve key	Admin-issued key
New inboxes / day / key	10	100
Outbound sends / day / inbox	50	200

Beta limits — need more? hello@maildesk.email. Machine-readable pricing: /pricing.md.

AgentPost is a Shovelware product. Spec: /v0/openapi.json · Agent-readable summary: /llms.txt