# MailAgents

MailAgents is an email inbox, sending, search, task triage, and E2EE workflow service for AI agents.

Primary agent entry points:
- Agent guide: https://mailagents.net/agent-guide
- MCP discovery: https://mailagents.net/api/mcp
- MCP endpoint: https://mailagents.net/mcp
- OpenAPI schema: https://mailagents.net/api/agent/v1/openapi.json
- Full agent notes: https://mailagents.net/llms-full.txt
- Agent manifest: https://mailagents.net/.well-known/mailagents-agent.json

Authentication:
- Preferred for agents: mailbox token in the X-Agent-Token header.
- OAuth is available for MCP clients that support protected-resource metadata.
- Use the smallest mailbox-token scope that fits the task: send, read, or read+send.

Agent quickstart:
1. Create a mailbox token in the MailAgents UI with send or read+send scope.
2. Discover MCP: GET https://mailagents.net/api/mcp
3. Confirm identity: POST https://mailagents.net/mcp with X-Agent-Token and tools/call whoami.
4. Send mail: tools/call send_email with to, subject, text or html, and idempotencyKey.
5. Verify delivery: tools/call list_emails with direction=sent; check status, createdAt, errorMessage, and delivery metadata.
6. For encrypted mail: follow decryptAction, requiredHeaders, canDecryptLocally, and oldMessageRecoverable from get_email.

Core MCP tools:
- whoami: inspect the authenticated mailbox, token scopes, and role.
- list_mailboxes: list mailboxes visible to the authenticated agent.
- list_emails/search_emails/get_email: find and read mailbox messages.
- send_email/reply_email: send new messages or replies. reply_email can omit to and default to the original sender. Use idempotencyKey for retries and bodyRef/draftRef for long bodies.
- create_body_ref: store a long subject/text/html body for 24 hours, then pass bodyRef to send_email or reply_email.
- get_email_decrypted/decrypt_email_local: helper aliases for get_email that keep decryption next-action fields in one stable response. Direct remote MCP calls return envelope metadata only; through the local MailAgents plugin bridge runtime, matching Agent E2EE envelopes are decrypted into plainText/html.
- list_email_tasks/claim_email_task/update_email_task: triage shared inbox tasks.
- ensure_agent_e2ee_key/register_agent_e2ee_bridge/list_agent_e2ee_keys: set up local Agent E2EE decryption.

JSON-RPC examples:
POST https://mailagents.net/mcp
Header: X-Agent-Token: <mailbox token>
Body: {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}
Body: {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"send_email","arguments":{"to":["user@example.com"],"subject":"Hello","text":"Test from MailAgents","idempotencyKey":"agent-demo-1"}}}
Body: {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_emails","arguments":{"direction":"sent","size":10}}}

Agent E2EE notes:
- Direct remote MCP get_email responses never expose agentEncryption.
- If decryptAction is retry_with_local_bridge_headers, retry through the registered local bridge. If localBridgeRuntimeRequired or plaintextAvailableOnlyInPluginBridge is true, raw remote MCP can release envelope metadata but cannot return plaintext.
- Required bridge headers are x-mailagents-local-e2ee-bridge, x-mailagents-local-e2ee-bridge-secret, and x-mailagents-local-e2ee-bridge-key.
- If decryptStatus is missing_agent_envelope and oldMessageRecoverable is false, the current agent key cannot decrypt that older/no-envelope message.
- Messages received after registering an Agent E2EE key can include an agent envelope for local decryption.

Long-body sending guidance:
- Prefer create_body_ref for long reports instead of placing the full body in send_email arguments.
- Pass bodyRef or draftRef to send_email/reply_email, keep idempotencyKey stable, and verify the sent message afterward.