assistant-mail

AssistantMail AI Agent Skill

Capability

This skill gives AI agents a consistent way to discover AssistantMail endpoint details and directly fetch mailbox/message data through MCP.

Critical Access Model

• Knowing an email address like agent-b1e4643c@assistant-mail.ai does not grant mailbox access.
• Backend mail APIs are keyed by mailboxId (UUID path parameter), not by mailbox email address.
• Mailbox operations are authorized by account ownership (mailbox.accountId === auth.accountId).

What this means for agents:

• The mailbox email address is a routing address, not an authentication secret.
• Your client must call mailbox routes with the correct mailboxId.
• A valid API key or Cognito JWT is still required.

Agent Bootstrap (Required)

1. Human owner registers or signs in on assistant-mail.ai. Learn more
2. Human owner creates an API key with POST /v1/api-keys.
3. Human owner shares the returned amk_... key securely with the agent runtime.
4. Agent lists mailboxes via GET /v1/mailboxes and stores the target mailboxId.
5. Agent uses that mailboxId for send/list/get/usage routes.

Notes:

• API keys are only shown once at creation.
• API key management endpoints are only available from the human-facing app
• API key auth can be supplied as x-api-key: amk_... or Authorization: Bearer amk_....

MCP Connection

• Command: assistantmail-mcp
• Environment:
  • ASSISTANT_MAIL_API_BASE_URL (optional, defaults to https://api.assistant-mail.ai)
  • ASSISTANT_MAIL_API_KEY (optional, amk_...; used by direct tools when apiKey input is omitted)
• Available tools:
  • assistantmail_health
  • assistantmail_get_me
  • assistantmail_get_inbound_policy
  • assistantmail_update_inbound_policy
  • assistantmail_list_mailboxes
  • assistantmail_create_mailbox
  • assistantmail_get_mailbox
  • assistantmail_update_mailbox
  • assistantmail_delete_mailbox
  • assistantmail_list_messages
  • assistantmail_get_message
  • assistantmail_send_email
  • assistantmail_reply_message – Reply to an email the agent has received. Handles threading (In-Reply-To, References) automatically.
  • assistantmail_delete_messages
  • assistantmail_get_usage
  • assistantmail_list_recipients
  • assistantmail_add_recipient
  • assistantmail_remove_recipient
  • assistantmail_send_email_reference
  • assistantmail_list_messages_reference
  • assistantmail_get_message_reference
  • assistantmail_get_usage_reference

These direct tools cover the API-key operational endpoints agents are expected to call.

OpenClaw

Use this skill by registering the MCP command assistantmail-mcp in your OpenClaw skill/MCP registry.

Claude

Use this skill by adding an MCP server entry that launches assistantmail-mcp.

OpenAI

Use this skill by configuring an MCP connector that starts assistantmail-mcp and exposes the tools above.

Direct MCP Calls (No Manual URL Building)

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

{
  "tool": "assistantmail_get_mailbox",
  "input": {
    "mailboxId": "",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_list_messages",
  "input": {
    "mailboxId": "",
    "limit": 50,
    "since": "2026-01-01T00:00:00.000Z",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_get_message",
  "input": {
    "mailboxId": "",
    "messageId": "",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_send_email",
  "input": {
    "mailboxId": "",
    "to": "recipient@example.com",
    "subject": "Hello",
    "text": "Hi there",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_reply_message",
  "input": {
    "mailboxId": "",
    "messageId": "",
    "text": "Thanks for your email!",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_get_usage",
  "input": {
    "mailboxId": "",
    "apiKey": "amk_..."
  }
}

{
  "tool": "assistantmail_list_recipients",
  "input": {
    "apiKey": "amk_..."
  }
}

If ASSISTANT_MAIL_API_KEY is set in the MCP server environment, you can omit apiKey in tool input.