Meta Agent Tools
PT

Back to the catalog

Assistant Mail MCP

Agent email with allowlist and consent via AssistantMail.

Open source Open in the app JSON README (API)

About

Agent email with allowlist and consent via AssistantMail.

Details

Kind
MCP servers
Topic
Communication
Publisher
assistantmail
Origin
official
Category
ferramentas
Transport
local
Version
1.3.1
Last push
2026-09-04T13:38:05Z
Repository state
ativo
Language
JavaScript
License
MIT
Added
2026-09-03 01:00:19
Updated
2026-09-03 01:00:19
Origin id
io.github.AssistantMail/assistantmail-mcp

README

# assistantmail-mcp

MCP server for [AssistantMail](https://assistant-mail.ai) — 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](https://app.assistant-mail.ai/?utm_source=github&utm_medium=readme&utm_campaign=clawhub_readme_amplify) · [Docs](https://assistant-mail.ai/docs) · [Website](https://assistant-mail.ai) · [Privacy](https://assistant-mail.ai/privacy.html) · [Terms](https://assistant-mail.ai/terms.html) · [Contributing](./CONTRIBUTING.md)

## OpenClaw / ClawHub

```bash
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](https://clawhub.ai/assistantmail/skills/assistant-mail). Same MCP works with Hermes.

## Installation

```bash
npx -y @assistantmail/assistantmail-mcp
```

Node 24+.

### Claude Desktop

```json
{
  "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`)

```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](https://app.assistant-mail.ai/?utm_source=github&utm_medium=readme&utm_campaign=clawhub_readme_amplify) link above (1 agent, 25/day; current limits: [Docs](https://assistant-mail.ai/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](https://assistant-mail.ai/docs)

## Official MCP Registry

The listing is **live** as [`io.github.AssistantMail/assistantmail-mcp`](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.AssistantMail/assistantmail-mcp) on the Official MCP Registry. Product docs: [assistant-mail.ai/docs](https://assistant-mail.ai/docs).

Packaging lives in [`server.json`](./server.json). After a version bump, republish with `mcp-publisher` — see [docs/MCP_REGISTRY.md](./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

```bash
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

```json
{ "tool": "assistantmail_list_mailboxes", "input": { "apiKey": "amk_..." } }
```

```json
{
  "tool": "assistantmail_list_messages",
  "input": { "mailboxId": "<uuid>", "limit": 20, "since": "2026-01-01T00:00:00.000Z" }
}
```

```json
{
  "tool": "assistantmail_get_message",
  "input": { "mailboxId": "<uuid>", "messageId": "<uuid>" }
}
```

```json
{
  "tool": "assistantmail_send_email",
  "input": {
    "mailboxId": "<uuid>",
    "to": "recipient@example.com",
    "subject": "Hello",
    "text": "Hi there"
  }
}
```

```json
{
  "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](https://assistant-mail.ai) · [Privacy Policy](https://assistant-mail.ai/privacy.html) · [Terms of Use](https://assistant-mail.ai/terms.html)

More