Call the email MCP server
straight from curl or a script
No client, no SDK. One Streamable HTTP endpoint that speaks JSON-RPC 2.0, authenticated with a scoped bearer key you can revoke in one click.
POST JSON-RPC 2.0 to https://mcpemails.com/api/mcp with an Authorization Bearer header carrying an API key from your dashboard. Supported methods are initialize, tools/list, tools/call, prompts/list and prompts/get.
How A script or raw HTTP client connects: a scoped API key
A script or raw HTTP client does not run the OAuth browser flow against a remote MCP server, so it authenticates with a bearer token instead. Create an API key in your dashboard, tick only the scopes the agent needs, and paste it into A script or raw HTTP client as an Authorization: Bearer header. Key connections and OAuth connections hit the same endpoint and get the same tool catalogue; the difference is only how the token is obtained.
The one value you need
Everything on this page is a way of getting this URL into curl and the raw API.
| Field | Value |
|---|---|
| MCP server URL | https://mcpemails.com/api/mcp |
| Transport | Streamable HTTP (MCP 2025-06-18) |
| Authentication | Authorization: Bearer, using a scoped API key from your dashboard. |
How to connect curl and the raw API to your inbox
Four steps. The first two are the same for every client, the rest are specific to this one.
Create a free account and connect a mailbox
Sign up at mcpemails.com, no card required, then go to Dashboard, Inboxes, Connect Inbox. Gmail connects with one-click Google sign-in; iCloud, Fastmail, Yahoo, Zoho and Yandex take an app-specific password; anything else connects over plain IMAP and SMTP. The free plan holds one inbox, forever.
Create a scoped API key
In Dashboard, API Keys, click Create key. Name it and tick only the scopes this agent needs: read:email, search:email, send:email, manage:folders, delete:email, manage:drafts, manage:contacts, schedule:email and manage:automations. The key looks like mcpe_ followed by 64 hex characters and is shown once, so copy it before you close the dialog.
Call the endpoint
POST a JSON-RPC 2.0 body to https://mcpemails.com/api/mcp with the key on the Authorization header. Start with tools/list to see the catalogue, then inbox_list to discover your mailbox ids.
Handle the response
Results come back as JSON-RPC 2.0. Successful results also carry a typed structuredContent object, so a script does not have to parse prose.
curl -X POST https://mcpemails.com/api/mcp \
-H "Authorization: Bearer mcpe_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Wondering which mailbox to connect first? See the provider compatibility matrix
What trips people up in curl
Send the key on the header, not in the query string
A key on ?key= or ?api_key= is still accepted for integrations that predate the header, but it should not be used in anything new. URL credentials survive in browser history, proxy logs, referrer headers and monitoring systems, none of which you control. The Authorization header is the supported path.
Outbound calls take an idempotency key, and retries without one are a real risk
Send, reply, forward, draft send and scheduled send accept an optional idempotency key, honoured for 24 hours. A network timeout on a send is ambiguous by nature: the mail may well have gone. With an idempotency key the retry is safe. Without one, a retry is a second email.
Long operations are genuinely long
A search-and-move across a large mailbox has been observed taking around 152 seconds in production, and the proxy allows up to 270 seconds before it gives up on its own. Set a client timeout that reflects that rather than the usual few seconds, or you will cancel operations that were about to succeed.
There is no push, in either direction
No webhooks, no server-initiated events, no callback URL to register. Reacting to new mail means polling, for example email_read with action: "list" and unread only, on whatever interval your workflow needs. Rate limits are 100 per minute, 1,000 per hour and 10,000 per day per key.
Limits worth knowing
- Requests are rate limited to 100 per minute, 1,000 per hour and 10,000 per day per key, plus your plan ceiling on billable actions.
- The server is request and response only. There are no webhooks and no server-initiated events, so new mail never wakes your agent by itself. To react to arriving mail, poll on a schedule.
- Mail is fetched live from your provider on every call and never stored. Only the encrypted OAuth token or app password is kept, so a revoked token or a changed mailbox password ends access immediately.
curl and the raw API and email, answered
Can I use this without an MCP client?
Yes. It is an ordinary HTTPS endpoint speaking JSON-RPC 2.0, so curl, a cron job, a backend service or any HTTP library can call it. Authenticate with a bearer API key from Dashboard, API Keys. The tool catalogue is identical to what an MCP client sees.
Which JSON-RPC methods are supported?
initialize, tools/list, tools/call, prompts/list and prompts/get. Successful results carry a typed structuredContent object alongside the human-readable content, which is what a script should read.
How do I make retries safe?
Pass an idempotency key on outbound operations. Send, reply, forward, draft send and scheduled send accept one and honour it for 24 hours, so retrying the same request after a timeout cannot produce a second email. Reads are naturally safe to retry.
What are the rate limits?
100 requests per minute, 1,000 per hour and 10,000 per day per key, plus your plan ceiling on billable actions. Failed calls and inbox_list are not billed.
Is my email stored on your servers?
No. Every message is fetched live from your provider for the request that asked for it and handed straight to your client. Only the encrypted OAuth token or app password is kept, so future calls can authenticate. Deleting the inbox in the dashboard, or revoking access at your provider, ends the connection at once.
Script your inbox
One endpoint, one scoped key. One inbox free forever, no card required.