# Mail Service Now ## Recommended agent connection Canonical OAuth MCP resource: https://mailservicenow.com/api/mcp Use configured server-level OAuth and sessionless Streamable HTTP (2025-11-25 or 2025-06-18), full initialize parameters, Content-Type application/json, Accept application/json,text/event-stream. POST one message per request; GET returns 405 with no SSE, notifications return 202. Legacy direct-function JSON-RPC compatibility remains separate. Resumable onboarding guide: https://mailservicenow.com/docs/agent-onboarding.md Owner-approved exact domain/mailbox scopes; connector OAuth transport retains credentials, never ordinary MCP output. start_onboarding(idempotencyKey,domain,localPart) returns one onboardingId for get_onboarding_status, resume_onboarding and renew_onboarding_proof. Separate owner approval, account approval, ownership, DNS preview, mailbox creation and exact-config MTA acknowledgement. DNS is an owner-authorized external-provider handoff, not a built-in Cloudflare connection. No automatic mail test. Customer-domain hosted/both inboxes support list_inbox, get_message, search_mailbox, send_mail and reply_to_message with mailbox scopes. Search is a bounded recent-window search. Forward-only addresses are not inboxes. Revoke one agent at https://mailservicenow.com/oauth-consent.html without affecting other clients. The remaining instructions describe the legacy account-key flow. Public get_request_status requires requestId plus email or username; new authenticated get_onboarding_status needs only onboardingId. Legacy DNS key recovery still revokes other legacy account keys and is not OAuth per-agent revocation. > Email Services & API for Private Clients. Hosted mailboxes and forwarding on a domain you own, a sending API, and an MCP server. Mail Service Now sends mail. Partner products stay their own products. The shared inbox@mailservicenow.com mailbox stays with Mail Service Now. Do not invent a key. Do not commit a key. ## Agents can sign up themselves An agent can request access, verify email or DNS, poll approval, obtain a standard customer key, and onboard its domains/mailboxes through MCP. Self-service does not mean self-approval: unmatched requests require a Mail Service Now owner/admin. Email access, credential storage, DNS-provider writes and MX cutover need 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.` (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 about every 20 minutes. 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.`, and verify with method dns. A new key is returned once. For DNS-bound recovery all previous customer keys are revoked; email recovery instead adds a key. Coordinate recovery with other clients. ```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. ## How an agent requests access No API key is required for these two calls. 1. Call MCP tool request_access, or POST /api/requestAccess, with contactEmail, domain, agentName, and intendedUse. 2. Wait for the email at contactEmail. The code is 8 digits and expires in 24 hours. The HTTP response never includes the code. 3. Call MCP tool verify_access_request, or POST /api/verifyAccessRequest, with requestId and code. 4. A ready response includes access "standard" and apiKey (msn_…) once. A setting_up response has no key and says: 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 an additional standard key once even if mail DNS/mailboxes are not yet ready. If setup is still in progress, the response is setting_up. Otherwise status is unavailable, the message is "This request could not be completed.", and 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 present, that header is the only credential checked. A standard key can send, manage domains and mailboxes, register webhooks, and call the customer MCP tools. Default quotas are 100 credits, 5 sends per minute, and 50 per UTC day. Admin routes and admin MCP tools return 403. Rate limit on request_access: 5 per hour per IP and 3 per hour per email. 429 includes retryAfter seconds. Wrong code is 401. Five failures lock the code (401). Expired code is 410. Unknown requestId is 404. A completed request verified again is 409. Invalid input is 400. ## Agent onboarding sequence 1. Request access (request_access). 2. Verify the emailed code or exact _msn-verify TXT proof (verify_access_request, method dns). 3. If the result is pending, poll get_request_status (e.g. every 20 minutes). Do NOT resend the same requestId. 4. If you do not already have a usable saved key, 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. 5. Call list_domains; add_domain only if needed. Read get_dns_instructions, publish DNS externally, call verify_domain, and add_mailbox. Check get_account_status for account approval/send eligibility, then read-only get_mailbox_diagnostics with the existing address. No onboarding ID is required. canSend does not wait for MTA sync. Legacy mtaApplied/mtaAppliedAt are receipt metadata only; current configuration requires exact revision-bound acknowledgement with a valid timestamp, and service readiness additionally requires fresh successful sync/service health. Inbound delivery remains not_tested. 6. Send only when authorized, always setting from. Diagnostics do not send an external probe or perform a resync. An account may add additional domains. POST /api/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. 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. 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. ## Check if my account is ready Keep the requestId. If verify returned setting_up, Email-based accounts may receive a ready email; username/DNS accounts receive no email. No key exists yet. 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 /api/getRequestStatus, with requestId and email (or username for DNS). 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. ready is true only when the account is ready. A ready body is { "ok": true, "status": "ready", "ready": true, "requestId": "ar_…" }. HTTP 429 is { "ok": false, "error": "Rate limit exceeded", "retryAfter": 3600 } whether or not the email is on file. After verify_access_request, call get_account_status or POST /api/getAccountStatus with that account's own key. It returns 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 such as "Add a fully hosted mailbox on a verified domain before sending." 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. A hosted address needs a domain you own. Publish MX, SPF, DKIM, and DMARC (https://mailservicenow.com/developers/domain-setup/), then create a hosted mailbox. ## Existing-mailbox readiness diagnostics get_mailbox_diagnostics requires {"address":"support@example-domain.com"}. It is read-only, limited to the account's own standard customer key and existing mailbox, and needs no onboarding ID. No UID/account selector, OAuth expansion or new standalone REST endpoint is provided. OAuth onboarding clients keep using get_onboarding_status. The result is {ok:true, diagnostic:{...}}. diagnostic separates sendEligibility, configurationProvisioning, serviceHealth, storageUsage, inboxAccess, inboundDelivery, deliveryVerification, nextAction and error. configurationProvisioning includes desiredRevision, appliedRevision, desiredUpdatedAt, lastAcknowledgedAt and appliedAt; public revisions are opaque IDs, not internal configuration digests or storage sample keys. A last acknowledgement alone is insufficient: applied requires the exact current revision and a valid timestamp at or after the desired update and not in the future. serviceHealth.ready additionally requires fresh successful sync/service health. get_account_status preserves ready/canSend compatibility, labelled readinessMeaning account_approval at account level and send_eligibility on mailbox rows. storageUsage describes Maildir allocated bytes, not a quota or delivery test. Missing/unusable telemetry is unavailable with null bytes, never assumed zero; an observed zero is valid. Old valid measurements are stale. Forward-only inbox/storage are not_applicable, and forwarding remains unverified/not_tested. inboundDelivery and applicable deliveryVerification checks stay not_tested. No secrets, DNS proof values, message content, raw stored errors or internal storage keys are exposed. Follow nextAction and reread after normal sync or operator resolution. Do not rotate keys, recreate the mailbox, or toggle modes to repair pending readiness. External probes and resync mutations are deferred, not implemented. Exact-ack sync-consumer and storage-collector installation on the mail host is a separately authorized rollout; source or API deployment does not prove either is installed. Full field contract: https://mailservicenow.com/docs/mailservicenow-for-ai.md#mailbox-readiness-diagnostics ## After a standard key: domain and mailboxes A ready response with apiKey does not publish mail DNS or create mailboxes. Email signup does not add the hostname; DNS signup/approval may already claim and add it. Inspect list_domains first. intendedUse does not provision support@ or orders@. Full checklist: https://mailservicenow.com/docs/mailservicenow-for-ai.md#after-you-have-a-standard-key-set-up-your-domain-and-mailboxes DNS for each record, including DMARC: https://mailservicenow.com/developers/domain-setup/ 1. ready plus a standard msn_… key means you can call send and the domain routes. setting_up has no key. Domain calls then return 403 Account setup is not complete yet. Send before a hosted mailbox on a verified domain returns 403 Add a fully hosted mailbox on a verified domain before sending. 2. POST /addDomain with {"domain":"example-domain.com"} and Authorization: Bearer msn_ (or X-Api-Key), or MCP add_domain. Or Add domain in the web app. The live call checks DNS immediately. created true and status failed, before you publish MX, is expected. Read dnsInstructions.records. The same normalized name again returns created false. 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 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. 3. Publish the returned account-bound ownership TXT and mail DNS records. MX mail.mailservicenow.com priority 10. One SPF TXT, copied from the dashboard (https://mailservicenow.com/developers/domain-setup/#spf). DKIM TXT at mail._domainkey, value from the response. The preferred MX must be mail.mailservicenow.com. Moving MX off Cloudflare Email Routing (route1.mx.cloudflare.net or any prior host) stops mail that host receives today. Cut over only when you mean to. Turn off Cloudflare Email Routing (or your other inbound provider) or delete its MX rows. Delete every MX row for any other provider. A row left at the same or a better priority keeps sending some of the domain's mail to that provider. 4. POST /verifyDomain with {"domainId":"example-domain.com"} (or Check DNS in the app) once DNS propagates. verified true sets status verified. transient true means retry. 5. POST /addMailbox with {"domainId":"example-domain.com","localPart":"orders","mode":"hosted"} for each address. The standard key works on this REST call and on MCP add_mailbox. A Firebase ID token also works. The shared agent key is refused with Firebase sign-in required. MCP add_domain adds a domain for this account. The web app can add the mailbox too. 6. Call get_mailbox_diagnostics with address for the existing mailbox. The usual roughly 60-second sync interval is not a readiness guarantee. Require an exact current-revision acknowledgement with a valid timestamp, then fresh successful sync/service health; legacy mtaApplied/mtaAppliedAt do not prove the configuration is current or delivery is live. Inbound delivery remains not_tested. Do not rotate keys, recreate the mailbox, or toggle modes to repair a pending diagnostic. Forward-only storage and inbox are not_applicable; forwarding remains unverified/not_tested. 7. With the owner's applicable authorization, optionally configure POST /webhooks or a proof send; GET /credits is read-only. An external delivery probe and a resync mutation are deferred, not implemented by diagnostics. An admin pending row with storedStatus code_sent, including an expired code, has decidable false and is not a mailbox hold. A decision returns 409 This request is not ready for a decision. setting_up means the account is still being finished. Once ready, do the list above. ## Domain ownership proof Every NEW claim requires its own account-bound TXT: _msn-domain. with the exact msn-domain-verification=<64hex> value returned in dnsInstructions.records (id ownership). get_dns_instructions returns instructions.records and instructions.ownership {required,expiresAt,verifiedAt}. The initial proof expires in 24 hours. Signup _msn-verify is separate; shared public MX/SPF/DKIM records alone never establish a new claim's ownership. On 409 domain_ownership_expired, repeat add_domain for that hostname, publish its renewed TXT, and call verify_domain. Repeating add_domain while the challenge is active preserves it. Proven ownership remains with that claim; removal/re-addition requires fresh proof. 409 domain_claim_changed means reload after a concurrent change. New unproven claims cannot create mailboxes (403 domain_ownership_required) or become sendable. DNS editing remains external. Previously verified domains are grandfathered; legacy unverified rows get a challenge lazily, with no bulk migration. Operators still need a separate audit of legacy verified ownership. Another account's reserved claim, even unverified, remains 409 domain_claimed; contact support, do not auto-transfer or endlessly retry. ## MCP domain tools and approval boundaries - list_domains: no arguments; this approved account's domains and legacy mailbox MTA receipt metadata - get_account_status: no arguments; account approval/send eligibility and separate per-mailbox readiness evidence - get_mailbox_diagnostics: required address string; read-only, this account's own key and existing mailbox only, no onboarding ID, no account selector, no secrets, no external probe or resync - get_dns_instructions: domainId; owned domain's instructions.records - verify_domain: domainId; owned domain's mail DNS checks, verified and transient - add_domain and add_mailbox remain the provisioning tools; standard customer keys are accepted, shared agent keys are refused The three new domain tools require the active approved account's own standard key. They do not accept a UID/account override or edit DNS at a registrar. Unauthorized, revoked, suspended and cross-account callers cannot use them. Anonymous tools/list may advertise protected tools without granting permission. A verified request_access is the approval request; there is no public approve_request or request_approval tool. Poll states are pending, setting_up, ready, unavailable. pending can also mean an unknown/mismatched request and is not proof of a real review queue entry. Rejection/lock is neutral unavailable; stop and resolve with the owner/support. The separate submitApplication email flow returns pending_review after verification. Proof expiry is reported by verify as 410; polling has no expired state. A completed proof is 409 and cannot reveal its key again. Request creation and mail sending have no idempotency key. Persist requestId; avoid blind retries after uncertain writes. Honor retryAfter on 429. Five wrong proof attempts lock verification. DNS 503 is transient; wait before retrying. Poll about every 20 minutes, within the shared-IP and identity budgets. No approval webhook is provided. MCP uses HTTP 200 for both successful tool results and most tool errors: inspect result.isError/result.structuredContent.status (402/404/409/410/429/503) and JSON-RPC error.data.status (400/401/403 and other failures). Protected-call authentication can fail at HTTP 401 before dispatch. Bootstrap initialize/tools/list/ping and the three access tools are public; mixing a protected tool into a batch requires authentication for the entire batch. Full state machine and concrete MCP examples: https://mailservicenow.com/docs/mailservicenow-for-ai.md#agent-onboarding-sequence ## Copy-paste Full steps, curl, and MCP JSON-RPC, in the How an agent requests access section: https://mailservicenow.com/docs/mailservicenow-for-ai.md ```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 {"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"}}} ``` POST that JSON to https://us-central1-mailservicenow.cloudfunctions.net/mcp with Content-Type application/json and no Authorization header. Then call verify_access_request with requestId and code. ## Apply for an account People apply at https://mailservicenow.com/apply/. The form collects a username, a name, an optional email, company, website, the domain or domains you will send from, a full use case, expected volume, whether an agent or the API will send the mail, and who referred you. A username is 3 to 64 characters: letters, digits, and . _ - + @. It may look like an email. That does not verify the address, and no mail is sent to it. When an email is entered, submit stores a pending access request and sends one email to that address. That email has fixed wording and an 8-digit code. It does not include the name or any other answer from the form. The code expires in 24 hours. After the code is verified, the page says the application was received and is pending review. A request that has not been verified is not listed for review and expires on that same 24-hour window. When no email is entered, the page calls POST /api/requestAccess with username, domain, agentName, and intendedUse, and omits contactEmail. The response has verification dns, dns.type TXT, dns.name _msn-verify plus the domain, and dns.value, a single-use token that expires in 24 hours. The page then calls POST /api/verifyAccessRequest with requestId and method dns. It can poll POST /api/getRequestStatus with requestId and username. No email is sent. The page does not show a key. 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. That returns a new key once. Example fields use placeholders such as you@example.com and example.com. ## Docs - [MailServiceNow for AI](https://mailservicenow.com/docs/mailservicenow-for-ai.md): system of record for agents - [Agent guide](https://mailservicenow.com/docs/agents.html): MCP tool reference - [OpenAPI](https://mailservicenow.com/docs/openapi.json): REST paths, including /requestAccess, /verifyAccessRequest, /getRequestStatus, and /getAccountStatus - [Developers](https://mailservicenow.com/developers/): quickstart - [Domain setup / deliverability](https://mailservicenow.com/developers/domain-setup/): MX, SPF, DKIM, DMARC, and how to check them - [Any agent product](https://mailservicenow.com/developers/any-agent/) - MCP server: https://us-central1-mailservicenow.cloudfunctions.net/mcp (version 0.8.0, protocol 2024-11-05) ## Admin requests An admin sign-in can delete access requests. MCP `operator_delete_request` takes `id` or `ids` (at most 200). REST is POST /api/admin/requestDelete with the same body. 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. Preview duplicates first with GET /api/admin/requestDuplicates?email= or domain= (one of those is required), untick rows, then send the checked ids. The server does not delete every match on its own. A standard key, the shared agent key, and the MTA token are refused. An admin sign-in can delete a domain from the Domains page, including a verified, pending DNS, or failed row. The confirm dialog names the domain and its mailbox count. If it has any mailbox, type the domain name. Mail stored for this domain is permanently deleted and cannot be recovered. MCP `operator_remove_domain` takes `uid` or `ownerEmail`, `domainId`, and `confirm` when mailboxes exist. REST is POST /api/admin/removeDomain. `mailservicenow.com` is 409 `system_domain`. A domain whose account is gone can be deleted; the audit row sets `ownerMissing` true. The claim is released in that write when it still names that account, so another account can add the domain. A customer's own mailbox removal does not release the claim. A standard key, the shared agent key, and the MTA token are refused on that delete.