Documentation

Your agent has an inbox
in four steps.

Connect any email account, generate an API key, paste one URL into your MCP client. Done. The full tool reference and example responses are below.

Quick start Tool reference

Quick start

Up and running in minutes.

No SDK required. MCPEmails speaks standard MCP over HTTP — drop it into any MCP-compatible agent.

01Sign up & connect an inbox

Create your account and connect Gmail

Sign up at mcpemails.com, then go to Dashboard → Inboxes → Connect Inbox. Choose Gmail and follow the OAuth flow. Your inbox is ready in under a minute.

Connect your inbox →

02Create an API key

Generate a bearer token for your agent

In Dashboard → API Keys, click "Create key". Give it a name, select the scopes your agent needs (read:email and/or send:email), and copy the key — it is shown only once.

# Your key looks like this:
mcpe_live_AbCdEfGhIjKlMnOpQrStUvWxYz123456

03Add MCPEmails to your agent

Paste the MCP endpoint into your client

Add the MCPEmails server to your MCP client config using the URL below and your bearer token. Use the tabs to see the exact format for Claude Desktop, Cursor, or a raw JSON-RPC client.

json

// claude_desktop_config.json
{
  "mcpServers": {
    "mcpemails": {
      "url": "https://mcpemails.com/mcp",
      "auth": {
        "type": "bearer",
        "token": "mcpe_live_YOUR_KEY_HERE"
      }
    }
  }
}

04Make your first call

Ask your agent to check your inbox

Copy your inbox UUID from Dashboard → Inboxes and include it in your agent's system prompt. Then ask your agent: "Check my inbox and summarise the last 5 unread messages."

# System prompt snippet — paste your real inbox UUID:
Your inbox ID is: 3f7a8b2c-1d4e-5f6a-7b8c-9d0e1f2a3b4c
Use the list_inbox MCP tool to read email.

Endpoint

One URL, standard MCP.

All traffic goes to a single Streamable HTTP endpoint. Authenticate with a bearer token from your dashboard.

POSThttps://mcpemails.com/mcp

Send a JSON-RPC 2.0 request body. Supported methods: initialize, tools/list, tools/call.

Transport: Streamable HTTP (MCP 2024-11-05)

Auth: Authorization: Bearer <api-key>

Rate limits: 100 req/min · 1,000/hr · 10,000/day per key

Response format: JSON-RPC 2.0

Initialize handshake

bash

curl -X POST https://mcpemails.com/mcp \
  -H "Authorization: Bearer mcpe_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": { "name": "my-agent", "version": "1.0" },
      "capabilities": {}
    }
  }'

Tool reference

Five tools. All the email ops your agent needs.

Every tool takes an inbox_id UUID — find yours in Dashboard → Inboxes. Click "Show example" to see a full request and response.

list_inboxread:email read_emailread:email search_emailsread:email send_emailsend:email reply_to_emailsend:email

list_inboxread:email

List email summaries from a connected inbox, newest first. Supports pagination, folder selection, and unread filtering.

Parameter	Type	Required	Description
`inbox_id`	string (uuid)	required	UUID of the inbox to list. Find it in Dashboard → Inboxes.
`limit`	integer	optional	Max results to return. Default 20, max 100.
`offset`	integer	optional	Zero-based pagination offset. Default 0.
`folder`	string	optional	Folder to list. Default "INBOX". Other values: "SENT", "DRAFTS", "TRASH".
`unread_only`	boolean	optional	Return only unread messages. Default false.

read_emailread:email

Fetch the full content of a single email by ID, including plain-text body, optional sanitized HTML, and optional attachment data.

Parameter	Type	Required	Description
`inbox_id`	string (uuid)	required	UUID of the inbox containing the email.
`message_id`	string	required	Provider message ID from list_inbox or search_emails.
`include_html`	boolean	optional	Include sanitized HTML body. Default false.
`include_attachments`	boolean	optional	Include base64 attachment data. Default false.
`mark_as_read`	boolean	optional	Mark message as read after fetching. Default false.

search_emailsread:email

Search an inbox using provider-native query syntax. Gmail supports Gmail search operators; Outlook uses $search; IMAP providers support a subset of IMAP SEARCH criteria.

Parameter	Type	Required	Description
`inbox_id`	string (uuid)	required	UUID of the inbox to search.
`query`	string	required	Search query. For Gmail: "from:alice@example.com after:2026/01/01". For Outlook: natural-language or KQL queries.
`limit`	integer	optional	Max results. Default 20, max 100.
`offset`	integer	optional	Pagination offset. Default 0.
`include_folders`	array	optional	Restrict search to these folders (IMAP only). Default: search all folders.

send_emailsend:email

Send a new email from a connected inbox. Supports plain text, optional HTML body, CC/BCC, and file attachments (up to 10 MB total).

Parameter	Type	Required	Description
`inbox_id`	string (uuid)	required	UUID of the inbox to send from.
`to`	array[string]	required	Recipient email addresses. Max 50.
`subject`	string	required	Email subject line. Max 998 characters.
`body`	string	required	Plain-text email body.
`cc`	array[string]	optional	CC recipients. Default [].
`bcc`	array[string]	optional	BCC recipients. Default [].
`html_body`	string	optional	HTML version of the body (multipart/alternative). Caller is responsible for safe HTML.
`reply_to`	string	optional	Reply-To header address.
`attachments`	array	optional	File attachments. Each item: { filename, mime_type, data (base64) }. Max 20 items, 10 MB total.

reply_to_emailsend:email

Send a reply to an existing email. Threading headers (In-Reply-To, References) are set automatically. Supports reply-all and attachments.

Parameter	Type	Required	Description
`inbox_id`	string (uuid)	required	UUID of the inbox that contains the original message.
`message_id`	string	required	Provider message ID of the email being replied to.
`body`	string	required	Plain-text reply body.
`html_body`	string	optional	Optional HTML version of the reply.
`reply_all`	boolean	optional	Reply to all original recipients (To + Cc). Default false.
`attachments`	array	optional	File attachments. Same schema as send_email. Max 20 items.

Error codes

Error codes & retry guidance.

Protocol errors are returned as JSON-RPC error objects. Execution errors are returned as normal results with isError: true.

Code	Type	When it occurs	Retryable
`-32001`	Protocol	Invalid or revoked API key	—
`-32601`	Protocol	Unknown tool name	—
`-32602`	Protocol	Missing or invalid parameter	—
`inbox_not_found`	Execution	inbox_id not found or not accessible	—
`message_not_found`	Execution	message_id does not exist (may have been deleted)	—
`scope_denied`	Execution	API key lacks required scope for this tool	—
`invalid_recipient`	Execution	A recipient address failed RFC 5322 validation	—
`auth_failed`	Execution	Provider OAuth token expired/revoked — user must reconnect	—
`rate_limit_exceeded`	Execution	Per-key rate limit hit (100/min, 1,000/hr, 10,000/day)
`quota_exceeded`	Execution	Daily send quota reached (plan limit)	—
`attachment_too_large`	Execution	Total attachment size exceeds 10 MB	—
`search_timeout`	Execution	Provider search took > 30 seconds — simplify query
`provider_error`	Execution	Provider returned an unexpected 5xx error

Example execution error response

json

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [{
      "type": "text",
      "text": "Inbox 3f7a8b2c-1d4e-5f6a-7b8c-9d0e1f2a3b4c not found or not accessible."
    }],
    "isError": true,
    "errorCode": "inbox_not_found"
  }
}

Rate limits

Rate limits & quotas.

Per key

100 requests / minute · 1,000 / hour · 10,000 / day

Limits are enforced per API key in rolling windows. When exceeded, the server returns rate_limit_exceeded with a retryAfter field (seconds to wait).

Send quota

200 sends / day (Free) · 2,000 / day (Pro) · Custom (Enterprise)

Applies only to send_email and reply_to_email. Counted per workspace per UTC calendar day. Returns quota_exceeded when reached.

Retrying

Use the retryAfter field — never retry sends blindly

For rate_limit_exceeded and provider_error, use exponential backoff starting at retryAfter seconds. Do not auto-retry send_email on provider_error — the message may have been accepted; check delivery_status first.

Ready to connect your inbox?

Start on the Free plan — 100 MCP calls / month, no card required. Upgrade when your agent needs more.

Get started free See pricing

Your agent has an inboxin four steps.