# MailServiceNow for AI agents

Single system of record for integrating MailServiceNow as a customer-domain inbox and outbound email backend.
An agent can fetch this file and implement against it without reading the website.

- Docs revision: **2026-10-07**
- API / MCP server version: **0.8.0**
- Canonical OAuth protocol: MCP **2025-11-25** / **2025-06-18**, sessionless Streamable HTTP with JSON responses
- Direct-function legacy compatibility: JSON-RPC **2024-11-05** dialect; not HTTP+SSE
- OpenAPI: <https://mailservicenow.com/docs/openapi.json>
- Developers: <https://mailservicenow.com/developers/>
- This file: <https://mailservicenow.com/docs/mailservicenow-for-ai.md>
- llms.txt: <https://mailservicenow.com/llms.txt>

Never put a real key in source, tickets, or prompts. Examples use `msn_<your-key>`.

## Recommended: one resumable OAuth flow

Use the [resumable owner-approved onboarding guide](/docs/agent-onboarding.md) with canonical MCP resource `https://mailservicenow.com/api/mcp`. The owner approves one domain, one exact mailbox and explicit scopes through OAuth; credentials stay in the connector transport and never appear in MCP results. The connector platform controls storage.

`start_onboarding` accepts `idempotencyKey`, `domain`, `localPart` and returns one durable `onboardingId`. `get_onboarding_status`, `resume_onboarding` and `renew_onboarding_proof` use that ID under the same owner/scoped authentication. The result separates owner approval, account identity, service approval, ownership, exact DNS changes, mailbox creation and current mail-server readiness. Publish DNS through an independently authorized provider connection or owner handoff; this service has no Cloudflare write connection.

Customer-domain inbox access is supported: `list_inbox`, `get_message`, `search_mailbox`, `send_mail`, and `reply_to_message` read/search/send/reply in the exact approved hosted/both mailbox. Forward-only addresses have no inbox. Readiness requires exact current-configuration mail-server acknowledgement with a valid timestamp and fresh successful sync/service health, not just the legacy `mtaApplied` flag; inbound delivery remains `not_tested`. The owner can revoke one agent at [/oauth-consent.html](/oauth-consent.html) without invalidating other clients.

The older key-based flow below remains for compatibility. Public `get_request_status` requires `requestId` plus `email` or `username`, as its schema now states; the new private `get_onboarding_status` requires only the onboarding ID. Legacy DNS account-key recovery still revokes all legacy keys for that account, so it should not be used for per-agent OAuth recovery.

## Agents can sign up themselves (legacy key flow)

An agent can request access, prove control of an email address or domain, check the decision, obtain its own customer key, and configure its domain and mailboxes using MCP or REST. It cannot approve itself. Unmatched requests still need a Mail Service Now owner/admin decision. Reading a verification email, publishing DNS, saving credentials, changing mail routing, and sending mail require the account owner's authorization and appropriate access in the agent's environment. This service does not provide that external access.

Start with [the end-to-end checklist](#agent-onboarding-sequence). Approval, possession of an API key, mail DNS verification, and live mailbox delivery are separate checkpoints. Pricing remains tailored through Contact/Apply; signup does not purchase a plan.

Sign up with a username. An email is optional. A username is 3 to 64 characters: letters, digits, and `.` `_` `-` `+` `@`. It is stored case-insensitively. Reserved names such as admin, root, postmaster, and abuse are refused. A username that looks like an email is not a verified email. No mail is sent to it.

If you pass `contactEmail`, the 8-digit email code flow is unchanged.

If you omit `contactEmail`, pass `username`, `domain`, `agentName`, and `intendedUse`. The response includes a TXT record. Publish it at exactly `_msn-verify.<domain>` (that name only). The token expires in 24 hours and works once. Then call `verify_access_request` with `requestId` and `method` `dns`. Poll `get_request_status` with `requestId` and `username`. `status` `ready` means the account is ready. The key is returned once, on the verify call when the account is ready, or on a fresh `request_access` plus `verify_access_request` after it becomes ready. `get_request_status` does not return the key. Then call `get_account_status` with the key.

`mailservicenow.com` and its subdomains cannot use this DNS check.

Lost the key and have no email: call `request_access` again with the same username and the account domain, publish the new TXT at `_msn-verify.<domain>`, and verify with `method` `dns`. A new key is returned once. For a DNS-bound account this rotates and revokes all previous customer keys for that account; coordinate recovery with any other clients. Email re-verification instead issues an additional key without revoking existing keys.

```bash
export MSN_API_BASE=https://us-central1-mailservicenow.cloudfunctions.net
curl -sS -X POST "$MSN_API_BASE/requestAccess" \
  -H "Content-Type: application/json" \
  -d '{"username":"agent-one","domain":"example-domain.com","agentName":"ExampleAgent","intendedUse":"Send a notification from an agent"}'
curl -sS -X POST "$MSN_API_BASE/verifyAccessRequest" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"ar_0123456789abcdef01234567","method":"dns"}'
curl -sS -X POST "$MSN_API_BASE/getRequestStatus" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"ar_0123456789abcdef01234567","username":"agent-one"}'
```

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"request_access","arguments":{"username":"agent-one","domain":"example-domain.com","agentName":"ExampleAgent","intendedUse":"Send a notification from an agent"}}}
```

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"verify_access_request","arguments":{"requestId":"ar_0123456789abcdef01234567","method":"dns"}}}
```

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_request_status","arguments":{"requestId":"ar_0123456789abcdef01234567","username":"agent-one"}}}
```

POST that JSON to `https://us-central1-mailservicenow.cloudfunctions.net/mcp` with `Content-Type: application/json` and no `Authorization` header.

A `ready` response and a standard key do not publish mail DNS or create mailboxes. Email signup does not add the domain; successful DNS signup/approval may already claim and add its verified hostname. Read `GET /listDomains` before provisioning. After the key, follow [After you have a standard key: set up your domain and mailboxes](#after-you-have-a-standard-key-set-up-your-domain-and-mailboxes).

## What this product is

Mail Service Now hosts mailboxes and forwarding on a domain you own, and lets software send and read that mail over HTTPS.
A hosted mailbox on a verified domain opens in the web app.
An agent requests its own key with `request_access` or `POST /api/requestAccess`.
The shared `inbox@mailservicenow.com` mailbox stays with Mail Service Now.

Callers do not open SMTP. Always set `from` on `sendMail` and `send_mail`.

## How mail is sent

| Fact | Value |
| --- | --- |
| Mail host | `mail.mailservicenow.com`. The sending address is the SPF value on the domain card |
| How you send | Call HTTPS. The service submits on port **587** with STARTTLS. |
| From | Always set `from` to an address on a verified domain you own, for example `support@example-domain.com`. If it is omitted and the account has exactly one sendable hosted mailbox, that mailbox is used as a fallback. The shared agent key sends as `"Mail Service Now" <noreply@mailservicenow.com>`. |
| Inbound MX | `mail.mailservicenow.com` |
| Shared mailbox that stays with Mail Service Now | `inbox@mailservicenow.com` |

Callers do not open SMTP. Always set `from` on the HTTPS send.

## Base URLs

For scoped OAuth, use only the canonical resource `https://mailservicenow.com/api/mcp`. For the legacy key/REST examples below, the Cloud Functions host and Hosting rewrites hit the same functions.

| Surface | Functions (preferred) | Hosting rewrite |
| --- | --- | --- |
| sendMail | `POST https://us-central1-mailservicenow.cloudfunctions.net/sendMail` | `POST https://mailservicenow.com/api/sendMail` |
| MCP | `GET` or `POST https://us-central1-mailservicenow.cloudfunctions.net/mcp` | `https://mailservicenow.com/api/mcp` |
| inbox | `GET https://us-central1-mailservicenow.cloudfunctions.net/inbox` | `GET https://mailservicenow.com/api/inbox` |
| drafts | `GET`, `POST`, or `DELETE https://us-central1-mailservicenow.cloudfunctions.net/drafts` | `https://mailservicenow.com/api/drafts` |
| webhooks | `GET`, `POST`, or `DELETE https://us-central1-mailservicenow.cloudfunctions.net/webhooks` | `https://mailservicenow.com/api/webhooks` |
| credits | `GET` or `POST https://us-central1-mailservicenow.cloudfunctions.net/credits` | `https://mailservicenow.com/api/credits` |
| requestAccess | `POST https://us-central1-mailservicenow.cloudfunctions.net/requestAccess` | `POST https://mailservicenow.com/api/requestAccess` |
| verifyAccessRequest | `POST https://us-central1-mailservicenow.cloudfunctions.net/verifyAccessRequest` | `POST https://mailservicenow.com/api/verifyAccessRequest` |
| addDomain | `POST https://us-central1-mailservicenow.cloudfunctions.net/addDomain` | `POST https://mailservicenow.com/api/addDomain` |
| listDomains | `GET https://us-central1-mailservicenow.cloudfunctions.net/listDomains` | `GET https://mailservicenow.com/api/listDomains` |
| getDnsInstructions | `GET https://us-central1-mailservicenow.cloudfunctions.net/getDnsInstructions` | `GET https://mailservicenow.com/api/getDnsInstructions` |
| verifyDomain | `POST https://us-central1-mailservicenow.cloudfunctions.net/verifyDomain` | `POST https://mailservicenow.com/api/verifyDomain` |
| addMailbox | `POST https://us-central1-mailservicenow.cloudfunctions.net/addMailbox` | `POST https://mailservicenow.com/api/addMailbox` |

`https://mailservicenow.web.app/api/...` is the same rewrite set as the apex host.

Suggested integrator environment (names only; values are yours):

```bash
MSN_API_BASE=https://us-central1-mailservicenow.cloudfunctions.net
MSN_AGENT_API_KEY=msn_<your-key>
```

## Authentication

Use no credential for bootstrap; use the returned standard customer key for your own account afterward.

| Caller | Credential | Supported onboarding access |
| --- | --- | --- |
| New applicant | None | MCP discovery, initialize, tools/list, ping, request_access, verify_access_request, get_request_status; matching public REST routes |
| Customer agent | Its own standard `msn_…` key | Account status, own domains/mailboxes, customer mail tools and REST webhooks |
| Signed-in account owner | Firebase ID token | Own REST domain/mailbox routes and MCP mailbox tools after approval; not `get_account_status`, which requires the customer key |
| Service owner/admin | Verified Firebase ID token with the required staff permission | Review/approval routes and permitted operator MCP tools |
| Legacy shared agent | Shared service key | Legacy shared mail tools; not customer domain/mailbox setup or customer account status |

For customer calls, use `Authorization: Bearer msn_<your-key>` or `X-Api-Key: msn_<your-key>`. If `X-Api-Key` is present it is the only credential checked; do not send conflicting headers. A three-part Bearer token is treated as a Firebase JWT. A customer key does not grant staff permissions even if its contact email belongs to an administrator. The MTA sync credential is not accepted for signup or MCP.

`GET /mcp` and public-only JSON-RPC batches need no key. A batch containing any protected tool requires authentication for the whole batch. `tools/list` is discovery, not a permission grant: it normally includes protected tools even for an anonymous caller (support-role listings are filtered). After signup, send protected requests separately with the account key. For authenticated discovery use the Bearer header: the public bootstrap branch only attempts optional authentication when `Authorization` is present.

Browser clients may call the HTTPS functions: responses include `Access-Control-Allow-Origin: *`. Preflight `OPTIONS` returns **204**.

## Credits

- A validated **agent** send (`sendMail` with an agent key, or MCP `send_mail`) deducts **1 credit before SMTP submission**. An SMTP failure does not automatically refund that credit.
- The default agent key starts at **100** credits (`agent_credits/default`). This file does not state a price.
- Signed-in humans authenticated with a Firebase ID token are **not** charged. Customer users must have a ready account and a sendable hosted mailbox; unauthorized or unready requests are denied before sending.
- `get_credits`, `GET /credits`, `list_inbox`, `get_message`, `mark_read`, `GET /inbox`, `POST /inbox`, and `/webhooks` do not spend credits.
- At 0 credits the send returns **429** with `error` exactly `Insufficient credits`. That is the same HTTP status as the rate limit; branch on the `error` string.
- The credit is decremented **after** input validation and **before** SMTP. If the MTA then fails, the credit stays spent. A **429** rate limit or **400** validation error does not spend a credit. A **503** kill switch does not spend a credit. An auth failure is **401** and does not spend a credit.
- Signed-in humans see the same agent balance in **Settings** on `/app.html`. That screen is a status view, not billing. `GET /credits` is the API behind it. MCP `get_credits` still returns only `{ "ok": true, "remaining" }`.

## Rate limits

Enforced per caller id. The agent key’s id is `agent:default` (one shared bucket for every agent send). Each Firebase user has their own bucket. Counters are UTC.

| Route | Burst | Daily | HTTP |
| --- | --- | --- | --- |
| `sendMail` and MCP `send_mail` | 5 per minute | 50 per UTC day | 429 `Rate limit exceeded` |
| `GET /inbox` (including `q=`), `POST /inbox`, `GET /attachment`, `/drafts`, `/webhooks`, `GET /credits`, `POST /credits`, MCP `list_inbox`, `get_message`, `get_credits`, `mark_read` | none | none | — |

On `sendMail` / `send_mail` the order is: global kill switch, then agent-key disable (agent callers only), then rate limit, then body validation, then credit, then SMTP. A request that later fails validation has already consumed one rate-limit slot. A kill-switch **503** has not.

`GET /mcp` (discovery) is unauthenticated and is not rate limited by this function.

## Kill switch

Admins freeze sends without a redeploy. Both flags are checked on `sendMail` and MCP `send_mail` after auth and **before** the rate limit and the credit decrement. A frozen send does not spend a credit. Inbox reads, `get_credits`, and `GET /credits` keep working. A bad credential is still **401** and never reaches these flags.

| Flag | Firestore | Who it blocks | HTTP |
| --- | --- | --- | --- |
| Pause all sending | `config/send.enabled === false`. A missing document means sending is on. | Humans and agents | **503** `Sending temporarily disabled` |
| Disable the agent key | `agent_keys/default.disabled === true`, or `frozenUntil` set to a time still in the future | Agent `sendMail` and MCP `send_mail` only. Human Firebase sends continue. | **503** `Agent key disabled` |

Signed-in admin accounts change both flags from **Settings** on `/app.html` (Agent credits). The response field `canControl` is true for the agent key and for those admin accounts. `canPauseAll` is true only for an admin Firebase account. Any other signed-in user can read the balance and the key status. Their `POST /credits` is **403** `Operator control requires the agent key or an operator account`. The agent key can freeze and unfreeze itself. It cannot pause every sender: that `POST` is **403** `Pausing all sending requires an operator account`.

`GET /credits` with the agent key or a Firebase ID token:

```bash
curl -sS "$MSN_API_BASE/credits" \
  -H "Authorization: Bearer $MSN_AGENT_API_KEY"
```

```json
{
  "ok": true,
  "credits": { "remaining": 100, "initial": 100, "humansCharged": false, "authFailureBurnsCredit": false },
  "agentKey": { "id": "default", "last4": "ab12", "status": "active", "disabled": false, "frozenUntil": null },
  "sending": { "enabled": true },
  "canControl": true,
  "canPauseAll": false,
  "docs": "https://mailservicenow.com/developers/#credits"
}
```

`last4` is the last four characters of the server-side key. The full key is not returned. `status` is `active` or `disabled`.

Customer API keys and mailbox IMAP/SMTP passwords are separate credentials. Customer API authentication rechecks account approval on each call; do not assume suspending an account or rotating its API key instantly invalidates an already issued IMAP/SMTP password. The existing mail-server credential lifecycle needs separate operator handling.

Freeze and unfreeze the default agent key:

```bash
curl -sS -X POST "$MSN_API_BASE/credits" \
  -H "Authorization: Bearer $MSN_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disabled":true}'
```

Unfreeze with `{"disabled":false}`. A timed freeze is `{"frozenUntil":"2026-09-24T00:00:00.000Z"}`. Clear it with `{"frozenUntil":null}`. An admin Firebase token may also send `{"sendingEnabled":false}` to pause every sender, and `{"sendingEnabled":true}` to resume. While the key is disabled, agent `sendMail` and MCP `send_mail` return **503** `Agent key disabled` and the credit counter does not move.

## sendMail

`POST` `Content-Type: application/json`

```json
{
  "to": "recipient@example.com",
  "from": "support@example-domain.com",
  "subject": "Hello from an agent",
  "text": "Sent via MailServiceNow."
}
```

- `to` is one address, a comma- or semicolon-separated string, or a JSON array of addresses. Maximum **5** recipients.
- `subject` and at least one readable body (`text` or `html`) are required. Body fields must be strings; `subject` is limited to 998 UTF-8 bytes.
- Optional `html` sends a multipart/alternative email. If `text` is omitted or blank, the server generates a readable fallback with paragraphs, list items, table cells, link destinations, and image alt text. Supplied nonblank `text` is preserved.
- Combined `text` + `html` is capped at **100KiB UTF-8**, checked on both the supplied input and sanitized output including generated fallback. Encoded MIME is capped at **6MiB** before credits are charged, equally on REST and MCP.
- HTML is sanitized to semantic tags, tables, links, and images. Scripts, forms, styles, classes, IDs, SVG/MathML, frames, event handlers, and unsafe URLs are removed. Links require explicit HTTP, HTTPS, or mailto; image URLs require HTTPS with a non-local hostname. CID/data images are unsupported. The server never fetches HTML resources. The web inbox blocks remote images until the reader opts in; loading images can reveal the reader's IP address and email-open timing.
- Always set `from` to an address on a verified domain you own, for example `support@example-domain.com`. If it's omitted and the account has exactly one sendable hosted mailbox, that mailbox is used as a fallback; with more than one, omitting `from` is an error (**400** `Choose the address to send from.`). The shared agent key sends as `noreply@mailservicenow.com`.
- Optional `inReplyTo` (one Message-ID) and `references` (Message-IDs) are copied onto the SMTP message. When either is set, the sent copy is filed on that inbox thread. Invalid values are **400** `Invalid inReplyTo` or `Invalid references`. Omit both for a normal send.
- Optional `attachments` is an array of `{ "filename", "contentType", "contentBase64" }`. Limits: **3 files**, **2MB** each, **4MB** total decoded. Allowed types: JPEG, PNG, GIF, WebP, PDF, plain text, CSV, and Office Open XML (docx, xlsx, pptx). Bytes are not stored in Firestore. A threaded send stores them in Firebase Storage and returns `attachmentCount` plus `attachmentsStored`. A send with no thread link still attaches the files on the SMTP message but does not file a copy in the inbox. Set `from` on that send the same way as any other send. MCP `send_mail` rejects attachments.

HTML example, using the same endpoint and authentication:

```json
{
  "to": "recipient@example.com",
  "from": "support@example-domain.com",
  "subject": "Project update",
  "html": "<h2>Project update</h2><p>The next milestone is <strong>ready for review</strong>.</p>",
  "text": "Project update: The next milestone is ready for review."
}
```

To send a client-rendered template as HTML, put the rendered markup in `html`, not in `text`. Template CSS is stripped by the same sanitizer; previews are not a guarantee that arbitrary template styling survives delivery. Omitting `html` continues to send a plain-text email. MailServiceNow does not render template variables on the server.

Agent success **200**:

```json
{
  "ok": true,
  "messageId": "<id@mail.mailservicenow.com>",
  "creditsRemaining": 99
}
```

Human success **200** omits `creditsRemaining`:

```json
{
  "ok": true,
  "messageId": "<id@mail.mailservicenow.com>"
}
```

`messageId` is the SMTP Message-ID assigned by the MTA. A threaded send may also include `threadId` (64 hex chars). `list_inbox` stays a flat message list.

### curl

```bash
curl -sS -X POST \
  "$MSN_API_BASE/sendMail" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "from": "support@example-domain.com",
    "subject": "Hello from an agent",
    "text": "Sent via MailServiceNow agent API."
  }'
```

Equivalent header: `-H "X-Api-Key: msn_<your-key>"` (do not send a wrong `X-Api-Key` alongside a good Bearer token; the key header wins).

### Node.js

```js
const base = process.env.MSN_API_BASE;
const key = process.env.MSN_AGENT_API_KEY; // msn_<your-key>
const res = await fetch(`${base}/sendMail`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "recipient@example.com",
    from: "support@example-domain.com",
    subject: "Hello from an agent",
    text: "Sent via MailServiceNow.",
  }),
});
const data = await res.json();
if (!res.ok || !data.ok) {
  throw new Error(`${res.status} ${data.error || "send failed"}`);
}
// data.messageId, data.creditsRemaining (agents only)
```

### Python

```python
import json, os, urllib.request
req = urllib.request.Request(
    os.environ["MSN_API_BASE"] + "/sendMail",
    data=json.dumps({
        "to": "recipient@example.com",
        "from": "support@example-domain.com",
        "subject": "Hello from an agent",
        "text": "Sent via MailServiceNow.",
    }).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["MSN_AGENT_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(req) as res:
    data = json.load(res)
# data["messageId"], data.get("creditsRemaining")
```

## inbox

`GET` with the same agent key or an admin Firebase ID token. Any other Firebase user is **403**. No credits. Listing does not mark mail read. Fetching one message does.

List (default `limit` 25, max 50):

```bash
curl -sS \
  "$MSN_API_BASE/inbox?limit=25" \
  -H "Authorization: Bearer msn_<your-key>"
```

```json
{
  "ok": true,
  "messages": [
    {
      "id": "firestore-doc-id",
      "messageId": "<id@mailservicenow.com>",
      "mailbox": "inbox@mailservicenow.com",
      "from": "Person <person@example.com>",
      "to": ["inbox@mailservicenow.com"],
      "subject": "Re: order 1042",
      "preview": "First 180 characters of the plain text…",
      "date": "2026-09-22T18:29:10.000Z",
      "ingestedAt": "2026-09-22T18:31:13.049Z",
      "unread": true,
      "folder": "inbox",
      "source": "maildir"
    }
  ],
  "unreadInPage": 1
}
```

`unreadInPage` counts unread rows **in this page only**. It is not a mailbox total. List rows omit `text` and `html`. Optional `mailbox` must be an `@mailservicenow.com` address (the composite index must exist for that query).

Read one (marks `unread: false`). Pass `id` **or** `messageId`. If both are present, `id` is used.

```bash
curl -sS \
  "$MSN_API_BASE/inbox?id=firestore-doc-id" \
  -H "Authorization: Bearer msn_<your-key>"
```

```json
{
  "ok": true,
  "message": {
    "id": "firestore-doc-id",
    "messageId": "<id@mailservicenow.com>",
    "mailbox": "inbox@mailservicenow.com",
    "from": "Person <person@example.com>",
    "to": ["inbox@mailservicenow.com"],
    "subject": "Re: order 1042",
    "preview": "First 180 characters of the plain text…",
    "date": "2026-09-22T18:29:10.000Z",
    "ingestedAt": "2026-09-22T18:31:13.049Z",
    "unread": false,
    "source": "maildir",
    "text": "Full plain-text body.",
    "html": "<p>Sanitized HTML, when available.</p>"
  }
}
```

`id` must match `^[A-Za-z0-9_-]{1,128}$`. Unknown message: **404** `Message not found`.

Stored messages may include optional `threadId`, `inReplyTo`, `references`, and `folder`. Every message row includes `attachments` (an array, empty when there are none). Each item is `{ "index", "filename", "contentType", "size", "sha256", "preview" }` with `preview` of `image`, `pdf`, `text`, or `download`. The bytes are not in this JSON. Clients that only read the fields above keep working. `GET /inbox` without `q`, `view`, `thread`, or `folder` is still `{ ok, messages, unreadInPage }`. `folder` is `inbox`, `archive`, or `trash`. A missing stored folder is returned as `inbox`. Optional `?folder=` on the flat list keeps only that folder, scanning the newest 200 rows before the limit. Omit `folder` and the flat list stays every folder. `list_inbox` does not send `folder`.

## Threads

Read responses sanitize stored HTML without rewriting raw inbound storage. HTML-only mail gets a readable text fallback. Generated inbound fallback is bounded to **256KiB UTF-8**; markup that expands beyond 256KiB is omitted in favor of text.

Human Inbox (`/app.html`) lists threads. Same auth as inbox. No credits.

List:

```bash
curl -sS \
  "$MSN_API_BASE/inbox?view=threads&limit=25" \
  -H "Authorization: Bearer msn_<your-key>"
```

```json
{
  "ok": true,
  "threads": [
    {
      "threadId": "64-hex-chars",
      "mailbox": "inbox@mailservicenow.com",
      "subject": "P5-1 thread sample",
      "count": 2,
      "preview": "Latest plain-text preview",
      "from": "Ada <ada@example.com>",
      "latestAt": "2026-09-22T22:05:00.000Z",
      "unread": true,
      "unreadCount": 2,
      "folder": "inbox"
    }
  ],
  "unreadThreads": 1,
  "folder": "inbox",
  "inboxUnread": 1
}
```

Open one thread (ordered oldest first, marks inbound rows read):

```bash
curl -sS \
  "$MSN_API_BASE/inbox?thread=64-hex-chars" \
  -H "Authorization: Bearer msn_<your-key>"
```

`thread` must match `^[a-f0-9]{64}$`. Unknown: **404** `Thread not found`. Bad id: **400** `Invalid thread`. `view` other than `threads` is **400** `Invalid view`. If `id` or `messageId` is also set, that single-message read wins and the thread `unreadCount` is refreshed from the remaining unread inbound rows.

`view=threads` defaults to `folder=inbox`. Pass `folder=archive` or `folder=trash` for the other two. `unreadThreads` counts unread rows **in the returned page**. `inboxUnread` counts unread **inbox** threads among the newest 200 thread rows in the mailbox, including when you are listing Archive or Trash. Threads with no `folder` field stay in Inbox.

Opening a thread (`GET /inbox?thread=`) marks every inbound row in it read. `POST /inbox` changes that flag or the folder without spending credits. Same auth as `GET /inbox`. No rate limit.

```bash
curl -sS -X POST \
  "$MSN_API_BASE/inbox" \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"thread":"64-hex-chars","unread":true}'
```

```bash
curl -sS -X POST \
  "$MSN_API_BASE/inbox" \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"thread":"64-hex-chars","folder":"archive"}'
```

`unread` must be a JSON boolean. `folder` is `inbox`, `archive`, or `trash`. The response is `{ "ok": true, "thread", "inboxUnread" }`. Marking a thread unread sets **every inbound row** in that thread unread and sets `unreadCount` to that number. Marking it read clears those flags and sets `unreadCount` to 0. Pass `id` or `messageId` instead of `thread` to change one inbound row; `id` wins when both are present, same as GET. Outbound rows cannot be marked unread (**400** `Only inbound mail can be marked unread`). `folder` always moves the whole thread. A later inbound message files that thread back into Inbox. This is not Gmail: there are no nested labels, snooze, or multi-label threads.

Grouping rule: In-Reply-To / References first (including outbound Message-IDs from a threaded send). If the parent is not stored yet, the thread id is derived from the first reference so the root joins later. If there is no reference, messages in the same mailbox with the same normalized subject share a thread. Empty subjects do not merge. `list_inbox` does not switch to this shape.

## Search

Signed-in substring search. Same auth as inbox. No credits. Does not mark mail read. Not an MCP tool. Optional `folder=inbox|archive|trash` keeps hits in that folder. Omit `folder` and search still covers every folder. Each hit includes `folder`.

```bash
curl -sS \
  "$MSN_API_BASE/inbox?q=P5-1" \
  -H "Authorization: Bearer msn_<your-key>"
```

```json
{
  "ok": true,
  "query": "p5-1",
  "scanned": 3,
  "hits": [
    {
      "id": "998a48dd65455edb88f98ac5f1b60620172abf56d2f4bcbd28e8105d9a416cc3",
      "direction": "inbound",
      "threadId": "ff9b088e3dc69e06daa1346a1e020ffae7bac32de41df5a2c236f406557f4c82",
      "messageId": "<p5-1-root@mailservicenow.com>",
      "mailbox": "inbox@mailservicenow.com",
      "from": "qa@example.com",
      "subject": "P5-1 thread sample",
      "snippet": "Root of the P5-1 sample thread.",
      "matched": ["subject", "body"],
      "date": "2026-09-22T23:00:00.000Z"
    }
  ]
}
```

`q` matches `subject`, `from`, or the plain-text body (HTML only when `text` is empty). Matching is case-insensitive and ignores extra whitespace. The scan is the newest **200** inbound rows and **200** outbound rows in the mailbox (default `inbox@mailservicenow.com`). `hits[].id` is the Firestore document id. `hits[].threadId`, when present, opens that thread. A hit does not include the full body.

Query shorter than 2 characters: **400** `Query must be at least 2 characters`. Longer than 200: **400** `Query too long`. If `id`, `messageId`, or `thread` is also set, that read wins. A non-empty `q` wins over `view` and the flat list. Unauthenticated: **401**.

## Attachments

Human Compose can attach files. `sendMail` accepts the same `attachments` array for a Firebase user or an agent key. `send_mail` does not.

Download one stored file (same auth as inbox, no credit):

```bash
curl -sS -D - -o sample.png \
  "$MSN_API_BASE/attachment?id=FIRESTORE_DOC_ID&index=0&box=inbound" \
  -H "Authorization: Bearer msn_<your-key>"
```

`box` is `inbound` (default) or `outbound`. `index` is the `index` on that message’s `attachments` entry. `disposition=inline` is allowed for image, PDF, and text. Anything else is **400** `Invalid box` or `Invalid attachment index`. Missing file: **404** `Attachment not found`. Unauthenticated: **401**.

Bytes live in Firebase Storage under `mail-attachments/{docId}/{index}-{filename}`. Firestore keeps metadata only. Storage rules deny client SDK access.

## Drafts

Human compose only. Use a Firebase ID token for an eligible staff user or a customer with a ready account. An agent key is **403** `Drafts require a signed-in user`. Drafts are scoped to the authenticated user; no credits are charged. Each draft is a document in Firestore `drafts` with that user's `uid`. The response does not include `uid`. Drafts do not store attachments.

Create:

```bash
curl -sS -X POST \
  "$MSN_API_BASE/drafts" \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"to":"qa@example.com","subject":"P5-4 draft","text":"Saved before send"}'
```

```json
{
  "ok": true,
  "draft": {
    "id": "32-hex-chars",
    "to": "qa@example.com",
    "subject": "P5-4 draft",
    "text": "Saved before send",
    "inReplyTo": "",
    "references": "",
    "createdAt": null,
    "updatedAt": null
  }
}
```

`draft.id` is the Firestore document id. Send the same `to`, `subject`, `text`, and optional `html` with `POST /sendMail`, and always set `from` to an address on a verified domain you own, for example `support@example-domain.com`. The sent SMTP id is `messageId` on that **200**. Then `DELETE /drafts?id=<draft.id>`.

`GET /drafts` lists the newest 25. `GET /drafts?id=` reads one. `POST` with `id` updates that draft. Optional `html` is sanitized and preserved with a combined **100KiB UTF-8** body cap. A blank `text` stays blank while drafting so editing HTML cannot leave a stale generated fallback; the send endpoint derives it from the final HTML. At least one of `to`, `subject`, `text`, readable `html`, or `inReplyTo` must be non-empty. Cap is **50** drafts per user (**400** `Draft limit reached (50)`). Another user's id is **404** `Draft not found`. Unauthenticated: **401**.

## Inbound webhooks

An agent registers one HTTPS URL for the default agent key. When a **new** message is stored, Mail Service Now POSTs `inbound.received` to that URL. Registration does not spend a credit. A failed delivery does not remove the stored message.

```bash
curl -sS -X POST "$MSN_API_BASE/webhooks" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/msn"}'
```

```json
{
  "ok": true,
  "webhook": {
    "url": "https://example.com/hooks/msn",
    "enabled": true,
    "secret": "whsec_<generated>",
    "createdAt": "2026-09-23T16:40:00.000Z",
    "updatedAt": "2026-09-23T16:40:00.000Z"
  }
}
```

`GET /webhooks` returns the same object, including `secret`. `DELETE /webhooks` clears it and returns `{ "ok": true, "webhook": null }`. `POST` again with the same or a new `url` keeps the secret. `"rotateSecret": true` replaces it. `"enabled": false` keeps the row and skips delivery.

Rules:

- `url` is HTTPS, at most 2048 characters, with no username, password, or fragment.
- Loopback, link-local, private, CGNAT, and cloud-metadata hosts are rejected, including DNS answers that point at those addresses. **400** `url host is not allowed` or `url host could not be resolved`.
- A missing credential is **401**. A bad agent key is **401** `Invalid API key`. A bad Firebase JWT is **401** `Invalid or expired ID token`. A verified Firebase user is **403** `Webhooks require an agent API key`.
- There is one URL for the default key (`agent_webhooks/default`). `POST` replaces it.

Event body (compact JSON, this key order). No `text`, `html`, or attachment bytes:

```json
{
  "event": "inbound.received",
  "id": "firestore-doc-id",
  "messageId": "<id@example.com>",
  "from": "Person <person@example.com>",
  "to": ["inbox@mailservicenow.com"],
  "subject": "Hello",
  "preview": "Plain text",
  "timestamp": "2026-09-23T16:40:00.000Z",
  "mailbox": "inbox@mailservicenow.com"
}
```

Headers:

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |
| `User-Agent` | `MailServiceNow-Webhook/1` |
| `X-MSN-Event` | `inbound.received` |
| `X-MSN-Timestamp` | Unix seconds |
| `X-MSN-Signature` | `sha256=` plus hex HMAC-SHA256 of `<timestamp>.<raw body>` using the registration secret |
| `X-MSN-Delivery-Attempt` | `1` or `2` |

Verify the signature over the raw body bytes. Do not re-serialize the JSON. Reject timestamps older than five minutes if you need replay protection. The sender does not follow redirects.

Delivery tries twice. A non-2xx response or a connection error waits **750ms**, then tries once more. Each attempt aborts after **5 seconds**. The second failure is written to `webhook_deliveries` (host, status, attempts, message id — not the secret and not the body). The stored message stays. The delivery record has `webhook.delivered: false` and a short `webhook.error`.

## Customer mailbox delivery

Once account setup is complete, the signed-in account chooses a delivery mode when it creates a mailbox and can change it later. `POST /addMailbox` and `POST /setMailboxMode` take `mode` and `forwardTo`. `GET /listDomains` and `GET /webmailMailboxes` return the same fields. MCP tools `add_mailbox` and `set_mailbox_mode` take the same arguments and return the mailbox. `POST /deleteMailbox` and MCP `delete_mailbox` remove the mailbox record. Removing the record does not delete mail stored on the server.

| `mode` | What happens | Login |
| --- | --- | --- |
| `hosted` | Mail is stored in Maildir. `forwardTo` must be empty. On the mail server: vmailbox only. | Webmail and IMAP/SMTP after the domain is verified. |
| `forward` | Mail is relayed to `forwardTo` and nothing is stored. On the mail server: virtual alias only. | No webmail login and no IMAP/SMTP credential. |
| `both` | Mail is stored and a copy is forwarded. On the mail server: vmailbox plus alias `address -> address, forwardTo...`. | Webmail and IMAP/SMTP, same as hosted. |

`forwardTo` is an array of email addresses. A single string is still accepted from older clients and is read back as a one-element array. Addresses are trimmed, lowercased, and de-duplicated. `hosted` rejects a non-empty list. `forward` and `both` require at least one address and reject more than **5**. A target equal to the mailbox itself is rejected. A target that is another mailbox on the same account is rejected when following its forwards leads back, including a direct two-hop loop. A target on the same domain that is not a mailbox is rejected. Forwarding into `mailservicenow.com` is rejected.

Existing mailbox documents are not migrated. `mode: "hosted"` still reads as hosted, including a protected address. A stored `forwardTo` string still reads as that one address. Switching to `forward` does not delete stored Maildir. Switching back to `hosted` or `both` restores the desired hosted capability; current application and service health still need separate confirmation.

The mail server syncs mailbox modes from `mtaMailboxExport` about every 60 seconds. A create or mode change stores the plan immediately and sets `mtaApplied` to false. The legacy `mtaApplied` flag and `mtaAppliedAt` timestamp are sync receipt metadata, not proof that the current configuration is applied or that mail can be delivered. Use `get_mailbox_diagnostics` with the address: current configuration requires an exact revision-bound acknowledgement with a valid timestamp, and service readiness additionally requires fresh successful sync/service health. Inbound delivery remains `not_tested`. New mailbox documents store `delivery` next to `mode` and `forwardTo`. Older documents do not have `delivery`; compute it from `mode` and `forwardTo` (a string `forwardTo` is one address). `delivery` on each API mailbox is what that sync reads:

```json
{
  "mode": "both",
  "forwardTo": ["ada@example.net"],
  "delivery": {
    "vmailbox": true,
    "virtualAlias": "sales@acme.example, ada@example.net"
  }
}
```

`hosted` is `{ "vmailbox": true, "virtualAlias": null }`. `forward` is `{ "vmailbox": false, "virtualAlias": "ada@example.net" }`.

A removed domain is **409** `domain_removed`: That domain was removed. Add it again if you still own it. `verifyDomain`, `getDnsInstructions`, `addMailbox`, `setMailboxMode`, `deleteMailbox`, and `setSpamFilter` leave that row unchanged. `listDomains` omits it. Adding the same name again uses `addDomain`.

An account that is not yet approved is **403** `Account setup is not complete yet`. New unproved domain claims also block mailbox creation until their ownership TXT is verified. The shared agent key (uid `agent:default`) on `addMailbox`, `setMailboxMode`, `deleteMailbox`, `mailboxClientCredential`, `add_mailbox`, `set_mailbox_mode`, `delete_mailbox`, or `issue_mailbox_credential` is **401** `Firebase sign-in required` (on MCP, JSON-RPC `-32000` with `data.status` 401 and that same message). A standard key from `status: "ready"` is accepted on those REST routes and on the mailbox MCP tools. A Firebase ID token may call only the mailbox MCP tools. Own-account domain tools and get_account_status require the standard customer key; legacy shared mail tools may use the shared key. See [After you have a standard key](#after-you-have-a-standard-key-set-up-your-domain-and-mailboxes).

An admin sign-in can create a hosted mailbox on `mailservicenow.com` (for example `team@mailservicenow.com`). Customers cannot add that domain. `inbox@mailservicenow.com` stays the shared inbox. `noreply@mailservicenow.com` is the shared agent key's From address, not a customer mailbox. Product-domain mailboxes are hosted only. `issue_mailbox_credential` (and `POST /mailboxClientCredential`) returns an IMAP/SMTP app password once and stores a SHA512-CRYPT hash. The mail server export includes those named mailboxes, not the product domain as coverage, so Dovecot and vmailbox update on the next sync (about 60 seconds) without rewriting the catch-all.

### Delete a mailbox

`POST /deleteMailbox` accepts `{ "address": "sales@acme.example" }` or `{ "domain": "acme.example", "localPart": "sales" }`. `domainId` and `mailboxId` are accepted as well. The signed-in account must own the mailbox. Someone else's mailbox is **404**. A missing mailbox is **404**, including a second delete of the same address. Unauthenticated is **401**.

An unverified domain may delete its last mailbox. On a verified domain, the last active mailbox is **409** `This is the last mailbox on <domain>. Add another mailbox first, or contact support to remove the domain.` The record stays. Only active mailboxes count: a missing status counts as active, and any other status does not. Deleting an inactive mailbox is allowed while another active mailbox remains.

A protected address is hard-coded and cannot be deleted. That call is **409**. The record stays.

The call deletes the Firestore mailbox record only. It does not delete mail stored on the server (Maildir under `/var/vmail` is left in place). The next mailbox export omits the address and lists `domains`, the verified domains that export covers, including a domain with no mailboxes left. The mail server syncs from `mtaMailboxExport` about every 60 seconds and uses that list to drop the address from the vmailbox map, the virtual alias map, sender login, and the Dovecot passwd file. Routing for a deleted mailbox drops on that next sync. The Maildir is kept. A protected address is never removed from those maps. A partial mailbox file that has no `domains` list of hostnames only updates the addresses it names. Removals are not acked, because the mailbox record is already gone.

The response records what was removed. `mtaApplied: false` matches the shape `setMailboxMode` writes:

```json
{
  "ok": true,
  "deleted": true,
  "mailbox": {
    "address": "sales@acme.example",
    "removed": true,
    "previousMode": "both",
    "delivery": { "vmailbox": false, "virtualAlias": null },
    "mtaApplied": false,
    "maildir": "leave"
  }
}
```

`delivery` describes the address leaving the vmailbox map and the virtual alias map. `maildir: "leave"` means do not remove stored mail. `previousMode` is what the mailbox was. It is not a new mode to apply. The sync drops the map rows from the export's `domains` list, not by replaying this response.

```bash
curl -sS -X POST "$MSN_API_BASE/addMailbox" \
  -H "Authorization: Bearer <firebase-id-token>" \
  -H "Content-Type: application/json" \
  -d '{"domainId":"acme.example","localPart":"sales","mode":"both","forwardTo":["ada@example.net"]}'
```

## How an agent requests access

No API key is required for this flow. Call it over MCP or REST. The code is emailed. It is never in the HTTP response. The first response does not say whether an account is already on file.

1. Call `request_access` (or `POST /requestAccess`) with `contactEmail`, `domain`, `agentName`, and `intendedUse`.
2. Read the email sent to `contactEmail`. The code is 8 digits and expires in 24 hours.
3. Call `verify_access_request` (or `POST /verifyAccessRequest`) with `requestId` and `code`.
4. Read the result:
   - `status: "ready"` includes `access: "standard"` and `apiKey` (`msn_…`). That is a normal customer key: send API, domain and mailbox routes, webhooks, and the customer MCP tools, with the default quotas (100 credits, 5 sends per minute, 50 per UTC day). Email signup does not add the domain or create mailboxes. Naming an address in `intendedUse` does not provision it. Continue with [After you have a standard key](#after-you-have-a-standard-key-set-up-your-domain-and-mailboxes).
   - `status: "setting_up"` has no `apiKey`. The message is `We're setting up your account. We'll email you when it's ready.`
   - An account already on file is left unchanged. If its account status is approved, the response is an additional standard key once, even if mail DNS or mailboxes still need setup. If setup is still in progress, the response is `setting_up`. Otherwise `status: "unavailable"` and the message is `This request could not be completed.` There is no key.
5. Store the key from the ready response. It is shown once. Keep it in a secret store. Send it the same way as any other `msn_…` key: `Authorization: Bearer msn_…` or `X-Api-Key: msn_…`. If `X-Api-Key` is present, that header is the only credential checked. Do not commit the key, and do not put it in a prompt.

A standard key is not an admin key. Admin routes and the admin MCP tools (`list_domain_allowlist`, `add_domain_allowlist`, `remove_domain_allowlist`, `check_domain_allowlist`, `operator_remove_domain`, `operator_delete_request`) return **403** `This action is limited to operator accounts.` The shared `inbox@mailservicenow.com` mailbox stays with Mail Service Now. `operator_remove_domain` marks a customer's domain removed, including its last mailbox, and releases that domain's claim when the claim still names the same account. When the domain has any mailbox, pass `confirm` set to the domain name. `mailservicenow.com` is **409** `system_domain`. `delete_mailbox` has no force flag and does not release the claim.

`request_access` is limited to **5 requests per hour per IP** and **3 requests per hour per email**. A **429** body is `{ "ok": false, "error": "Rate limit exceeded", "retryAfter": <seconds> }` and the `Retry-After` header is set. The code allows **5 attempts**. A wrong code is **401**. After 5 failures the code is **401** `That code is no longer valid`. An expired code is **410**. An unknown `requestId` is **404**. Completing the same request twice is **409** and does not return the key again.

### curl

```bash
export MSN_API_BASE=https://us-central1-mailservicenow.cloudfunctions.net

curl -sS -X POST "$MSN_API_BASE/requestAccess" \
  -H "Content-Type: application/json" \
  -d '{
    "contactEmail": "ops@example-domain.com",
    "domain": "example-domain.com",
    "agentName": "ExampleAgent",
    "intendedUse": "Send a notification from an agent"
  }'
```

```json
{ "ok": true, "requestId": "ar_0123456789abcdef01234567", "expiresIn": 86400, "message": "If the verification code email doesn't arrive within a few minutes, check the spam folder or contact support." }
```

```bash
curl -sS -X POST "$MSN_API_BASE/verifyAccessRequest" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"ar_0123456789abcdef01234567","code":"12345678"}'
```

Ready:

```json
{
  "ok": true,
  "status": "ready",
  "requestId": "ar_0123456789abcdef01234567",
  "access": "standard",
  "apiKey": "msn_<your-key>",
  "tokenType": "Bearer",
  "message": "Save this key now. It is shown once.",
  "quotas": { "credits": 100, "burstPerMinute": 5, "perUtcDay": 50 }
}
```

Setting up:

```json
{
  "ok": true,
  "status": "setting_up",
  "requestId": "ar_0123456789abcdef01234567",
  "message": "We're setting up your account. We'll email you when it's ready."
}
```

Send later with the saved key:

```bash
curl -sS -X POST "$MSN_API_BASE/sendMail" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"to":"recipient@example.com","from":"support@example-domain.com","subject":"Hello","text":"Sent with the standard key."}'
```

### MCP JSON-RPC

`request_access` and `verify_access_request` do not send an `Authorization` header.

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "request_access",
      "arguments": {
        "contactEmail": "ops@example-domain.com",
        "domain": "example-domain.com",
        "agentName": "ExampleAgent",
        "intendedUse": "Send a notification from an agent"
      }
    }
  }'
```

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "verify_access_request",
      "arguments": {
        "requestId": "ar_0123456789abcdef01234567",
        "code": "12345678"
      }
    }
  }'
```

Read `result.structuredContent` on success (`ready`, `setting_up`, or `unavailable`). On failure check both `result.isError` / `result.structuredContent.status` and `error.data.status`. Verification validation/auth errors (400/401/403) use JSON-RPC `error`, not `result.isError`; 404/409/410/429/503 use the tool-error result. A 429 includes `retryAfter`. See [MCP errors](#mcp-errors).

| Status | When |
| --- | --- |
| 400 | `contactEmail`, `domain`, `agentName`, `intendedUse`, `requestId`, or `code` is missing or invalid. `Invalid JSON`. |
| 401 | The code is wrong, or it is no longer valid. Also a bad key on a later send. |
| 403 | A standard key called an admin route or an admin MCP tool. |
| 404 | `requestId` is unknown. |
| 409 | `already_complete`. That request was already finished. Do not retry it. Once the account is ready, get the key with a fresh request_access plus verify_access_request. The key is shown once. "Do NOT resend the same requestId" applies only while the result is pending. The key is not returned again. |
| 410 | The code expired (24 hours). |
| 429 | Rate limit on `request_access`. Body includes `retryAfter` seconds. |

## Agent onboarding sequence

This is the supported state machine. MCP covers MailServiceNow domain listing, DNS instructions, and DNS verification; publish the actual DNS records through your separately authorized DNS provider. There is no public `approve_request` or `request_approval` MCP tool. A verified `request_access` submission is the approval request itself. `POST /registerAccount` is the separate Firebase-signed-in app registration route; anonymous agents use `request_access` and do not need to create a Firebase login for customer-key onboarding.

1. Discover the server with unauthenticated `GET /mcp`, then `initialize` and `tools/list`. Bootstrap is stateless JSON-RPC 2.0; no session ID, OAuth signup, or SSE is required.
2. Choose **one** proof route. Email: call `request_access` with `contactEmail`, `domain`, `agentName`, `intendedUse`; retrieve the actual emailed 8-digit code from an authorized inbox. DNS: omit `contactEmail`, supply `username` plus the other fields; publish `dns.value` as TXT at exactly `dns.name` (`_msn-verify.<domain>`). A username that resembles an email is not an email proof. Keep `requestId`, identity, and challenge expiry securely.
3. Call `verify_access_request` with `requestId` plus `code` (email), or `method: "dns"` (DNS). The proof expires after 24 hours and is single-use. Do not guess codes or hammer DNS verification while propagation is incomplete: five mismatches lock the challenge. CNAME and wildcard proof records are refused.
4. If verification returns `ready` **with `apiKey`**, securely save that key and continue. If it returns `setting_up`, identity is verified but the service decision is pending: poll `get_request_status` with the original `requestId` and `email` (email route) or `username` (DNS route), about every 20 minutes. Do NOT resend the same requestId to verification after it has completed. Polling neither approves the request nor returns a key.
5. When a pending request becomes `ready`, and only if you do not already have a usable saved key, perform a fresh `request_access` and `verify_access_request` with the same identity and domain. The consumed proof cannot reveal the old key. DNS-bound recovery rotates and revokes previous customer keys; email recovery adds another key. Do not repeatedly recover a key on every ready poll.
6. Add and verify each domain: first call MCP `list_domains` (or `GET /listDomains`); DNS signup/approval may already have claimed its hostname. Use MCP `add_domain` or `POST /addDomain` only as needed. Read DNS records from the domain response or MCP `get_dns_instructions` (`GET /getDnsInstructions?domainId=…`), publish them through the owner's authorized DNS provider, then MCP `verify_domain` (`POST /verifyDomain`). These MCP tools use the active approved account's own standard key and never select another account by UID. The signup TXT proves signup identity; the per-claim `_msn-domain` ownership TXT below binds mail-domain setup to the approved account. Neither replaces MX/SPF/DKIM. DMARC is recommended, not required by the current verifier.
7. Create each intended hosted address with MCP `add_mailbox` or `POST /addMailbox`, using the standard customer key. The shared agent key is refused. Check `get_account_status` for account approval and send eligibility, then call `get_mailbox_diagnostics` with `address` for that existing mailbox. No onboarding ID is needed. Current configuration requires an exact revision-bound acknowledgement with a valid timestamp; service readiness additionally requires fresh successful sync/service health. Legacy `mtaApplied` / `mtaAppliedAt` receipt metadata is insufficient. `canSend` reflects account/domain/mailbox eligibility; it does **not** wait for MTA sync or promise deliverability, available credits, or enabled sending. Inbound delivery remains `not_tested`. Do not rotate keys, recreate the mailbox, or toggle delivery modes to repair a pending diagnostic.
8. Only after the owner authorizes the operation, optionally configure REST `/webhooks`, issue an IMAP/SMTP app password if those protocols are needed, and send a proof message. HTTPS/MCP mail does not need an IMAP password. Always set `from` to the provisioned address. Do not resend an uncertain send automatically: no send idempotency key is implemented.

### MCP onboarding calls after approval

Send each request separately to `$MSN_API_BASE/mcp` with `Content-Type: application/json` and `Authorization: Bearer msn_<your-key>`. Examples are placeholders; list before writing and do not assume the example mailbox/domain exists.

```json
{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"list_domains","arguments":{}}}
```

If absent, add the hostname:

```json
{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"add_domain","arguments":{"domain":"example-domain.com"}}}
```

Fetch instructions for the owned domain (the result contains `instructions.records`):

```json
{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"get_dns_instructions","arguments":{"domainId":"example-domain.com"}}}
```

After publishing those records through the external DNS provider:

```json
{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"verify_domain","arguments":{"domainId":"example-domain.com"}}}
```

Read `result.structuredContent.verified` and `checks`; `ok: true` alone is not DNS success. After `verified: true`, create the intended mailbox if it is not already listed:

```json
{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"add_mailbox","arguments":{"domainId":"example-domain.com","localPart":"support","mode":"hosted"}}}
```

```json
{"jsonrpc":"2.0","id":15,"method":"tools/call","params":{"name":"get_account_status","arguments":{}}}
```

A representative account response is `{"ok":true,"status":"ready","accessLevel":"standard","ready":true,"domains":[],"mailboxes":[],"canSend":false,"reason":"Add a fully hosted mailbox on a verified domain before sending."}`. Domain and mailbox arrays fill as setup completes. Use `list_domains` again for MTA confirmation; neither approval nor `canSend` alone confirms live inbound delivery. If any tool returns an error, follow [the error contract](#mcp-errors) rather than advancing to the next step.

### Approval and status states

Auto-approval is a server-owned policy decision, not a choice an applicant can pass in a request. Nonmatching or conflicting requests need a service owner/admin with `requests.approve`; support-only and customer keys cannot approve. The operator uses the admin UI or authorized REST decision route, not an applicant MCP tool. Unverified `code_sent` / `dns_pending` rows are not ready for an operator decision. The separate `/submitApplication` email form flow intentionally returns `pending_review` after verification and does not mint a key; its public status polling still uses the states below.

| Observable result | Meaning and next action |
| --- | --- |
| Request creation returns `requestId` and `expiresIn: 86400` | Challenge created, not approval. Email response never contains the code; DNS response contains the public TXT proof value. |
| Verify `setting_up`; poll `setting_up`, `ready: false` | Proof completed; wait for service review/setup. Poll the original request; do not create repeated applications. |
| Poll `pending`, `ready: false` | Unverified or unresolved request, **or** unknown/mismatched identity/requestId. A generic negative response omits `requestId`; it is not proof of a real pending review. Check your saved identity and challenge. |
| Verify `ready` with `apiKey` | Account approved and a key issued once. Mail domain/mailbox setup may remain. |
| Poll `ready`, `ready: true` | The matching account is approved. No key and no delivery guarantee. Recover only if a usable key is missing. |
| `unavailable` | Locked proof, rejected account, or another unavailable outcome; details are intentionally neutral. Stop automatic onboarding and resolve with the owner/support. Do not create identities to bypass rejection. |
| Verify **410** | Proof expired. The status endpoint does not expose an `expired` state and may still say `pending`. Start a fresh challenge if still authorized. |
| Verify **409** | Completed or rejected request, or a conflict. Completed proofs cannot be replayed; rejection needs operator resolution. Inspect the error rather than treating every 409 as success. |

There is no approval webhook/subscription and no approval ETA in this API. Email-based accounts may receive a ready notification; username/DNS accounts receive no email. Polling is the automated continuation mechanism.

### Prove ownership of each new domain claim

Approval permits account operations; it does not prove control of arbitrary domains. Every new claim has a fresh unpredictable challenge bound to the account and normalized hostname. Previously published, shared MX/SPF/DKIM records alone cannot prove ownership for a new claimant.

`add_domain`, `list_domains` and `get_dns_instructions` expose the owned claim's DNS instructions. For example, inside `domain.dnsInstructions` (or `instructions` for `get_dns_instructions`):

```json
{
  "ownership": {
    "required": true,
    "expiresAt": "2026-10-03T12:00:00.000Z",
    "verifiedAt": null
  },
  "records": [{
    "id": "ownership",
    "type": "TXT",
    "host": "_msn-domain",
    "name": "_msn-domain.example-domain.com",
    "value": "msn-domain-verification=<64-hex-challenge-from-response>",
    "required": true
  }]
}
```

This is an illustrative subset: publish the actual response value and the returned mail DNS records, not the placeholder or date. The challenge is intended for DNS publication, not an API credential. CNAME and wildcard ownership answers are refused. Only the account that holds the claim can retrieve it through authenticated domain tools. `get_dns_instructions` does not return anyone's API key or mailbox password.

- Publish TXT directly at the exact returned name; CNAME and wildcard ownership answers are refused. Then call `verify_domain` with `domainId`. Initial ownership proof expires in 24 hours. Do not substitute the signup `_msn-verify` record or another tenant's old challenge.
- `add_domain` repeated before expiry keeps the current challenge. On **409 `domain_ownership_expired`**, call `add_domain` again with the same hostname, read its renewed challenge, replace the TXT value, and verify again. A stale token cannot satisfy a renewed challenge.
- Successful ownership stays attached to that claim, even if mail DNS later needs repair. Domain removal/re-addition creates a fresh claim and proof; another account cannot replay the old token. A concurrent removal, transfer or renewal returns **409 `domain_claim_changed`**: reload the current state instead of replaying stale data.
- A new unproven claim cannot create mailboxes: **403 `domain_ownership_required`**. Existing send eligibility still requires verified mail DNS and an active hosted/both mailbox. `add_domain` alone does not authorize sending.
- Domains already verified before this ownership gate retain their existing verification when the current claim still belongs to that account, preserving live mail service. Legacy unverified rows receive a challenge lazily when accessed. No bulk migration or retroactive ownership audit is implied; operators should audit legacy verified claims separately.
- A claim reserved by another account is **409 `domain_claimed`** even if it has not finished proof. Stop and contact support for ownership review; there is no automatic claim transfer, and repeatedly applying does not reclaim it. This protects against takeover but leaves abandoned-reservation recovery with the service operator.

### Retries and safe resumability

- Request creation is not idempotent and accepts no idempotency key. A retry can create another request and, for email, another message. Persist a successful `requestId` before proceeding; after an uncertain response reconcile it if available instead of blindly replaying.
- `request_access`: 5/hour per IP and 3/hour per email or normalized username. `get_request_status`: separate 10/hour per IP and 6/hour per identity. Shared-IP agents share the IP budget. Honor `retryAfter` seconds (REST also sets `Retry-After`) and add jitter.
- Verify: wrong proof is 401; fifth mismatch locks it; expired proof is 410; unknown request is 404; completed verification is 409 (usually `code: "already_complete"`). DNS lookup failure is 503 and does not consume a mismatch attempt. Inspect local proof/expiry and wait for propagation before retrying. On an uncertain successful verification, poll before deciding whether key recovery is necessary.
- `add_domain` with the same normalized hostname is resumable (`created: false`); an expired ownership challenge is renewed, so reread the instructions; `add_mailbox` duplicate is 409, so inspect `listDomains` before creating again. `verifyDomain` can be repeated after DNS propagation; `transient: true` means retry later without inferring failure.
- DNS-provider writes, MX cutover, key rotation and optional mailbox-password issuance need the owner's applicable authorization. MailServiceNow does not edit the DNS provider for you. New/unverified own domains may be omitted by get_account_status until ownership is proven; use list_domains and get_dns_instructions for setup diagnostics. Changing MX moves incoming mail away from the previous provider.

An account may add additional domains. Exact existing-domain retries preserve their active ownership proof. `POST /addDomain` and MCP `add_domain` accept the account key. The same normalized name (lowercase, trimmed, trailing dot removed) that is already on the account returns `created: false`; it does not change mailboxes or provider DNS, but renews an expired ownership challenge. A subdomain or parent of a domain already on the account, such as `mail.example.com` when `example.com` is already held, is **409** `domain_variant`. That hostname is a subdomain or parent of a domain already on this account. Use the existing domain and add mailboxes on it, or contact support@mailservicenow.com to remove it.

409 already complete: that request was already finished. Do not retry it. Once the account is ready, get the key with a fresh request_access plus verify_access_request. The key is shown once. "Do NOT resend the same requestId" applies only while the result is pending.

409 domain_variant: That hostname is a subdomain or parent of a domain already on this account. Use the existing domain and add mailboxes on it, or contact support@mailservicenow.com to remove it.

409 domain_claimed: That domain belongs to another account. If you own it, contact support@mailservicenow.com to have it moved to your account.

## Check if my account is ready

Keep the `requestId` from `request_access`. If verify returned `setting_up`, no key exists yet. For email requests, Mail Service Now can email that address when the account is ready; no email is sent for username/DNS requests. Once the account is ready, get the key with a fresh request_access plus verify_access_request. The key is shown once. "Do NOT resend the same requestId" applies only while the result is pending. You can also poll. Poll about every 20 minutes. get_request_status allows 10 per hour per IP and 6 per hour per email, counted separately from request_access, so that poll has room for an extra check.

`get_request_status`, or `POST /getRequestStatus`, takes `requestId` and `email` (the same `contactEmail`) or `username` for the no-email route. No API key. Unknown email, a real email with the wrong `requestId`, and an unknown `requestId` all return the same HTTP 200 body:

```json
{ "ok": true, "status": "pending", "ready": false }
```

A matching pair adds `requestId`. `status` is `ready`, `setting_up`, `pending`, or `unavailable`. `ready` is true only when the account is ready:

```json
{ "ok": true, "status": "ready", "ready": true, "requestId": "ar_0123456789abcdef01234567" }
```

A limited response is the same whether or not the email is on file:

```json
{ "ok": false, "error": "Rate limit exceeded", "retryAfter": 3600 }
```

After `verify_access_request`, call `get_account_status` or `POST /getAccountStatus` with that account's own key. It returns `status`, `accessLevel`, each domain's `verification` (`mx`, `spf`, `dkim`, `dmarc` as `verified`, `missing`, or `unchecked`), compatibility `ready` / `canSend` fields, and separate per-mailbox readiness evidence. Account `ready` means service approval; mailbox `ready` and `canSend` describe send eligibility, not configuration application, service health or delivery proof. When `canSend` is false, `reason` is a short next step. The shared agent key, the mail-server sync token, and another account's key are refused. The call returns only the account that owns the key. For one existing mailbox, use the read-only `get_mailbox_diagnostics` tool with `address`; no onboarding ID is required. See [Mailbox readiness diagnostics](#mailbox-readiness-diagnostics).

A hosted address needs a domain you own. Publish MX, SPF, DKIM, and DMARC, then create the mailbox. DNS: [Domain setup / deliverability](/developers/domain-setup/). This illustrative response subset shows why send eligibility is independent of pending configuration:

```json
{
  "ok": true,
  "status": "ready",
  "accessLevel": "standard",
  "ready": true,
  "readinessMeaning": "account_approval",
  "domains": [{
    "name": "example-domain.com",
    "status": "verified",
    "verification": { "mx": "verified", "spf": "verified", "dkim": "verified", "dmarc": "unchecked" }
  }],
  "mailboxes": [{
    "address": "support@example-domain.com",
    "mode": "hosted",
    "ready": true,
    "readinessMeaning": "send_eligibility",
    "sendEligibility": { "eligible": true, "reasonCode": "eligible" },
    "configurationProvisioning": { "status": "pending", "applied": false, "inboundDelivery": "not_tested" },
    "serviceHealth": { "status": "awaiting_apply", "ready": false },
    "inboundDelivery": "not_tested"
  }],
  "canSend": true
}
```

When no hosted mailbox is eligible, `canSend` is false and `reason` is `Add a fully hosted mailbox on a verified domain before sending.` While setup is still in progress, `reason` is `Account setup is not complete yet`.

## Mailbox readiness diagnostics

Call MCP `get_mailbox_diagnostics` with `{ "address": "support@example-domain.com" }` using that account's own standard customer key. This is a read-only check of one existing mailbox. No onboarding ID is required. It accepts no UID/account selector and does not expand OAuth permissions; OAuth onboarding clients keep using `get_onboarding_status`. Shared service keys, MTA tokens and other accounts cannot use it to inspect a mailbox. Unknown and other-owner addresses return the same not-found response. There is no new standalone REST endpoint for this tool.

```json
{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"get_mailbox_diagnostics","arguments":{"address":"support@example-domain.com"}}}
```

The tool's `structuredContent` is `{ "ok": true, "diagnostic": { ... } }`. The diagnostic separates:

- `address`, `mode`, `inboxAccess`: the existing mailbox and whether its mode/domain permit inbox access. An available inbox is not proof a new message reached it; forward-only inbox access is `not_applicable`.
- `sendEligibility`: `eligible` and `reasonCode`. Compatibility `get_account_status.canSend` and mailbox `ready` remain eligibility fields. Its account `readinessMeaning` is `account_approval`, while mailbox `readinessMeaning` is `send_eligibility`.
- `configurationProvisioning`: `status`, `applied`, `reasonCode`, `desiredRevision`, `appliedRevision`, `desiredUpdatedAt`, `lastAcknowledgedAt`, `appliedAt` and `inboundDelivery`. Application requires an exact revision-bound acknowledgement for the current owner, domain claim, mailbox generation and configuration, with a valid timestamp at or after the desired update and not in the future. `lastAcknowledgedAt` can describe old evidence; only `applied: true` establishes the current match. The public revision IDs are opaque and are not internal configuration digests or storage sample keys. Legacy `mtaApplied` and `mtaAppliedAt` are receipt metadata only.
- `serviceHealth`: `status`, `ready`, `healthCheckedAt`, `lastSyncAt`. Current configuration is necessary but insufficient: the successful sync and healthy mail-service telemetry must also be fresh and follow the applied configuration. Missing, stale, failed or future-dated evidence must not be treated as ready.
- `storageUsage`: `status`, `allocatedBytes`, `observedAt`, `receivedAt`, `metric`, `reasonCode`. This is Maildir filesystem allocation, not a quota, message count or delivery test. Missing or unusable telemetry is `unavailable` with null bytes; do not display it as zero. A real zero-byte observation may be valid. Old valid measurements are `stale`; forward-only storage is `not_applicable`.
- `inboundDelivery`: always `not_tested` in this release. `deliveryVerification.smtpAcceptance` is `not_tested`; `hostedStorage` is `not_tested` for hosted/both or `not_applicable` for forward-only; `forwarding` is `not_tested` for forward/both or `not_applicable` for hosted. Even a storage measurement or an existing inbox message does not verify a new external delivery. Forwarding remains unverified until separately tested.
- `nextAction`: a safe `code`, `responsible` party and `message`; `error` is either a safe code/message or null. Raw stored errors, credentials, DNS proof values, message content and internal storage keys are not returned.

Follow the reported next action and reread diagnostics after normal sync or operator resolution. Do not rotate keys, recreate the mailbox, or toggle modes to repair pending readiness. These reads do not mutate DNS, configuration, credentials or telemetry, run a resync, or send any mail. An external delivery probe and a resync mutation are deferred, not implemented. A real external test requires separate authorization and evidence.

The exact-ack sync consumer and storage collector on the mail host require a separately authorized rollout. Source availability or an API deployment is not evidence that either host component is installed. Until exact acknowledgement arrives, configuration remains pending; absent storage telemetry stays unavailable. Do not claim mail is live from a roughly 60-second sync interval or a successful deployment alone.

## After you have a standard key: set up your domain and mailboxes

`status: "ready"` and a standard `msn_…` key mean this account can call send and the domain routes. They do not publish mail DNS or create mailboxes. Email signup stores `domain` as a note; DNS signup/approval may already claim and add its proved domain. First inspect `GET /listDomains`. `intendedUse` is a note. Writing `support@example-domain.com` or `orders@example-domain.com` in `intendedUse` does not create those mailboxes.

Do these steps in order. Examples use `example-domain.com`. The key in `Authorization` is the `apiKey` from the ready response (`msn_<your-key>`), the same value you store as `MSN_AGENT_API_KEY`. The same paths exist under `https://mailservicenow.com/api/`.

1. Confirm `status: "ready"` and `apiKey`. `setting_up` has no key. The message is `We're setting up your account. We'll email you when it's ready.` Mail Service Now is still finishing that account. Domain and mailbox calls then return **403** `Account setup is not complete yet`. The web app shows the same setup message. Once the response is `ready` and you have the key, the remaining work is this list. A send with that key, before a hosted mailbox exists on a verified domain, returns **403** `Add a fully hosted mailbox on a verified domain before sending.`

2. Call `POST /addDomain` with the standard key, or use **Add domain** on `/app.html` (Domains). Body field `domain` is the customer hostname.

```bash
curl -sS -X POST "$MSN_API_BASE/addDomain" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example-domain.com"}'
```

The live function checks DNS as part of this call. If mail DNS is not published yet, the response is still **200** with `created: true`, `verified: false`, and `domain.status` `failed`. That first `failed` is the DNS check, not a refusal to add the hostname. Read `domain.dnsInstructions.records` and `domain.failureReason`. Calling `addDomain` again for the same normalized name returns **200** `created: false` and leaves mailboxes and provider DNS alone; an expired ownership challenge is renewed in the returned instructions. Another hostname on this account is allowed. A subdomain or parent of a domain already on the account is **409** `domain_variant`: That hostname is a subdomain or parent of a domain already on this account. Use the existing domain and add mailboxes on it, or contact support@mailservicenow.com to remove it. A hostname on another account is **409** `domain_claimed`: That domain belongs to another account. If you own it, contact support@mailservicenow.com to have it moved to your account. `mailservicenow.com` is **400**. MCP `add_domain` uses the same rule.

`GET /listDomains` lists what this account already has. `GET /getDnsInstructions?domainId=example-domain.com` returns the same records.

The standard key is `Authorization: Bearer msn_<your-key>` or `X-Api-Key: msn_<your-key>`. A Firebase ID token works on these routes too. The shared agent key (uid `agent:default`) does not. On these REST routes, `X-Api-Key` set to that shared key is **401** `Invalid API key`. A Bearer value that is not a customer key and not a Firebase ID token is **401** `Firebase sign-in required`.

3. Publish the records in `dnsInstructions.records`. Copy `value` from the response. Record-by-record steps, including DMARC, are in the public guide: <https://mailservicenow.com/developers/domain-setup/>. New claims also require the [account-bound ownership record](#prove-ownership-of-each-new-domain-claim). The mail-routing rows are:

| `id` | Type | Host | Value |
| --- | --- | --- | --- |
| `mx` | MX | `@` | `mail.mailservicenow.com`, priority **10** |
| `spf` | TXT | `@` | the SPF `value` on the domain card (one TXT only; see the [domain setup guide](https://mailservicenow.com/developers/domain-setup/#spf)) |
| `dkim` | TXT | `mail._domainkey` | the `value` on the `dkim` record (selector `mail`) |

`dmarc` (`_dmarc`) is recommended. Verification does not require it.

The preferred MX (lowest priority number) has to be `mail.mailservicenow.com`. If Cloudflare Email Routing is a better priority, `checks.mx.detail` is `MX points at route1.mx.cloudflare.net` (or whichever host is preferred). A second SPF TXT fails with `Publish one SPF TXT`. If an SPF TXT already exists, add the dashboard `ip4:` mechanism to that one record and keep existing `include:` mechanisms. Leave existing A records and unrelated TXT records, including `_acme-challenge`, in place. Do not add an A record for the mail server on this domain.

**Cut over when you mean to.** Pointing MX at `mail.mailservicenow.com` takes inbound mail off the previous host. Replacing Cloudflare Email Routing (or any other MX) stops whatever that host delivers today. Change MX only when Mail Service Now should receive the domain's mail.

4. Call `POST /verifyDomain` after DNS propagates, or **Check DNS** on the domain in the web app.

```bash
curl -sS -X POST "$MSN_API_BASE/verifyDomain" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"domainId":"example-domain.com"}'
```

`domain` is accepted in place of `domainId`. `verified: true` sets `domain.status` to `verified`. `verified: false` leaves `failed` and `failureReason` (also on ownership and mail DNS checks). `transient: true` means the lookup did not finish; call again. A `failed` result from step 2 is cleared by this call once the records match.

5. Create each mailbox with `POST /addMailbox`, or **Add mailbox** in the web app. One call per address. `localPart` is the name before `@`. `mode` is `hosted`, `forward`, or `both`. `hosted` stores mail and takes no `forwardTo`. `forward` and `both` require `forwardTo` (an array, at most 5). See [Customer mailbox delivery](#customer-mailbox-delivery).

```bash
curl -sS -X POST "$MSN_API_BASE/addMailbox" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"domainId":"example-domain.com","localPart":"orders","mode":"hosted"}'
```

Auth on this call:

| Call | Standard `msn_…` key from `ready` | Firebase ID token | Shared agent key |
| --- | --- | --- | --- |
| `POST /addDomain`, `GET /listDomains`, `GET /getDnsInstructions`, `POST /verifyDomain`, `POST /addMailbox`, `POST /setMailboxMode`, `POST /deleteMailbox`, `POST /mailboxClientCredential` | Yes. Bearer or `X-Api-Key`. | Yes. | No. |
| MCP `add_mailbox`, `issue_mailbox_credential`, `set_mailbox_mode`, `delete_mailbox` | Yes. Same key, for a mailbox on that account. | Yes, and only these mailbox MCP tools. | No. JSON-RPC `-32000`, message `Firebase sign-in required`, `data.status` 401. |

`Firebase sign-in required` is the message for the shared agent key. A standard key is a customer key and is accepted, including on MCP `add_mailbox`. You do not need a separate Firebase sign-in when you already have that key. The web app signs in with Firebase and calls the same REST routes.

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "add_mailbox",
      "arguments": {
        "domainId": "example-domain.com",
        "localPart": "orders",
        "mode": "hosted"
      }
    }
  }'
```

MCP `add_domain` adds a domain for this account, the same rule as `POST /addDomain`. MCP `list_domains`, `get_dns_instructions`, and `verify_domain` provide the matching read/verify steps using the approved account's standard key. DNS-provider changes remain external.

6. Check `get_mailbox_diagnostics` with the existing `address`. The mail server normally reads `mtaMailboxExport` about every 60 seconds, but elapsed time and legacy `mtaApplied` / `mtaAppliedAt` do not establish readiness. Require an exact current-revision acknowledgement with a valid timestamp, then fresh successful sync/service health. Pending diagnostics are not a reason to rotate keys, recreate the mailbox, or toggle its mode. `get_account_status.canSend` and mailbox `ready` remain eligibility fields. Even configuration/service readiness leaves inbound delivery `not_tested`; an external delivery test needs separate authorization and is not implemented by this diagnostic. `forward` has no inbox or IMAP/SMTP credential; its storage/inbox checks are `not_applicable` and forwarding is unverified until separately tested. For `hosted` or `both`, the optional app password is a separate call: `POST /mailboxClientCredential` or MCP `issue_mailbox_credential` with `address`. It returns the password once and stores a SHA512-CRYPT hash. A standard key can issue it for a mailbox on that account. The shared agent key is refused.

7. Optional. `POST /webhooks` registers `inbound.received`. A proof send is `POST /sendMail` or MCP `send_mail`. Always set `from` to an address on a verified domain you own, for example `support@example-domain.com`. If it's omitted and the account has exactly one sendable hosted mailbox, that mailbox is used as a fallback; with more than one, omitting `from` is an error (**400** `Choose the address to send from.`). Read credits with `GET /credits` or `get_credits`.

### What looks like a hold and is not

An admin list row with `status: "pending"` and `storedStatus: "code_sent"` is an access-request stub. The code was emailed and the request was not verified. An expired code stays `code_sent`; `POST /verifyAccessRequest` then returns **410** `That code has expired` and does not change the stub. `decidable` is false on that row. A decision returns **409** `This request is not ready for a decision.` That row is not why mailboxes are missing, and it is not something to decide. Ignore it when this account already returned `ready` and a key.

`setting_up` is the other case. That response has no `apiKey`. The account is still being finished. Domain and mailbox calls stay **403** `Account setup is not complete yet` until a later verify returns `ready`. After `ready`, finish domain, DNS, verify, and mailboxes as above.

## MCP

Stateless JSON-RPC 2.0 over `POST`. There is no SSE stream and no session id to keep. A JSON array body is a batch. `notifications/initialized` or `initialized` with `id` omitted returns **204** with an empty body. Other methods are request/response calls: always supply an `id`. An all-notification batch returns an empty JSON array. Initialize, tools/list and ping work without a key; tool availability does not imply authorization.

`GET /mcp` needs no auth:

```json
{
  "ok": true,
  "name": "mailservicenow",
  "version": "0.7.0",
  "transport": "json-rpc-2.0",
  "protocolVersion": "2024-11-05",
  "tools": ["request_access", "verify_access_request", "get_request_status", "get_account_status", "get_mailbox_diagnostics", "send_mail", "get_credits", "list_inbox", "get_message", "mark_read", "list_domain_allowlist", "add_domain_allowlist", "remove_domain_allowlist", "check_domain_allowlist", "add_domain", "list_domains", "get_dns_instructions", "verify_domain", "operator_remove_domain", "operator_delete_request", "add_mailbox", "issue_mailbox_credential", "set_mailbox_mode", "delete_mailbox"],
  "auth": "Authorization: Bearer <MSN_AGENT_API_KEY> or a standard-access customer key. request_access, verify_access_request, and get_request_status need no key. get_account_status and get_mailbox_diagnostics need the account key."
}
```

Remote client shape (header value is your key, not this placeholder):

```json
{
  "mcpServers": {
    "mailservicenow": {
      "url": "https://us-central1-mailservicenow.cloudfunctions.net/mcp",
      "headers": {
        "Authorization": "Bearer msn_<your-key>"
      }
    }
  }
}
```

Use that only with a client that POSTs JSON-RPC. Do not assume an SSE MCP transport.

### initialize

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"example","version":"0.0.0"}}}'
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "mailservicenow", "version": "0.7.0" }
  }
}
```

Also implemented: `notifications/initialized`, `initialized`, `ping`, `tools/list`, `tools/call`.

### tools/list

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

The `tools` array entries:

| Tool | Arguments | Effect |
| --- | --- | --- |
| `request_access` | `domain`, `agentName`, `intendedUse`; `contactEmail` or `username` | Email code when contactEmail is set; otherwise DNS TXT challenge. No key required. See [How an agent requests access](#how-an-agent-requests-access). |
| `verify_access_request` | `requestId` plus `code` (email) or `method: "dns"` | Returns a standard `apiKey` once, or `status: "setting_up"`. No key required. |
| `get_request_status` | `requestId`, `email` or `username` | No key. Same pending body for an unknown email, a wrong `requestId`, and an unknown `requestId`. Poll about every 20 minutes. See [Check if my account is ready](#check-if-my-account-is-ready). |
| `get_account_status` | none. The key selects the account. | Account key only. Returns account approval, domain verification, compatibility send eligibility (`ready`, `canSend`) and separate per-mailbox configuration, service-health and inbound-delivery evidence. |
| `get_mailbox_diagnostics` | `address` (required string) | Read-only. The account's own key and existing mailbox only; no onboarding ID or account selector. Returns configuration, service-health, storage/inbox and forwarding evidence. Inbound delivery is `not_tested`; no external probe or resync is performed. |
| `send_mail` | `to` (string), `subject` (string), `text` (string). Always set `from` to an address on a verified domain you own, for example `support@example-domain.com`. If it's omitted and the account has exactly one sendable hosted mailbox, that mailbox is used as a fallback; with more than one, omitting `from` is an error. Optional `inReplyTo`, `references`. No attachments. | Sends. Costs 1 credit. Rate limits apply. The shared agent key uses From `noreply@mailservicenow.com`. Omitting `from` when more than one sendable hosted mailbox exists is **400** `Choose the address to send from.` |
| `get_credits` | none | `{ "ok": true, "remaining": 100 }` |
| `list_inbox` | optional `limit` (1–50, default 25), optional `mailbox` | Same list shape as `GET /inbox`. No credit. |
| `get_message` | `id` and/or `messageId` | One message, marked read. No credit. |
| `mark_read` | `id` and/or `messageId`. Optional `unread` boolean. | Sets that inbound row read (`unread` omitted or `false`) or unread (`true`). No credit. |
| `add_domain` | `domain` | Standard customer key. Add an owned domain; same normalized hostname returns `created: false`. DNS verification is MCP `verify_domain` or REST `POST /verifyDomain`. |
| `list_domains` | none | Approved standard customer key only. Lists this account's active domains, DNS checks/instructions and legacy mailbox `mtaApplied` receipt metadata; use `get_mailbox_diagnostics` for readiness. No UID selector. |
| `get_dns_instructions` | `domainId` | Approved standard customer key only. Returns the owned domain's `instructions.records`; publish externally. |
| `verify_domain` | `domainId` | Approved standard customer key only. Rechecks the owned domain's mail DNS. Inspect `verified`, `transient`, and `checks`. Does not modify your DNS provider. |
| `add_mailbox` | `domainId`, `localPart`, `mode` (`hosted` \| `forward` \| `both`), optional `forwardTo` (array of emails, max 5) | Creates a mailbox. Output includes `mailbox.mode`, `mailbox.forwardTo`, and `mailbox.delivery`. Account setup must be complete. A standard key is accepted. The shared agent key is refused (`Firebase sign-in required`). No credit. Add the domain with `POST /addDomain` or MCP `add_domain` first. An admin sign-in may use domain `mailservicenow.com` with mode `hosted` for a named mailbox such as `a.codex`. |
| `issue_mailbox_credential` | `address` (or `mailbox`) | Issues or resets the IMAP/SMTP app password. Returns `password` once and stores a SHA512-CRYPT hash. A standard key is accepted for a mailbox on that account. A Firebase ID token works for the owner, or an admin for a product-domain mailbox. The shared agent key is refused. Forward-only is refused. No credit. |
| `set_mailbox_mode` | `domainId`, `localPart` or `mailboxId`, `mode`, optional `forwardTo` | Updates delivery mode. Same output shape. Does not delete stored mail. A standard key is accepted. The shared agent key is refused. No credit. |
| `delete_mailbox` | `address`, or `domainId` / `domain` plus `localPart` / `mailboxId` | Removes the mailbox record. Routing drops on the next sync, about every 60 seconds. The Maildir is kept. Output includes `removed`, `delivery` (`vmailbox` false, `virtualAlias` null), `mtaApplied` false, and `maildir` `leave`. A protected address cannot be deleted (**409**). The last active mailbox on a verified domain is **409** `This is the last mailbox on <domain>. Add another mailbox first, or contact support to remove the domain.` Unverified domains are not affected. A standard key is accepted. The shared agent key is refused. No credit. |
| `operator_delete_request` | `id` or `ids` (at most 200). An id is `access:ar_…` or the raw `ar_…` id. | Admin only. Deletes those access requests and no others. The account and its key stay as they are. Each id writes one `request.delete` audit row and clears that email's request rate counter. A standard key, the shared agent key, and the MTA token are refused. |

### tools/call send_mail

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "send_mail",
      "arguments": {
        "to": "recipient@example.com",
        "from": "support@example-domain.com",
        "subject": "Hello from MCP",
        "text": "Sent via MailServiceNow MCP."
      }
    }
  }'
```

Always set `from` to an address on a verified domain you own, for example `support@example-domain.com`. If it's omitted and the account has exactly one sendable hosted mailbox, that mailbox is used as a fallback; with more than one, omitting `from` is an error (**400** `Choose the address to send from.`). The shared agent key sends as `noreply@mailservicenow.com`.

HTTP **200** success (check `structuredContent`, not only the HTTP status):

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"ok\": true,\n  \"messageId\": \"<id@mail.mailservicenow.com>\",\n  \"creditsRemaining\": 99\n}"
      }
    ],
    "structuredContent": {
      "ok": true,
      "messageId": "<id@mail.mailservicenow.com>",
      "creditsRemaining": 99
    }
  }
}
```

`to` is a string. Commas or semicolons split extra recipients, max 5. `text` or optional `html` supplies the body. HTML sanitization, generated fallback, the combined **100KiB UTF-8** input/output body cap, and **6MiB** encoded MIME cap match REST and are checked before credits. MCP still does not accept attachments.

### tools/call get_credits

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_credits","arguments":{}}}'
```

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "{\n  \"ok\": true,\n  \"remaining\": 100\n}" }
    ],
    "structuredContent": { "ok": true, "remaining": 100 }
  }
}
```

### tools/call list_inbox

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"list_inbox","arguments":{"limit":25,"mailbox":"inbox@mailservicenow.com"}}}'
```

`structuredContent` is `{ "ok": true, "messages": [ ... ], "unreadInPage": 0 }` with the same message fields as `GET /inbox` list.

### tools/call get_message

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_message","arguments":{"id":"firestore-doc-id"}}}'
```

`structuredContent` is `{ "ok": true, "message": { ... } }` including `text` (and `html` when stored). The row is marked read.

### tools/call mark_read

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"mark_read","arguments":{"id":"firestore-doc-id"}}}'
```

`structuredContent` matches `POST /inbox`: `{ "ok": true, "thread", "inboxUnread" }` when the row has a thread, or `{ "ok": true, "message" }` when it does not. Pass `"unread": true` to mark that inbound row unread. Omitted `unread` marks it read. This tool does not call the credit counter. Unknown id is HTTP 200 with `result.isError: true` and `structuredContent.status` **404**, same as other MCP not-found results. A bad `unread` value is JSON-RPC `-32000` with `data.status` **400**.

### tools/call add_mailbox and set_mailbox_mode

Standard key or Firebase ID token. Account setup must be complete. The shared agent key is refused with the same message as `POST /addMailbox` (`Firebase sign-in required`). Domain setup is REST: [After you have a standard key](#after-you-have-a-standard-key-set-up-your-domain-and-mailboxes).

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Authorization: Bearer <firebase-id-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "add_mailbox",
      "arguments": {
        "domainId": "acme.example",
        "localPart": "sales",
        "mode": "both",
        "forwardTo": ["ada@example.net"]
      }
    }
  }'
```

`structuredContent` is `{ "ok": true, "mailbox": { "mode", "forwardTo", "delivery", ... } }`. `set_mailbox_mode` uses the same output. `forwardTo` has at most 5 addresses. See Customer mailbox delivery for the cap, the loop rule, and the note that the mail server syncs from `mtaMailboxExport` about every 60 seconds, with legacy `mtaApplied` and `mtaAppliedAt` as receipt metadata only. Use `get_mailbox_diagnostics` for exact current-revision application and fresh service health; neither receipt metadata nor a successful configuration check proves delivery.

### tools/call delete_mailbox

Firebase ID token, same as `add_mailbox`. The agent key is refused.

```bash
curl -sS -X POST "$MSN_API_BASE/mcp" \
  -H "Authorization: Bearer <firebase-id-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "delete_mailbox",
      "arguments": { "address": "sales@acme.example" }
    }
  }'
```

`structuredContent` is `{ "ok": true, "deleted": true, "mailbox": { "removed": true, "delivery": { "vmailbox": false, "virtualAlias": null }, "mtaApplied": false, "maildir": "leave" } }`. This does not delete mail stored on the server. A missing mailbox is HTTP 200 with `result.isError: true` and `structuredContent.status` **404**. A protected address is JSON-RPC `-32000` with `data.status` **409**. The last active mailbox on a verified domain is **409** `This is the last mailbox on <domain>. Add another mailbox first, or contact support to remove the domain.` Unverified domains are not affected.

### MCP errors

Tool failures that are **402, 404, 409, 410, 429, or 503** still use HTTP **200**. The JSON-RPC result has `isError: true` and `structuredContent.status`. Insufficient credits and rate limits are both **429** here (credits are not HTTP 402).

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{\n  \"ok\": false,\n  \"error\": \"Rate limit exceeded\"\n}" }
    ],
    "isError": true,
    "structuredContent": {
      "ok": false,
      "error": "Rate limit exceeded",
      "status": 429
    }
  }
}
```

Other tool failures use a JSON-RPC **error** (HTTP still 200):

| JSON-RPC `error.code` | When |
| --- | --- |
| `-32600` | Body is not a JSON-RPC 2.0 object |
| `-32601` | Method not found |
| `-32602` | `tools/call` missing `params.name` |
| `-32000` | Other failures, including validation (`data.status` **400**) and auth problems that are not HTTP 401 |

Validation example (`to` / `subject` / `text` missing, unknown tool, bad mailbox, bad id): HTTP 200

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32000,
    "message": "to, subject, and text or meaningful html are required",
    "data": { "status": 400 }
  }
}
```

Authentication failure before a protected `POST /mcp` call is HTTP **401** `{ "ok": false, "error": "…" }`, not a JSON-RPC envelope. Wrong method is HTTP **405**.

## HTTP errors (REST)

| Status | `error` string | When |
| --- | --- | --- |
| 400 | `to, subject, and text or meaningful html are required` | sendMail missing fields |
| 400 | `Max 5 recipients per request` | more than 5 recipients |
| 400 | `Body too large (max 100KB combined text and html)` / `Encoded message too large (max 6MB)` | REST/MCP combined body or encoded message limit |
| 400 | `contactEmail must be an email address` / `domain must be a hostname such as example.com` / `agentName is required` / `intendedUse is required` / `requestId is invalid` / `code is invalid` | `requestAccess` or `verifyAccessRequest` |
| 400 | `Invalid JSON` | ingest body is not JSON |
| 400 | `messageId is required` / `mailbox must be an @mailservicenow.com address` / `source must be imap, maildir, or pipe` | ingest validation |
| 400 | `id or messageId is required` / `Invalid id` / `Invalid messageId` | inbox read |
| 400 | `Invalid thread` / `Invalid view` | thread id or `view` |
| 400 | `thread, id, or messageId is required` / `unread or folder is required` / `unread must be true or false` / `folder must be inbox, archive, or trash` / `Only inbound mail can be marked unread` | `POST /inbox` or MCP `mark_read` |
| 400 | `url is required` / `url must be https` / `url must not include credentials` / `url must not include a fragment` / `url is too long` / `url host is not allowed` / `url host could not be resolved` / `enabled must be true or false` / `rotateSecret must be true or false` | `/webhooks` |
| 400 | `disabled must be true or false` / `frozenUntil must be an ISO time or null` / `sendingEnabled must be true or false` / `disabled, frozenUntil, or sendingEnabled is required` / `Invalid JSON` | `POST /credits` |
| 400 | `Query must be at least 2 characters` / `Query too long` | `GET /inbox?q=` |
| 400 | `Draft is empty` / `Draft limit reached (50)` / `To too long` / `Subject too long` / `In-Reply-To too long` / `References too long` / `id is required` | `/drafts` |
| 400 | `Invalid inReplyTo` / `Invalid references` | sendMail / send_mail threading fields |
| 400 | `attachments must be an array` / `Max 3 attachments` / `Attachment type not allowed` / `Attachment filename does not match its type` / `Attachment content is required` / `Attachment content is not valid base64` / `Attachment too large (max 2MB each)` / `Attachments too large (max 4MB total)` / `Attachment content does not match its type` | sendMail attachments |
| 400 | `Attachments are not supported on send_mail` | MCP `send_mail` with attachments |
| 400 | `Choose the address to send from.` | sendMail / send_mail when `from` is omitted and the account has more than one sendable hosted mailbox. With exactly one, omission is a fallback, not the normal path. |
| 400 | `Invalid box` / `Invalid attachment index` | `GET /attachment` |
| 401 | `Missing Authorization Bearer token or X-Api-Key` | no credential |
| 401 | `That code is not valid` / `That code is no longer valid` | wrong or locked access code. No key is returned. |
| 401 | `Invalid API key` | wrong agent key or customer key |
| 401 | `Invalid or expired ID token` | bad Firebase JWT |
| 401 | `Invalid ingest key` | wrong or missing ingest key |
| 401 | `MCP requires agent API key (Bearer msn_…)` | Firebase user called MCP |
| 400 | `Enter a domain you own, such as example.com.` / `That domain name is not valid.` / `domainId is required` / `Enter the mailbox name.` / `Choose hosted, forward, or both.` | `addDomain`, `verifyDomain`, or `addMailbox` |
| 401 | `Firebase sign-in required` | shared agent key on a domain or mailbox route (REST Bearer, or MCP mailbox tools). A standard key is accepted there. |
| 403 | `Account setup is not complete yet` | domain or mailbox call before the account can send (`setting_up`, not `ready`) |
| 403 | `Add a fully hosted mailbox on a verified domain before sending.` | standard key `sendMail` / `send_mail` before that mailbox exists |
| 403 | `This action is limited to operator accounts.` | standard customer key on an admin route or an admin MCP tool |
| 403 | `This mailbox requires an operator account` | caller attempting an operator-only shared mailbox without the required permission |
| 403 | `Drafts require a signed-in user` | agent key on `/drafts` |
| 403 | `Webhooks require an agent API key` | verified Firebase user on `/webhooks` |
| 403 | `Operator control requires the agent key or an operator account` | signed-in user who is not an admin on `POST /credits` |
| 403 | `Pausing all sending requires an operator account` | agent key trying to set `sendingEnabled` |
| 404 | `Request not found` | unknown `requestId` |
| 404 | `Message not found` | inbox / `get_message` |
| 404 | `Draft not found` | `/drafts` id for another user, or missing |
| 404 | `Thread not found` | `GET /inbox?thread=` |
| 404 | `Attachment not found` | `GET /attachment` |
| 409 | `already_complete` | `verifyAccessRequest` on a finished request. Do not retry that requestId. Once the account is ready, get the key with a fresh request_access plus verify_access_request. The key is shown once. "Do NOT resend the same requestId" applies only while the result is pending. The key is not returned again. |
| 409 | `domain_variant` | `addDomain`, `add_domain`. That hostname is a subdomain or parent of a domain already on this account. Use the existing domain and add mailboxes on it, or contact support@mailservicenow.com to remove it. |
| 409 | `domain_claimed` | `addDomain`, `add_domain`. That domain belongs to another account. If you own it, contact support@mailservicenow.com to have it moved to your account. |
| 409 | `domain_removed` | `verifyDomain`, `getDnsInstructions`, `addMailbox`, `setMailboxMode`, `deleteMailbox`, `setSpamFilter`, and the mailbox MCP tools. That domain was removed. Add it again if you still own it. The removed row is not changed. `listDomains` and `get_account_status` omit it. Adding the same name again uses `addDomain`. |
| 409 | `That mailbox already exists on this domain.` / `already complete` | `addMailbox` or `verify_access_request` |
| 410 | `That code has expired` | access code older than 24 hours. No key is returned. |
| 405 | `Method not allowed` | wrong verb (`sendMail`, `requestAccess`, and `verifyAccessRequest` are POST; `inbox` is GET or POST; `attachment` is GET; `drafts` and `webhooks` are GET, POST, or DELETE; `credits` is GET or POST; `mcp` is GET or POST) |
| 429 | `Rate limit exceeded` | burst or daily cap, or access-request cap (5/hour per IP, 3/hour per email). Access-request 429 includes `retryAfter` seconds. |
| 429 | `Insufficient credits` | agent balance is 0. Same status as the rate limit. |
| 500 | `Send failed` / `Inbox request failed` / `Ingest failed` / `MCP error` | unexpected failure (including MTA misconfiguration). The client does not receive the internal message. |
| 503 | `Sending temporarily disabled` | global kill switch (`config/send.enabled === false`) |
| 503 | `Agent key disabled` | agent key `disabled` or `frozenUntil` still in the future. No credit spent. Human sends are not blocked by this flag. |

There is no **402** on the live send path. Do not code clients to wait for 402.

## Anti-abuse expectations

- No credential → **401**. That response does not spend a credit.
- Over the burst or daily cap → **429** `Rate limit exceeded`.
- Agent key frozen → **503** `Agent key disabled`, and the credit counter does not move.
- All sending paused → **503** `Sending temporarily disabled`, and the credit counter does not move.
- Integrators do not connect to port 25 or 587. Submission credentials stay on the function.
- Do not relay arbitrary third-party mail through this API. Sends are audited (actor, recipients, Message-ID, outcome).
- Do not log the agent key. Redact it as `msn_<your-key>`.

## A product that uses this API

This is an integration on the Mail Service Now email API, not a Mail Service Now service. The generic recipe is [Any agent product](https://mailservicenow.com/developers/any-agent/).

1. If you do not have a key, follow [How an agent requests access](#how-an-agent-requests-access). Then set `MSN_API_BASE` and `MSN_AGENT_API_KEY=msn_<your-key>`. A ready key does not publish mail DNS or create mailboxes. DNS signup/approval may already add its proved hostname; inspect list_domains first. Continue with [After you have a standard key](#after-you-have-a-standard-key-set-up-your-domain-and-mailboxes).
2. `GET /mcp` or read this file to confirm tool names.
3. `tools/call` `get_credits` (or ignore credits if you send as a person in the web app; people are not charged and cannot call MCP).
4. `send_mail` / `sendMail`. Require HTTP 200 and `ok: true` / `structuredContent.ok === true`. Save `messageId`.
5. On **429**, read `error`: back off for `Rate limit exceeded`; stop and ask Mail Service Now for credits for `Insufficient credits`.
6. Optionally `list_inbox` then `get_message` for mail delivered to the mailbox. `mark_read` changes the unread flag without a credit. `POST /webhooks` registers an HTTPS URL for `inbound.received` events.

## Admin requests

An admin sign-in can remove access requests from the Requests page. Pending, verified, active, expired, and declined rows can be removed. The account and its key stay as they are. A customer key still works, and the account status still answers.

Delete one row, or select several and delete them. Each deleted id writes its own `request.delete` audit row. The row keeps status, type, id, account id, email, domain, and timestamps. It does not keep codes, code hashes, keys, tokens, or secrets. Deleting a row also clears that email's request rate counter, so a fresh `request_access` is accepted immediately.

Review duplicates before deleting them. Enter an email, a domain, or both. That filter is required. The preview keeps the newest open or active row for each email and domain and lists the rest. Untick any row to keep it. `POST /api/admin/requestDelete` then deletes exactly the ids you send, at most 200. It does not search again, and it does not delete every match on its own. Preview is `GET /api/admin/requestDuplicates` with `email`, `domain`, or both.

MCP `operator_delete_request` is admin only. Pass `id` or `ids`. A standard key, the shared agent key, and the MTA token are refused. The same check guards the REST routes.

## Admin domains

An admin sign-in can delete a domain from the Domains page. Verified, pending DNS, and failed rows each have Delete. The confirm dialog names the domain and how many mailboxes it has. If it has any mailbox, type the domain name before it is deleted. Mail stored for this domain is permanently deleted and cannot be recovered. Select several rows to delete them together. Each domain is its own request and writes its own `domain.remove` audit row.

`mailservicenow.com` cannot be deleted. The API returns **409** with code `system_domain`. A protected domain, and any domain that contains a protected address, stays **409**.

A domain whose account record is gone can still be deleted. The audit row sets `ownerMissing` to true. The claim is deleted in the same write only when it still names that account, so a different account can add the domain afterward. A customer's own mailbox removal does not release the claim. Mail already stored for that one mailbox stays until the whole domain is deleted.

The next mail sync drops that domain from the mail maps. Mail stored for the domain is permanently deleted and cannot be recovered. There is no backup.

MCP `operator_remove_domain` is admin only. Pass `uid` or `ownerEmail`, and `domainId`. Pass `confirm` when the domain has any mailbox. A standard key, the shared agent key, and the MTA token are refused. REST is `POST /api/admin/removeDomain` with the same body. The response says mail is permanently deleted and cannot be recovered.

## Related pages

- Developers: <https://mailservicenow.com/developers/>
- Any agent product recipe: <https://mailservicenow.com/developers/any-agent/>
- Legacy agent page (still served): <https://mailservicenow.com/docs/agents.html>
- OpenAPI: <https://mailservicenow.com/docs/openapi.json>
- Web app: <https://mailservicenow.com/app.html>


## Exact configuration recovery for existing mailboxes

Use `get_mailbox_diagnostics` with the owned address. `desiredConfiguration`
contains saved settings; `effectiveConfiguration` contains current or historical
acknowledgement evidence, or unknown. `syncWorker.runtimeValidation` is separate
from legacy exact acknowledgements and requires matching versioned worker
validation. An acknowledgement never establishes external delivery.

`reconcile_mailbox` accepts `address`, the diagnostic's current
`configurationProvisioning.desiredRevision` as `expectedDesiredRevision`, and a stable 16–128 character
`idempotencyKey`. It is restricted to the current owner's standard customer key.
The operation preserves messages, credentials, mode and forwarding settings.
Stale revisions and conflicting idempotency reuse are rejected. Poll
`get_mailbox_recovery` with the returned `operationId` at its recommended interval.
Queued/applying/failed states do not mean configuration or delivery succeeded.

Targeted recovery is unavailable until a supported safe host consumer is
installed and sends a fresh authenticated capability report. In that state,
`reconcile_mailbox` returns `infrastructure_unavailable` without queuing work.
The global sync worker's presence does not enable this capability. Do not toggle
mailbox modes, recreate mailboxes, rotate credentials or restart onboarding as a
substitute.

Independent external delivery probes and correlated delivery traces are not yet
operational; diagnostics report their missing infrastructure explicitly. Do not
claim that a probe was sent, an inbox received it, or forwarding was verified.
An actual probe needs explicit sending consent, an independent external sender
using public MX, and destination-side evidence for inbox arrival.
