Angel Mail Docs

MCP over HTTP

For building a client, or calling Angel Mail from code without an MCP library.

The endpoint #

POST https://app.angelmail.io/mcp        (your own server: https://<your server>/mcp)
Content-Type: application/json
Authorization: Bearer smt_…              (or the access token from sign-in)

Streamable HTTP, stateless: each POST carries one JSON-RPC 2.0 message (or a batch array) and gets a JSON reply. There is no server-sent event stream and no session id. Notifications (no id) get 202 Accepted and no body. Protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 are accepted; the server answers with the one you asked for, else the newest.

Signing in, or a token #

Tokens. Make one in Angel Mail → Settings → AI connections → Any other MCP client. It starts with smt_, works only for this server, and only until the owner revokes it. Its name is what the owner sees on everything it writes.

Sign-in (OAuth 2.1). A request without a working token gets 401 with WWW-Authenticate pointing at the protected-resource metadata:

GET /.well-known/oauth-protected-resource/mcp
GET /.well-known/oauth-authorization-server     (also /.well-known/openid-configuration)

Clients register at /oauth/register (dynamic client registration), send the owner to /oauth/authorize with PKCE, and exchange the code at /oauth/token, which also refreshes. Sign-in is open only to known apps: callbacks on this computer (loopback), the app schemes cursor://, vscode://, vscode-insiders:// and windsurf://, and the https callbacks of Claude, ChatGPT, Grok, Cursor and VS Code. Any other app connects with a token.

The calls #

Start a connection:

curl -s https://app.angelmail.io/mcp -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}'
{"jsonrpc": "2.0", "id": 1, "result": {
  "protocolVersion": "2025-11-25",
  "capabilities": {"tools": {"listChanged": false}, "prompts": {"listChanged": false}},
  "serverInfo": {"name": "angel-mail", "title": "Angel Mail", "version": "0.4.0"},
  "instructions": "Angel Mail: the owner's email across their linked inboxes. …"}}

Show instructions to the model: they carry the rules for drafting and sending.

MethodWhat it does
initializeCapabilities, server info, instructions
ping{}
tools/listEvery tool this token may use, with input schemas and annotations (send_approved_email only for tokens that may send)
tools/call{"name": "<tool>", "arguments": {…}}
prompts/listThe named workflows and their arguments
prompts/get{"name": "<workflow>", "arguments": {…}}: one user message with the steps

Call a tool:

curl -s https://app.angelmail.io/mcp -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_mail","arguments":{"query":"is:unread newer_than:2d","limit":5}}}'

Results come twice: as structuredContent (the JSON object) and as content[0].text (the same JSON as text, for clients that only read text). Read structuredContent when your client supports it.

Get a workflow:

curl -s https://app.angelmail.io/mcp -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"prompts/get","params":{"name":"draft_replies","arguments":{"limit":"3"}}}'
{"jsonrpc": "2.0", "id": 3, "result": {"description": "Find conversations waiting for …",
  "messages": [{"role": "user", "content": {"type": "text", "text": "Draft replies for … at most 3.\n1. Call get_writing_feedback …"}}]}}

Errors #

A tool that fails returns a normal result with isError: true and the reason as text, so the model can read it and try again:

{"result": {"isError": true, "content": [{"type": "text", "text": "Error: No such item among yours (list_my_drafts shows them)"}]}}

Everything else is an HTTP status or a JSON-RPC error:

AnswerMeaningWhat to do
HTTP 401, error -32001No token, or the token was refusedSign in again, or make a new token
HTTP 403, error -32002The owner switched this agent off in Settings → AI connectionsTell the owner; it works again once they switch it back on. Don't start a new sign-in
HTTP 404, error -32001A public demo with agents switched offUse your own server or the hosted service
HTTP 429Too many requests; Retry-After says how many seconds to waitWait, then try again
HTTP 400, error -32700The body isn't JSONFix the request
error -32601Unknown methodCheck the method name
error -32602Unknown tool or prompt, or a missing prompt argumentCheck tools/list or prompts/list
HTTP 405 on GETThere is no event stream (with a working token; without one, a GET gets the same 401 as a POST)Use POST

Limits #

WhatLimit
Requests to /mcp600 a minute from one address (a server can change it)
Sending (approving an email, send_approved_email)300 an hour per owner
A request bodyAbout 4 MB, so put big files at a public https URL
Attachments on one email25 MB in total (Gmail's limit)
wait_for_reviewUp to 50 seconds per call
search_mailUp to 40 conversations per call
propose_actionsUp to 100 items per batch
A skill's ticket2 hours
send_approved_emailWithin 2 hours of the request_send

For agents: this page as Markdown, every page in one file at llms-full.txt, the index at llms.txt.