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

1. Create a free account via the Get Free link above (1 agent, 25/day; current limits: Docs).
2. Go to API Keys and create a key (amk_...). Copy it immediately — it is only shown once.
3. 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

Tools

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.

Reference tools

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"

# 1) Discover your mailboxId
curl "$BASE/v1/mailboxes" -H "x-api-key: $API_KEY"

# 2) Send an email
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"}'

# 3) Read inbox
curl "$BASE/v1/mailboxes/<mailboxId>/messages" -H "x-api-key: $API_KEY"

Tool call examples

{ "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