# Mailman local agent API

Mailman lets local AI agents and scripts search and read your mail, extract codes and links, download files, and sync selected accounts. It provides MCP over Streamable HTTP at `/mcp` and a REST API at `/v1/…` on the same local server. Mail access is read-only: no sending, changing mail, account passwords, or TOTP secrets.

## Requirements and setup

Available on every plan with a valid Mailman license. Keep Mailman open, signed in to your license, and the Local API toggle on. Run your client on the same computer as Mailman; a hosted agent cannot reach your computer's loopback address.

1. Open **Settings → Agents & API** and turn on **Local API**.
2. Leave the port at **7357**, or choose a port and click **Apply**.
3. Click **Add client**, enter a name such as “Claude Code”, and click **Create token**.
4. Copy the token now; Mailman shows it only once. Use a separate named client for each agent or script.

The server requires `127.0.0.1` and also binds `[::1]` when available. If IPv6 cannot bind, the API runs on IPv4 and Settings shows a non-fatal note. The toggle and port are remembered for the next launch. Turning the toggle off or quitting Mailman stops the API.

## Connect a client

Replace `<your token>` with the token from Settings, and replace `7357` everywhere if you changed the port. Every request, including the OpenAPI document, needs `Authorization: Bearer <your token>`. Restart or reconnect your client after changing its configuration.

### Claude Code

Run in your project:

```sh
claude mcp add --transport http mailman http://127.0.0.1:7357/mcp \
  --header "Authorization: Bearer <your token>"
```

Check the connection with `/mcp` in Claude Code. See [Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp) for configuration scopes.

### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.mailman]
url = "http://127.0.0.1:7357/mcp"
http_headers = { "Authorization" = "Bearer <your token>" }
tool_timeout_sec = 130
```

The timeout accommodates waits of up to 120 seconds. Codex supports `url` and `http_headers` for Streamable HTTP servers; see the [official OpenAI MCP documentation](https://developers.openai.com/codex/mcp/). To keep the token out of the file, replace `http_headers` with `bearer_token_env_var = "MAILMAN_TOKEN"` and set that environment variable before starting Codex.

### Cursor

Add to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally:

```json
{
  "mcpServers": {
    "mailman": {
      "url": "http://127.0.0.1:7357/mcp",
      "headers": { "Authorization": "Bearer <your token>" }
    }
  }
}
```

See [Cursor's MCP documentation](https://cursor.com/docs/mcp).

### Claude Desktop and other stdio-only clients

Use [mcp-remote](https://github.com/punkpeye/mcp-remote) to bridge stdio to Mailman's HTTP endpoint. It requires Node.js and `npx`:

```sh
npx -y mcp-remote http://127.0.0.1:7357/mcp \
  --header "Authorization: Bearer <your token>"
```

In Claude Desktop's MCP configuration, merge this entry into `mcpServers`. The environment variable form avoids problems with spaces in arguments on Windows:

```json
{
  "mcpServers": {
    "mailman": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://127.0.0.1:7357/mcp",
        "--header", "Authorization:${MAILMAN_AUTH}"
      ],
      "env": { "MAILMAN_AUTH": "Bearer <your token>" }
    }
  }
}
```

### curl and scripts

```sh
curl -H "Authorization: Bearer <your token>" http://127.0.0.1:7357/v1/status
```

For the REST examples below, set these shell variables once:

```sh
MAILMAN_URL='http://127.0.0.1:7357'
MAILMAN_TOKEN='<your token>'
```

## MCP tools

Tools use JSON arguments with the same names as the REST parameters below. `?` means optional. Mail content is returned as untrusted data in `structuredContent`; tool failures set `isError: true` and include the error object. There are **no rate limits**; page sizes, request sizes, and timeouts still apply.

| Tool | Purpose and key parameters |
| --- | --- |
| `mailman_status` | Check version, license, sync state, and account count; no arguments. |
| `list_accounts` | List public account metadata and aliases; `query?`, `category?`, `tag?`, `cursor?`, `limit?`. |
| `find_accounts` | Resolve inboxes, aliases, or account IDs; `emails` array, up to 10,000. |
| `search_mail` | Search mail headers; `q`, `bodies?`, `category?`, `offset?`, `limit?`. |
| `list_messages` | List message headers; `account?`, `scope?`, `category?`, `cursor?`, `limit?`. |
| `read_message` | Read a message body and metadata; `id`, `format?`, `original?`, `maxChars?`. |
| `get_attachment` | Download a file, up to 25 MB over MCP; `id`, `index`. |
| `get_raw_message` | Read original RFC822 source as text, capped at 2 MB over MCP; `id`. |
| `read_messages` | Read several messages together; `ids` array, up to 50, plus `format?`, `original?`, `maxChars?`. |
| `list_stacks` | List maintained message stacks; `category?`, `cursor?`, `limit?`. |
| `get_stack` | List a stack's message headers; `id`, `category?`, `cursor?`, `limit?`. |
| `get_codes` | Get stored extracted codes; `account?`, `since?`, `limit?`. |
| `sync_accounts` | Sync chosen accounts or one category; `accounts` array OR `category`, `waitSeconds?`. |
| `sync_status` | Check current state and last sync result; `accounts` array. |
| `wait_for_mail` | Refresh and wait for an exact recipient; `to`, `account?`, `from?`, `subjectContains?`, `since?`, `extract?`, `timeoutSeconds?`. |

For MCP attachments, text types return `untrusted.text`, images also have an image content block, and other files return `untrusted.base64`, alongside `mime`, `untrusted.name`, and `truncated`. Use REST for larger files or byte-for-byte raw mail.

## REST conventions

GET parameters go in the query string; POST parameters go in a JSON body with `Content-Type: application/json`. Unknown parameters, duplicate query parameters, wrong types, and invalid IDs are rejected. GET array parameters such as `accounts` use one comma-separated value; POST arrays use JSON arrays. Use `curl -G --data-urlencode` for addresses with `+`, searches, timestamps, and cursors.

- IDs are opaque and stable across restarts: accounts `acc_…`, messages `msg_…`, stacks `stk_…`. Copy IDs from responses. The examples use illustrative `acc_1`, `msg_1`, and `stk_1`; substitute your own.
- Attachments use the zero-based `index` returned by reading a message. Inline parts use `cid`, without surrounding angle brackets; URL-encode it in the path.
- `account` and `accounts` accept account IDs, inbox emails, or known aliases. Resolution ignores case and surrounding whitespace. An inbox email wins over an alias; a shared alias resolves to the lowest account ID. `wait_for_mail` also supports unregistered recipients through explicit `account` or a unique domain match, as described below.
- `category` accepts a category name (case-insensitive) or its numeric ID as a string. The account-list `tag` filter likewise accepts a name or numeric ID.
- `since` is an RFC3339 timestamp, such as `2026-10-12T15:00:00Z`. Returned timestamps such as `receivedAt` and `lastSync` are Unix seconds; some metadata may be null.
- Page `limit` defaults to 25 and ranges from 1 to 100. Accounts, messages, stacks, and stack messages return `{ "items": […], "truncated": false, "nextCursor": null }`. When `nextCursor` is non-null, pass it as `cursor` to the same endpoint with the same filters. You may change `limit`; do not decode or construct cursors.
- List pages are bounded to about 1 MB. Search uses `offset`/`nextOffset`, not cursors, and stops at 20,000 results. Codes have no continuation parameter.
- Message header rows contain `id`, `account`, `stack`, `receivedAt`, `unread`, and `untrusted: { from, fromName, to, subject }`.

### GET /v1/status

No parameters. Returns `{ version, licenseOk, sync, accountCount }`; `sync` is `running` or `paused`. The request itself requires a valid license.

```sh
curl -H "Authorization: Bearer $MAILMAN_TOKEN" "$MAILMAN_URL/v1/status"
```

### GET /v1/accounts

Optional `query`, `category`, `tag`, `cursor`, `limit`. Returns a page of `{ id, email, aliases, provider, category, tags, paused, lastSync }`. `category` and `tags` in each row are arrays of names. No credentials are returned.

```sh
curl -G -H "Authorization: Bearer $MAILMAN_TOKEN" "$MAILMAN_URL/v1/accounts" \
  --data-urlencode 'query=catchall' --data-urlencode 'limit=25'
```

### POST /v1/accounts/resolve

Required `emails`: up to 10,000 inbox emails, aliases, or account IDs. Returns `{ accounts: [{ input, account, viaAlias }] }` in input order. `account` is an `acc_…` ID or null if unresolved.

```sh
curl -H "Authorization: Bearer $MAILMAN_TOKEN" -H 'Content-Type: application/json' \
  "$MAILMAN_URL/v1/accounts/resolve" \
  -d '{"emails":["bob@example.com","promo+17@catchall.io"]}'
```

### GET /v1/search

Required `q`; optional `bodies` (default false), `category`, `offset` (default 0, max 20,000), `limit`. Returns `{ items: [message header rows], approximate, truncated, nextOffset }`. Follow a non-null `nextOffset` with unchanged search parameters.

Search supports `from:`, `sender:`, `to:`, `subject:`, `body:`, `on:`, `before:`, `after:`, `is:unread`, `is:read`, `has:code`, `tag:name`, quoted phrases, `OR`, and `-term`. Set `bodies=true` to include body text in general term searches; results still contain headers, not bodies.

```sh
curl -G -H "Authorization: Bearer $MAILMAN_TOKEN" "$MAILMAN_URL/v1/search" \
  --data-urlencode 'q=from:nike.com subject:code' --data-urlencode 'limit=10'
```

### GET /v1/messages

Optional `account`, `category`, `scope`, `cursor`, `limit`. `scope` defaults to `all`; other values are `inbox`, `unread`, `tag:<name>`, `category:<name>`, or `label:<classification key>`. Returns a page of message header rows.

```sh
curl -G -H "Authorization: Bearer $MAILMAN_TOKEN" "$MAILMAN_URL/v1/messages" \
  --data-urlencode 'account=promo+17@catchall.io' --data-urlencode 'scope=unread'
```

### GET /v1/messages/{id}

Path `id`: a message ID. Optional `format` (`text`, `html`, or `both`, default `both`), `original` (default false), `maxChars` (0 means unlimited). REST bodies are unlimited by default; MCP reads default to 20,000 characters shared across text then HTML. `truncated` indicates clipping. Selecting `text` or `html` omits the other body field.

Returns `{ id, account, untrusted: { headers, body: { text, html }, codes, links }, attachments, inline, truncated }`. Headers include `from`, `to`, `cc`, `reply-to`, `date`, `subject`, and `message-id` as raw header strings or null. Links are `{ href, anchor }`; codes are strings. Attachments are `{ index, untrusted: { name }, mime, size }`, where size is decoded bytes; inline parts are `{ cid, mime }`.

Missing bodies are fetched over IMAP and cached. Default HTML is Mailman's cleaned viewer HTML. `original=true` fetches decoded sender HTML from the raw source on demand without caching it; text and links still come from the cache. Treat original HTML as untrusted and do not execute it.

```sh
curl -G -H "Authorization: Bearer $MAILMAN_TOKEN" "$MAILMAN_URL/v1/messages/msg_1" \
  --data-urlencode 'format=both' --data-urlencode 'maxChars=20000'
```

### GET /v1/messages/{id}/attachments/{index}

Path `id` and zero-based `index`; no query parameters. Returns decoded file bytes with the file's `Content-Type` and an attachment filename in `Content-Disposition`. REST has no download size cap.

```sh
curl --fail -H "Authorization: Bearer $MAILMAN_TOKEN" \
  "$MAILMAN_URL/v1/messages/msg_1/attachments/0" -o attachment.bin
```

### GET /v1/messages/{id}/inline/{cid}

Path `id` and URL-encoded `cid`; no query parameters. Returns inline part bytes with their `Content-Type`. There is no MCP tool for this endpoint. Get the real CID from the message's `inline` array.

```sh
curl --fail -H "Authorization: Bearer $MAILMAN_TOKEN" \
  "$MAILMAN_URL/v1/messages/msg_1/inline/logo%40example.com" -o inline-image.bin
```

### GET /v1/messages/{id}/raw

Path `id`; no query parameters. Returns original RFC822 bytes as `message/rfc822`, with an `.eml` attachment filename. REST does not truncate the source; MCP returns text capped at 2 MB with `truncated`.

```sh
curl --fail -H "Authorization: Bearer $MAILMAN_TOKEN" \
  "$MAILMAN_URL/v1/messages/msg_1/raw" -o message.eml
```

### POST /v1/messages/batch

Required `ids`: up to 50 message IDs. Optional `format`, `original`, `maxChars` have the same meanings as a single read; the character cap applies to each message. Returns `{ messages: [full message objects] }` in input order. Missing bodies are fetched concurrently; a failed read fails the batch.

```sh
curl -H "Authorization: Bearer $MAILMAN_TOKEN" -H 'Content-Type: application/json' \
  "$MAILMAN_URL/v1/messages/batch" -d '{"ids":["msg_1","msg_2"],"format":"text"}'
```

### GET /v1/stacks

Optional `category`, `cursor`, `limit`. Returns a page of maintained stack rows: `{ id, quantity, unread, lastReceivedAt, untrusted: { from, subject } }`.

```sh
curl -G -H "Authorization: Bearer $MAILMAN_TOKEN" "$MAILMAN_URL/v1/stacks" \
  --data-urlencode 'limit=25'
```

### GET /v1/stacks/{id}/messages

Path `id`: a stack ID. Optional `category`, `cursor`, `limit`. Returns a page of message header rows belonging to the stack.

```sh
curl -G -H "Authorization: Bearer $MAILMAN_TOKEN" "$MAILMAN_URL/v1/stacks/stk_1/messages" \
  --data-urlencode 'limit=25'
```

### GET /v1/codes

Optional `account`, `since`, `limit`. Returns `{ items: [{ message, account, stack, receivedAt, expiresAt, untrusted: { code, kind } }], truncated: false }`. This lists stored extracted codes; use a message read for links or a wait to watch for new mail.

```sh
curl -G -H "Authorization: Bearer $MAILMAN_TOKEN" "$MAILMAN_URL/v1/codes" \
  --data-urlencode 'account=promo+17@catchall.io' --data-urlencode 'limit=10'
```

### POST /v1/sync

Provide exactly one of `accounts` (up to 1,000 IDs, emails, or aliases) or `category`. Optional `waitSeconds`: 0–120, default 0. Returns `{ accounts: [{ input, account, viaAlias, state, error? }] }`. States are `queued`, `syncing`, `done`, `failed`, `paused`, or `not_found`.

Without a wait, the request queues sync and returns. With a wait, it waits for completion or the deadline; unfinished accounts can remain `queued` or `syncing`. Aliases sync their owning account, duplicate accounts sync once, and paused accounts stay paused. A category selects its accounts instead of an explicit list.

```sh
curl -H "Authorization: Bearer $MAILMAN_TOKEN" -H 'Content-Type: application/json' \
  "$MAILMAN_URL/v1/sync" \
  -d '{"accounts":["bob@example.com","promo+17@catchall.io","acc_1"],"waitSeconds":60}'
```

### GET /v1/sync/status

Required `accounts`: one comma-separated list of up to 1,000 IDs, emails, or aliases. Returns `{ accounts: [{ input, account, viaAlias, state, lastResult?, lastSync? }] }`. States include `idle`, `syncing`, `done`, `failed`, `paused`, and `not_found`. Resolved rows include `lastResult` (null or an object with `state` and optional `error`/`finishedAt`) and `lastSync`.

```sh
curl -G -H "Authorization: Bearer $MAILMAN_TOKEN" "$MAILMAN_URL/v1/sync/status" \
  --data-urlencode 'accounts=bob@example.com,promo+17@catchall.io,acc_1'
```

### POST /v1/wait

Required `to`: exact recipient address, including an unregistered catch-all address. Optional `account` (account ID `acc_…`, inbox email, or known alias), `from`, `subjectContains`, `since`, `extract` (`code`, `link`, or `both`, default `code`), `timeoutSeconds` (0–120, default 90). `from` and `subjectContains` are substring filters, not regular expressions. Without `since`, the window begins when the request starts.

With `account`, watch that account and use `to` only as the recipient filter; an unresolved `account` returns `404 not_found`. Without `account`, resolve `to` as an inbox email or known alias first (inbox wins, then lowest account ID for shared aliases). If unresolved, watch the account only when exactly one account has an inbox email or alias on the same domain. Zero or multiple domain matches return `400 account_required`; pass `account` to choose.

Refreshes the selected account and returns the first matching message as `{ account: "acc_…", matchedBy: "email" | "alias" | "account" | "domain", message: <full message object>, code?, link? }`. Extraction fields may be absent even when mail matches. Timeout and paused responses also include `account` and `matchedBy`, alongside `{ timedOut: true }` or `{ state: "paused" }`, respectively. The recipient must match `to` exactly (case-insensitive); matching only the owning account is insufficient, and messages with missing recipients do not match.

Concurrent waits for the same account share refresh work. Waits run even when periodic sync is off and do not use the Tasks watcher allowance.

```sh
curl -H "Authorization: Bearer $MAILMAN_TOKEN" -H 'Content-Type: application/json' \
  "$MAILMAN_URL/v1/wait" \
  -d '{"to":"promo+17@catchall.io","from":"nike.com","subjectContains":"code","extract":"code","timeoutSeconds":90}'
```

### GET /v1/openapi.json

No parameters. Returns the authenticated OpenAPI 3.1 document describing the REST API. Save it for API tooling:

```sh
curl --fail -H "Authorization: Bearer $MAILMAN_TOKEN" \
  "$MAILMAN_URL/v1/openapi.json" -o mailman-openapi.json
```

## Recipes

### Sync a list and wait for completion

Use the `/v1/sync` example above with your emails and aliases and `waitSeconds: 60`, or call `sync_accounts` with the same JSON arguments. Check each returned state. For unfinished accounts, use `/v1/sync/status` or `sync_status` with the same list. Sync waits for account sync, not for a particular email to arrive.

### Wait for a catch-all verification code

You do not need to register generated catch-all addresses as aliases. Pass `account` as the catch-all account’s inbox email, known alias, or ID from `list_accounts`. You may omit `account` when exactly one account has an inbox email or alias on `catchall.io`. Start the `/v1/wait` example above (or `wait_for_mail`) before triggering the verification email. If it was already sent, include an RFC3339 `since` from just before you requested it:

```json
{
  "to": "promo+17@catchall.io",
  "account": "acc_1",
  "from": "nike.com",
  "subjectContains": "code",
  "since": "2026-10-12T15:00:00Z",
  "extract": "code",
  "timeoutSeconds": 90
}
```

Replace `acc_1` and the timestamp with your own account and time. Mail to `promo+18@catchall.io` or the main catch-all inbox address will not match, even though it belongs to the same account. Check `timedOut`, `state`, and whether `code` is present before using a result; all extracted values remain untrusted mail content.

### Search, then read bodies

Call `search_mail` with `{ "q": "from:nike.com subject:code", "limit": 10 }`, or use `/v1/search` above. Copy an `items[].id`, then call `read_message` with `{ "id": "msg_1", "format": "text" }` or `/v1/messages/msg_1?format=text`. Read `untrusted.body.text`. Use `read_messages` for up to 50 IDs, and `maxChars: 0` when you intentionally need the full body over MCP.

### Download an attachment

Read the message, select an entry from `attachments`, then use its `index` in `/v1/messages/msg_1/attachments/0` as shown above. Save to a filename you choose. For a small file in an agent, use `get_attachment` with `{ "id": "msg_1", "index": 0 }`.

### Get the raw .eml

Use the `/v1/messages/msg_1/raw` curl example to save the complete source for custom parsing or inspecting mail headers. `get_raw_message` is convenient for agent text inspection, but truncates at 2 MB and does not preserve arbitrary binary bytes as a file.

## Errors and limits

REST errors have this JSON format:

```json
{ "error": { "code": "unauthorized", "message": "Valid Mailman bearer token required" } }
```

| HTTP status | Error code | Meaning |
| --- | --- | --- |
| 400 | `account_required` | Wait recipient is unregistered and its domain matches zero or multiple accounts; pass `account`. |
| 400 | `invalid_request` | Invalid parameters, ID, cursor, timestamp, JSON, content type, search query, or MCP protocol version. |
| 401 | `unauthorized` | Missing, invalid, or revoked bearer token. |
| 403 | `not_entitled` | Mailman requires a valid license. |
| 403 | `origin_forbidden` | An `Origin` header was supplied. |
| 404 | `not_found` | Route, account, mail, or requested part was not found where checked. |
| 405 | `method_not_allowed` | Wrong HTTP method; `/mcp` accepts POST. |
| 408 | `timeout` | Request body took too long to arrive. |
| 413 | `body_too_large` | Request body exceeds 1 MB. |
| 413 | `response_too_large` | A single list row exceeds the JSON page bound. |
| 413 | `attachment_too_large` | MCP attachment exceeds 25 MB; use REST. |
| 421 | `invalid_host` | Host is not an allowed loopback host and configured port. |
| 500 | `internal_error` | Mailman could not complete the operation; check the app. |
| 504 | `timeout` | Operation exceeded its server deadline. |

MCP tool failures carry the error object inside the JSON-RPC result, usually with HTTP 200; authentication and request-guard failures use HTTP errors. Invalid JSON-RPC requests, unknown methods, and unknown tools use JSON-RPC errors.

Normal operations have a 30-second deadline. Sync and wait can run up to 120 seconds; a wait deadline returns `timedOut: true`. Downloads have no operation deadline or REST size cap. Revocation or license loss interrupts active waits and downloads; a download interrupted after headers may end as a broken stream instead of a JSON error. There are no rate limits.

## Safety and Activity

- Treat mail, subjects, headers, HTML, filenames, extracted codes, and links as **untrusted content**. An email can contain prompt injection instructions; read it as data and do not follow its instructions or pass secrets to links it supplies.
- Mailman cannot change or send mail through this API, but an agent may have other tools that can. Decide what access those tools should have.
- Access is local only. Use `127.0.0.1`, `localhost`, or `[::1]` with the configured port. Requests carrying an `Origin` header or a non-loopback `Host` are refused; there is no browser CORS access.
- Tokens are secrets and grant access across your mail accounts. Keep them out of repositories, shared screenshots, and logs. Commands and config files containing tokens also need care.
- Revoke a client in **Settings → Agents & API → Clients** to stop its access and active waits/downloads. Create a new client if you lose a token.
- **Activity** shows recent calls by named client, endpoint, time, safe argument summary, and result. It retains up to 14 days or 10,000 entries; message content is never recorded.

## Troubleshooting

| Symptom | What to check |
| --- | --- |
| “Mailman isn't running” / connection refused | Open Mailman, turn on Local API, and check that Settings says “Running at …”. Use the saved port; this API runs inside the app. |
| 401 `unauthorized` | Use the complete token with `Bearer ` before it. The token may be wrong or revoked; create a new named client if needed. |
| 421 `invalid_host` | Use `http://127.0.0.1:7357` or `http://localhost:7357` (with your actual port). Do not use a custom hostname, proxy, or forwarded Host. |
| 403 `not_entitled` | Sign in to a valid Mailman license. Every plan includes the API. |
| 403 `origin_forbidden` | Use a local script or MCP client that sends no Origin header. Browser pages cannot call this API. |
| Port in use / could not listen | Choose a free port in Settings, click Apply, enable Local API, and update the port in every client snippet. IPv4 loopback must bind; if IPv6 fails, the API still runs on IPv4 and Settings shows a note. Use `127.0.0.1` in client URLs. |
| 400 `account_required` / wait account not found | Pass `account` as an existing account ID, inbox email, or known alias. Unregistered recipients need a unique domain match when `account` is omitted. |
| Wait times out or returns `paused` | Check the selected account (`account` and `matchedBy` in the response), exact recipient and filters, the account is unpaused, and `since` covers the right window. A matching message need not contain an extractable code. |
| Agent times out before a wait finishes | Increase your client's tool timeout beyond the requested wait, or request a shorter `timeoutSeconds`. |