assistantmail-mcp
MCP server for AssistantMail — give AI agents a managed mailbox to send and receive email.
Built for personal and small-team OpenClaw / Hermes operators who want agent email with allowlist, consent, retention, and spend caps you control. Listed on ClawHub for easy install — not an official OpenClaw endorsement.
Get Free · Docs · Website · Privacy · Terms · Contributing
OpenClaw / ClawHub
openclaw skills install @assistantmail/assistant-mail
Then configure your MCP client to run this server and set ASSISTANT_MAIL_API_KEY (Claude Desktop and Cursor examples below). Skill: assistant-mail on ClawHub. Same MCP works with Hermes.
Installation
npx -y @assistantmail/assistantmail-mcp
Node 24+.
Claude Desktop
{
"mcpServers": {
"assistantmail": {
"command": "npx",
"args": ["-y", "@assistantmail/assistantmail-mcp"],
"env": {
"ASSISTANT_MAIL_API_KEY": "amk_..."
}
}
}
}
Cursor / VS Code (.cursor/mcp.json or .vscode/mcp.json)
{
"servers": {
"assistantmail": {
"command": "npx",
"args": ["-y", "@assistantmail/assistantmail-mcp"],
"env": {
"ASSISTANT_MAIL_API_KEY": "amk_..."
}
}
}
}
Prerequisites
- Create a free account via the Get Free link above (1 agent, 25/day; current limits: Docs).
- Go to API Keys and create a key (
amk_...). Copy it immediately — it is only shown once.
- Set
ASSISTANT_MAIL_API_KEY; call assistantmail_list_mailboxes to get your mailboxId UUID. Mail API routes use that UUID, not an email address.
Paid plans: upgrade in-app only (not Payment Links). Use Upgrade in the AssistantMail app — checkout is not sold via Stripe Payment Links. Docs: assistant-mail.ai/docs
Official MCP Registry
The listing is live as io.github.AssistantMail/assistantmail-mcp on the Official MCP Registry. Product docs: assistant-mail.ai/docs.
Packaging lives in server.json. After a version bump, republish with mcp-publisher — see docs/MCP_REGISTRY.md.
Environment variables
| Variable | Default | Description |
|---|
ASSISTANT_MAIL_API_KEY | (none) | API key (amk_...). Can be omitted if passed per-tool. |
ASSISTANT_MAIL_API_BASE_URL | https://api.assistant-mail.ai | The public API for the AssistantMail service |
Diagnostics
| Tool | Description |
|---|
assistantmail_health | Check that the MCP server is running and confirm the API base URL. No API key required. |
Account
| Tool | Description |
|---|
assistantmail_get_me | Get account profile and plan tier. |
assistantmail_get_inbound_policy | Get the current inbound email policy (who can send to this account's mailboxes). |
assistantmail_update_inbound_policy | Update the inbound policy (if allowed by selected account tier). Accepted values: owner, list, sent. Use allowedSenders with list. |
Mailboxes
| Tool | Description |
|---|
assistantmail_list_mailboxes | List all mailboxes on the account. Returns mailboxId needed for message operations. |
assistantmail_create_mailbox | Create a new mailbox (if allowed by selected account tier), optionally specifying displayName and address. |
assistantmail_get_mailbox | Get metadata for a single mailbox by mailboxId. |
assistantmail_update_mailbox | Update a mailbox's display name. |
assistantmail_delete_mailbox | Permanently delete a mailbox and all its messages. THIS ACTION HAS NO CONFIRMATION. USE CAREFULLY. |
Messages
| Tool | Description |
|---|
assistantmail_list_messages | List inbound and outbound messages for a mailbox. Supports since (ISO timestamp) and limit (max 100). |
assistantmail_get_message | Fetch a single message including textBody and htmlBody. Bodies are only returned within the plan's retention window; bodyExpired: true is set if the window has elapsed. |
assistantmail_send_email | Queue an outbound email. Requires to, subject, and at least one of text or html. |
assistantmail_reply_message | Reply to an existing message. Requires messageId and at least one of text or html; recipients and subject are derived automatically. |
assistantmail_delete_messages | Delete messages by messageIds array, or pass deleteAll: true to clear the mailbox. |
assistantmail_get_usage | Get daily and monthly send quota usage for a mailbox. A null limit means unlimited. |
Recipients
| Tool | Description |
|---|
assistantmail_list_recipients | List approved and pending recipients for the account. |
assistantmail_add_recipient | Add a recipient. Sends a consent invitation email when required by the account's plan. |
assistantmail_remove_recipient | Remove a recipient from the allowed list. |
These return raw REST endpoint details rather than calling the API. Use them when you need to construct a request manually or inspect the exact URL and response schema.
| Tool | Description |
|---|
assistantmail_send_email_reference | Endpoint, headers, and body fields for POST /v1/mailboxes/{mailboxId}/messages. |
assistantmail_list_messages_reference | Endpoint and query params for GET /v1/mailboxes/{mailboxId}/messages. |
assistantmail_get_message_reference | Endpoint and response schema for GET /v1/mailboxes/{mailboxId}/messages/{messageId}. |
assistantmail_get_usage_reference | Endpoint and response schema for GET /v1/mailboxes/{mailboxId}/usage. |
Quick start
API_KEY="amk_..."
BASE="https://api.assistant-mail.ai"
curl "$BASE/v1/mailboxes" -H "x-api-key: $API_KEY"
curl -X POST "$BASE/v1/mailboxes/<mailboxId>/messages" \
-H "x-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"to":"recipient@example.com","subject":"Hello","text":"Hi there"}'
curl "$BASE/v1/mailboxes/<mailboxId>/messages" -H "x-api-key: $API_KEY"
{ "tool": "assistantmail_list_mailboxes", "input": { "apiKey": "amk_..." } }
{
"tool": "assistantmail_list_messages",
"input": { "mailboxId": "<uuid>", "limit": 20, "since": "2026-01-01T00:00:00.000Z" }
}
{
"tool": "assistantmail_get_message",
"input": { "mailboxId": "<uuid>", "messageId": "<uuid>" }
}
{
"tool": "assistantmail_send_email",
"input": {
"mailboxId": "<uuid>",
"to": "recipient@example.com",
"subject": "Hello",
"text": "Hi there"
}
}
{
"tool": "assistantmail_reply_message",
"input": {
"mailboxId": "<uuid>",
"messageId": "<uuid>",
"text": "Thanks for the update."
}
}
If ASSISTANT_MAIL_API_KEY is set in the server environment, apiKey can be omitted from all tool inputs.
AssistantMail · Privacy Policy · Terms of Use