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 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
| Caller | Credential | How 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
errorInsufficient credits(not 402). - Rate limit on send: 5/minute and 50/UTC-day per caller. Same 429 status,
errorRate limit exceeded. The agent key shares one bucket.
Endpoints
| Name | URL |
|---|---|
| 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.
- Call
request_accessorPOST /requestAccesswithcontactEmail,domain,agentName, andintendedUse. - Wait for the email. The code is 8 digits and expires in 24 hours.
- Call
verify_access_requestorPOST /verifyAccessRequestwithrequestIdandcode. -
status: "ready"includesaccess: "standard"andapiKeyonce. 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 issetting_up. Otherwisestatus: "unavailable"and the message is “This request could not be completed.” There is no key. - Store the key in a secret store. It is shown once. Send it as
Authorization: Bearer msn_…orX-Api-Key: msn_…. IfX-Api-Keyis 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
- Discover MCP without a key. Call
request_accesswith the email or username/DNS inputs above, then persistrequestId. - Verify the emailed code or exact signup TXT with
verify_access_request. Proofs expire in 24 hours and five mismatches lock them. - If verification returns
setting_up, pollget_request_statusabout 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. - Save
apiKeywhen verification returnsready. 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. - Call
list_domains, useadd_domainif needed, and readget_dns_instructions. Publish the returned DNS records through your authorized DNS provider, then callverify_domain. MailServiceNow does not change registrar records. - Create the intended address with
add_mailbox. Check account approval/send eligibility withget_account_status, then call read-onlyget_mailbox_diagnosticswith the existingaddress; 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. LegacymtaApplied/mtaAppliedAtare receipt metadata only. Inbound delivery remainsnot_tested. Do not rotate keys, recreate the mailbox, or toggle modes to repair pending diagnostics. - 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— argsto,subject,from, and a message body. OptionalinReplyToandreferences. Supplytextor 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 setfromto an address on a verified domain you own, for examplesupport@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, omittingfromis an error (400Choose the address to send from.). The shared agent key sends asnoreply@mailservicenow.com.get_credits— returns remaining creditslist_inbox— optionallimit,mailbox→ stored inbound messages andunreadInPage. No credit cost.get_message—idormessageId→ one message, marked read. No credit cost.mark_read—idormessageId, optionalunread→ set the inbound unread flag. No credit cost. Auth failure is HTTP 401 before the tool runs.add_mailbox—domainId,localPart,mode(hosted,forward, orboth),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 frommtaMailboxExportabout every 60 seconds. LegacymtaAppliedand its timestamp record sync receipt, not current configuration or delivery proof. Useget_mailbox_diagnosticsfor exact current-revision acknowledgement and fresh service health. An admin sign-in may add a hosted mailbox onmailservicenow.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— samemodeandforwardToarguments → updates delivery. Does not delete stored mail. Output includesmode,forwardTo, anddelivery. Readget_mailbox_diagnosticsafter the change; receipt flags or elapsed time alone do not confirm the current mode is applied.delete_mailbox—address, ordomainIdandlocalPart→ 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 noforceflag. Unverified domains are not affected. A standard key is accepted. The shared agent key is refused.operator_remove_domain— admin only.uidorownerEmail, plusdomainId. When the domain has any mailbox, also passconfirmset to the domain name. Marks the domainremovedand every mailbox on itremoved. The claim is released when it still names that account. Mail stored for this domain is permanently deleted and cannot be recovered.mailservicenow.comis 409system_domain. A protected domain, and any domain that contains a protected address, is 409. A missing account can still be removed; the audit row setsownerMissing. This is the path for removing a domain's last mailbox. A standard orrequest_accesskey is 403, even for an admin email. The shared agent key and the MTA token are refused.delete_mailboxdoes not release the claim.operator_delete_request— admin only.idorids(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, pluscontactEmailfor emailed proof orusernamefor DNS proof.verify_access_request— no API key.requestIdandcode, ormethod: "dns". Returns a standard key once, orsetting_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.domainIdselects an owned domain. Returnsinstructions.recordsfor external DNS publication.verify_domain— standard customer key only.domainIdselects an owned domain. Rechecks DNS; inspectverified,transientandchecks. Does not edit DNS.add_domain— account key. Additional domains are allowed. The same normalized name returnscreated: false. A subdomain or parent of a domain already on the account is 409domain_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 409domain_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.requestIdandemailorusername. 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— requiredaddressstring. 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 isnot_tested. Forward-only storage/inbox arenot_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