Developers: current docs, quickstart, and the Markdown guide are at /developers/. This page stays available as the legacy agent reference. Download .md · OpenAPI

Email Services & API for Private Clients

Agent API & MCP

Authenticate as an agent with an API key, send mail via HTTPS or MCP JSON-RPC, and read credits. People signed in to the web app are not charged. An agent requests its own key with request_access or POST /api/requestAccess.

Resumable, owner-approved onboarding

Connect to https://mailservicenow.com/api/mcp with OAuth. The owner approves an exact domain, mailbox and permission set. Credentials travel through the connector's OAuth transport, never through MCP tool results.

Use start_onboarding once with an idempotency key, then get_onboarding_status, resume_onboarding and renew_onboarding_proof with the same onboarding ID. Account approval, ownership, DNS changes, mailbox creation and live server readiness are separate checkpoints.

Customer-domain inboxes are supported. Scoped list_inbox, get_message, search_mailbox, send_mail and reply_to_message use the owner's hosted/both mailbox. Forward-only addresses have no inbox. DNS is changed only through an independently authorized provider connection or an owner handoff.

Full resumable onboarding and mailbox guide · Manage or revoke one agent connection

The older key-based instructions below remain for compatibility. Their DNS recovery revokes all prior legacy account keys; OAuth revocation affects only the selected connection.

Agents can sign up themselves

Agents can request access, prove email or DNS control, poll the service decision, obtain a standard customer key, and onboard domains and mailboxes through MCP. They cannot approve themselves. Unmatched requests need a Mail Service Now owner/admin decision. Access to email, DNS-provider changes, credential storage and mail sending still require the account owner's authorization. Pricing remains tailored through Contact/Apply.

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. The key is returned once, on verify 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, and verify with method dns. A new key is returned once. DNS-bound recovery revokes all previous customer keys for the account; email recovery instead adds a key. Coordinate recovery with other clients.

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"}'
{"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"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"verify_access_request","arguments":{"requestId":"ar_0123456789abcdef01234567","method":"dns"}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_request_status","arguments":{"requestId":"ar_0123456789abcdef01234567","username":"agent-one"}}}

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

From address: 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 noreply@mailservicenow.com. You call HTTPS only. Inbound MX is mail.mailservicenow.com. The shared inbox@mailservicenow.com mailbox stays with Mail Service Now. A hosted mailbox on a verified domain opens in the web app.

Authentication

CallerCredentialHow to send
Agent API key msn_<redacted> Authorization: Bearer msn_…
or X-Api-Key: msn_…

On sendMail, if the Bearer token looks like a Firebase JWT it is verified with verifyIdToken; otherwise it is treated as the agent API key. Signed-in customers with a ready account can use their own hosted mailboxes. Domain ownership and mailbox readiness are checked on every mail request. Drafts stay private to the signed-in user. The shared product mailbox requires operator permission. request_access, verify_access_request, and get_request_status need no key. Discovery, initialize, tools/list and ping are also public. Customer tools use the approved account's own standard API key. Tool discovery does not grant permission; shared agent keys do not authorize customer domain setup. Mailbox tools also accept a Firebase ID token once account setup is complete.

Agents request their own key. Call request_access (MCP) or POST /api/requestAccess with contactEmail, domain, agentName, and intendedUse. The contact address is emailed an 8-digit code. Then call verify_access_request (or POST /api/verifyAccessRequest) with requestId and code. A domain on the domain list returns a standard key once. A domain that is not on that list stays setting_up. Mail Service Now only finishes those requests that are still being set up. It does not hand an agent its key. Never commit or paste a full key into a public channel. The same steps are in the Markdown guide (How an agent requests access) and llms.txt.

Credits model

  • A validated agent send uses 1 credit before SMTP submission. SMTP failures are not automatically refunded.
  • The default agent key starts at 100 credits (Firestore agent_credits/default.remaining).
  • People signed in to the web app are not charged.
  • Empty balance: HTTP 429 with error Insufficient credits (not 402).
  • Rate limit on send: 5/minute and 50/UTC-day per caller. Same 429 status, error Rate limit exceeded. The agent key shares one bucket.

Endpoints

NameURL
sendMail https://mailservicenow.com/api/sendMail
MCP (JSON-RPC) https://mailservicenow.com/api/mcp
inbox https://mailservicenow.com/api/inbox
OpenAPI-ish /docs/openapi.json

sendMail (REST)

POST JSON body: to, subject, text, and from. Optional attachments (max 3, 2MB each, 4MB total). 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. The shared agent key sends as noreply@mailservicenow.com. MCP send_mail uses the same from rule and does not accept attachments.

Success: { "ok": true, "messageId": "<…>", "creditsRemaining": N } (creditsRemaining only for agent auth).

Example: agent send (curl)

curl -sS -X POST \
  https://mailservicenow.com/api/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."
  }'

How an agent requests access

No API key is required. The code is emailed and is not in the 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. Wait for the email. The code is 8 digits and expires in 24 hours.
  3. Call verify_access_request or POST /verifyAccessRequest with requestId and code.
  4. status: "ready" includes access: "standard" and apiKey once. That key can call send, the domain and mailbox routes, webhooks, and the customer MCP tools. Email signup does not add the domain or create mailboxes; DNS signup/approval may already have added its proved hostname. Inspect list_domains first. Default quotas are 100 credits, 5 sends per minute, and 50 per UTC day. status: "setting_up" has no key. 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 is approved, the response is a standard key once even if domain/mailbox setup remains. 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 in a secret store. It is shown once. Send it as Authorization: Bearer msn_… or X-Api-Key: msn_…. If X-Api-Key is set, it is the only credential checked. Do not commit it.

A standard key gets 403 on admin routes and on list_domain_allowlist, add_domain_allowlist, remove_domain_allowlist, check_domain_allowlist, and operator_remove_domain. Limits on request_access: 5/hour per IP and 3/hour per email. 429 includes retryAfter seconds. Wrong code is 401. Five failures lock it (401). Expired code is 410. Unknown requestId is 404. Completing the same request again is 409. Invalid input is 400.

curl

curl -sS -X POST \
  https://mailservicenow.com/api/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"
  }'
curl -sS -X POST \
  https://mailservicenow.com/api/verifyAccessRequest \
  -H "Content-Type: application/json" \
  -d '{"requestId":"ar_0123456789abcdef01234567","code":"12345678"}'

MCP JSON-RPC

curl -sS -X POST \
  https://mailservicenow.com/api/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"
      }
    }
  }'

Then call verify_access_request with requestId and code. Read structuredContent.status (ready or setting_up). The longer copy is in the Markdown guide (How an agent requests access) and llms.txt.

A ready key does not publish mail DNS or create mailboxes. intendedUse does not provision addresses. After the key, follow After you have a standard key (developers quickstart, Domain setup / deliverability). setting_up means the account is still being finished.

Agent onboarding sequence

  1. Discover MCP without a key. Call request_access with the email or username/DNS inputs above, then persist requestId.
  2. Verify the emailed code or exact signup TXT with verify_access_request. Proofs expire in 24 hours and five mismatches lock them.
  3. If verification returns setting_up, poll get_request_status about every 20 minutes using the original requestId and email or username. A verified request is the approval request; there is no public self-approval tool.
  4. Save apiKey when verification returns ready. When polling becomes ready and no usable key is saved, do one fresh request/verify cycle. Polling never returns a key and consumed proofs cannot be replayed. DNS recovery rotates old keys.
  5. Call list_domains, use add_domain if needed, and read get_dns_instructions. Publish the returned DNS records through your authorized DNS provider, then call verify_domain. MailServiceNow does not change registrar records.
  6. Create the intended address with add_mailbox. Check account approval/send eligibility with get_account_status, then call read-only get_mailbox_diagnostics with the existing address; no onboarding ID is required. Current configuration needs an exact revision-bound acknowledgement with a valid timestamp; service readiness additionally needs fresh successful sync/service health. Legacy mtaApplied/mtaAppliedAt are receipt metadata only. Inbound delivery remains not_tested. Do not rotate keys, recreate the mailbox, or toggle modes to repair pending diagnostics.
  7. Send only an authorized message, always setting from. HTTPS/MCP sending does not require an IMAP password.

The domain tools require an active approved account's standard key. list_domains takes no arguments; get_dns_instructions and verify_domain take domainId. They do not accept UID/account overrides. Shared, MTA, revoked and unapproved credentials cannot use them; another account's domain cannot be read or verified.

Public polling states are pending, setting_up, ready, and unavailable. Unknown or mismatched request/identity pairs also return pending without requestId. Unavailable is intentionally neutral, including locked/rejected outcomes: stop and resolve with the owner/support. Expiry is a verify 410, not a public polling state. The separate application form's verification can return pending_review. Ready means account approval, not live mail delivery.

Honor retryAfter on 429. Creation is not idempotent, verification is single-use, and mail sends have no idempotency key. Do not blindly replay an uncertain write or send. DNS propagation can take time; verification lookup 503 is retryable. Read the full state machine, retry rules and MCP examples.

An account may add additional domains. 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 and does not change mailboxes or provider DNS; an expired ownership challenge is renewed. 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.

409 domain_removed: That domain was removed. Add it again if you still own it. verifyDomain, getDnsInstructions, addMailbox, setMailboxMode, deleteMailbox, setSpamFilter, and the mailbox MCP tools return this for a removed domain and do not change the row. listDomains omits it. Adding the same name again uses addDomain.

Domain ownership comes before mailbox access

Every new claim gets a unique account-bound TXT at _msn-domain.<domain>, with the exact msn-domain-verification=… value returned in the DNS instructions. The ownership object exposes required, expiresAt and verifiedAt. Shared mail DNS alone is not ownership proof. The signup _msn-verify challenge is separate.

The initial ownership proof expires after 24 hours. On 409 domain_ownership_expired, call add_domain again, publish the renewed TXT and verify. Before expiry the same call preserves its token. Proven ownership persists for that claim; removal/re-add requires fresh proof. Unproven new claims cannot create mailboxes (403 domain_ownership_required). A concurrent claim change returns 409 domain_claim_changed; reload the current state.

Previously verified domains keep working without migration; unverified legacy domains receive a challenge lazily. Legacy verified ownership still needs a separate operator audit. A domain reserved by another account remains 409 domain_claimed, including abandoned unverified claims. Contact support for review instead of trying to transfer it automatically.

Check if my account is ready

Keep the requestId. If verify returned setting_up, no key exists yet. Email requests may receive a ready email; username/DNS requests receive no email. 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. Poll get_request_status or POST /getRequestStatus with requestId and email or username. No API key. 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.

Unknown email, a real email with the wrong requestId, and an unknown requestId all return HTTP 200 { "ok": true, "status": "pending", "ready": false }. A match also includes requestId. status is ready, setting_up, pending, or unavailable. HTTP 429 is { "ok": false, "error": "Rate limit exceeded", "retryAfter": 3600 } whether or not the email is on file.

After verify, call get_account_status or POST /getAccountStatus with that account's own key. The response has status, accessLevel, domain verification (mx, spf, dkim, dmarc), compatibility ready/canSend fields and separate per-mailbox configuration, service-health and inbound-delivery evidence. Account ready means approval; mailbox ready and canSend mean send eligibility, not 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. A hosted address needs a domain you own. DNS: Domain setup / deliverability.

MCP JSON-RPC

Pragmatic JSON-RPC 2.0 over HTTPS (initialize / tools/list / tools/call). Auth: Authorization: Bearer msn_…

Bootstrap calls need no Authorization header. Do not combine public signup calls with protected tools in an unauthenticated batch. Successful results use result.structuredContent. Tool failures 402/404/409/410/429/503 use HTTP 200 with result.isError; validation and tool auth errors 400/401/403 use JSON-RPC error.data.status. Protected-call auth may fail at HTTP 401 before dispatch.

Tools:

  • send_mail — args to, subject, from, and a message body. Optional inReplyTo and references. Supply text or meaningful HTML; an omitted text alternative is generated. HTML is sanitized, with a combined 100 KB UTF-8 body limit and 6 MB encoded MIME limit. Attachments remain REST-only. 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.
  • get_credits — returns remaining credits
  • list_inbox — optional limit, mailbox → stored inbound messages and unreadInPage. No credit cost.
  • get_message — id or messageId → one message, marked read. No credit cost.
  • mark_read — id or messageId, optional unread → set the inbound unread flag. No credit cost. Auth failure is HTTP 401 before the tool runs.
  • add_mailbox — domainId, localPart, mode (hosted, forward, or both), forwardTo (up to 5 addresses) → creates a mailbox. Account setup must be complete. A standard key is accepted. The shared agent key is refused. Forward-only has no IMAP login. The mail server syncs mode changes from mtaMailboxExport about every 60 seconds. Legacy mtaApplied and its timestamp record sync receipt, not current configuration or delivery proof. Use get_mailbox_diagnostics for exact current-revision acknowledgement and fresh service health. An admin sign-in may add a hosted mailbox on mailservicenow.com.
  • issue_mailbox_credential — address → issues or resets the IMAP/SMTP app password. The password is returned once and stored as a SHA512-CRYPT hash. A standard key is accepted for a mailbox on that account. The shared agent key is refused. Forward-only is refused.
  • set_mailbox_mode — same mode and forwardTo arguments → updates delivery. Does not delete stored mail. Output includes mode, forwardTo, and delivery. Read get_mailbox_diagnostics after the change; receipt flags or elapsed time alone do not confirm the current mode is applied.
  • delete_mailbox — address, or domainId and localPart → removes the mailbox record. Routing drops on the next sync, about every 60 seconds. The Maildir is kept. 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. There is no force flag. Unverified domains are not affected. A standard key is accepted. The shared agent key is refused.
  • operator_remove_domain — admin only. uid or ownerEmail, plus domainId. When the domain has any mailbox, also pass confirm set to the domain name. Marks the domain removed and every mailbox on it removed. The claim is released when it still names that account. Mail stored for this domain is permanently deleted and cannot be recovered. mailservicenow.com is 409 system_domain. A protected domain, and any domain that contains a protected address, is 409. A missing account can still be removed; the audit row sets ownerMissing. This is the path for removing a domain's last mailbox. A standard or request_access key is 403, even for an admin email. The shared agent key and the MTA token are refused. delete_mailbox does not release the claim.
  • operator_delete_request — admin only. id or ids (at most 200). Deletes those access requests. The account and its key stay as they are. Each id writes one audit row and clears that email's request rate counter. A standard key, the shared agent key, and the MTA token are 403 or 401.
  • request_access — no API key. domain, agentName, intendedUse, plus contactEmail for emailed proof or username for DNS proof.
  • verify_access_request — no API key. requestId and code, or method: "dns". Returns a standard key once, or setting_up. See Agent onboarding sequence.
  • list_domains — standard customer key only. No arguments. Own active domains, instructions, checks and mailbox MTA-application status.
  • get_dns_instructions — standard customer key only. domainId selects an owned domain. Returns instructions.records for external DNS publication.
  • verify_domain — standard customer key only. domainId selects an owned domain. Rechecks DNS; inspect verified, transient and checks. Does not edit DNS.
  • add_domain — account key. Additional domains are allowed. The same normalized name returns created: false. 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 domain owned by 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.
  • get_request_status — no API key. requestId and email or username. See Check if my account is ready. Poll about every 20 minutes.
  • get_account_status — the account's own key only. Returns approval, accessLevel, domain verification, compatibility send eligibility and separate per-mailbox readiness evidence. Refuses the shared agent key and any other account.
  • get_mailbox_diagnostics — required address string. Read-only; the account's own key and existing mailbox only, without an onboarding ID or account selector. Separates current configuration, service health, storage/inbox and forwarding evidence. Inbound delivery is not_tested. Forward-only storage/inbox are not_applicable; forwarding remains unverified/not_tested. External probes and resync mutations are deferred and are not performed by this tool. Public revision IDs are opaque; storage unavailable/null is not zero. Exact-ack and storage-collector host installation is a separately authorized rollout, not proven by source or API deployment. See the diagnostics field contract.

forward relays only and is not a webmail or IMAP login. hosted stores mail. both stores a copy and forwards. A mailbox cannot forward to itself or into a loop. More than 5 targets is rejected.

Inbound webhooks

POST /webhooks with the agent key registers one HTTPS URL. A new ingest POSTs inbound.received (id, messageId, from, to, subject, preview, timestamp, mailbox) signed with HMAC-SHA256. Header X-MSN-Signature: sha256=<hex> over <unix seconds>.<raw body>. One retry after 750ms. Failures do not fail ingest. No credit. GET /webhooks reads it. DELETE /webhooks clears it.

Inbox (list / read)

Signed-in customers use a Firebase ID token for their own ready hosted mailboxes. Agents use their account’s API key. The shared service inbox requires staff access; another customer’s mailbox is never authorized. Listing does not mark mail read. Fetching one message does. unreadInPage is only the unread count inside the returned page.

curl -sS \
  "https://mailservicenow.com/api/inbox?limit=25" \
  -H "Authorization: Bearer msn_<your-key>"
curl -sS \
  "https://mailservicenow.com/api/inbox?id=<doc-id>" \
  -H "Authorization: Bearer msn_<your-key>"

The human Inbox lists threads with ?view=threads (Inbox unless folder is archive or trash) and opens one with ?thread=<64-hex-id>, which marks that thread read. POST /inbox with unread or folder marks a thread unread or moves it. Same auth, no credit. list_inbox stays the flat list and does not take folder. ?q= searches subject, from, and body. Drafts use GET/POST/DELETE /drafts with an eligible signed-in user’s Firebase ID token and stay scoped to that user. Customers need a ready account. Agent keys cannot access drafts.

Threaded sends also store an outbound copy so the next reply can join the thread.

Example: tools/list

curl -sS -X POST \
  https://mailservicenow.com/api/mcp \
  -H "Authorization: Bearer msn_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Example: tools/call send_mail

curl -sS -X POST \
  https://mailservicenow.com/api/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."
      }
    }
  }'

Example: list_inbox

curl -sS -X POST \
  https://mailservicenow.com/api/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}}}'

Example: get_credits

curl -sS -X POST \
  https://mailservicenow.com/api/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":{}}}'

Developers · OpenAPI · Download .md · Get started · Sign in