MCP server

The official shipmail MCP server lets AI agents work with domains, mailboxes, messages, threads, webhooks, and suppressions through structured tools. It runs locally over stdio and uses your shipmail API key.

Last updated May 14, 2026

Install

Add this server to any MCP-compatible host that supports stdio servers.

{
  "mcpServers": {
    "shipmail": {
      "command": "npx",
      "args": ["-y", "shipmail-mcp"],
      "env": {
        "SHIPMAIL_API_KEY": "sm_live_..."
      }
    }
  }
}

Create API keys from the shipmail dashboard. For setup details, see API authentication.

Client examples

Claude Desktop, Cursor, Windsurf, and other stdio-compatible MCP hosts use the same command shape. Keep the key server-side in the host environment and use --tools when a workflow needs only a subset of ShipMail actions.

Claude Desktop

{
  "mcpServers": {
    "shipmail": {
      "command": "npx",
      "args": ["-y", "shipmail-mcp"],
      "env": {
        "SHIPMAIL_API_KEY": "sm_live_..."
      }
    }
  }
}

Cursor or Windsurf

{
  "mcpServers": {
    "shipmail-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "shipmail-mcp",
        "--tools",
        "shipmail_status,shipmail_list_mailboxes,shipmail_list_messages,shipmail_get_message"
      ],
      "env": {
        "SHIPMAIL_API_KEY": "sm_live_..."
      }
    }
  }
}

Configuration

Variable	Description
SHIPMAIL_API_KEY	Required API key (or use `SHIPMAIL_API_KEY_FILE`). Use the minimum scopes needed for the tools you enable.
SHIPMAIL_API_KEY_FILE	Optional path to a file containing the API key. Takes precedence over `SHIPMAIL_API_KEY`. Useful with Docker secrets or systemd `LoadCredential`.
SHIPMAIL_BASE_URL	Optional. Defaults to `https://shipmail.to/api/v1`. Production values must use HTTPS on a shipmail.to host.
SHIPMAIL_MCP_TOOLS	Optional comma-separated tool allowlist.
SHIPMAIL_ALLOW_INSECURE_BASE_URL	Set to `1` only for local development against non-HTTPS or non-shipmail hosts.

Limit the tool surface

Use --tools to expose only the tools a workflow needs. The flag overrides SHIPMAIL_MCP_TOOLS when both are set.

{
  "args": [
    "-y",
    "shipmail-mcp",
    "--tools",
    "shipmail_list_mailboxes,shipmail_get_thread,shipmail_reply_to_thread"
  ]
}

Tools

Tools return both MCP structured content and a text fallback. Mutating tools accept an optional idempotency_key; when omitted, the MCP server generates one.

Group	Tools
Status	shipmail_status
Domains	shipmail_list_domains, shipmail_get_domain, shipmail_create_domain, shipmail_update_domain, shipmail_delete_domain, shipmail_verify_domain, shipmail_search_domains
Mailboxes	shipmail_list_mailboxes, shipmail_get_mailbox, shipmail_create_mailbox, shipmail_update_mailbox, shipmail_delete_mailbox, shipmail_list_mailbox_folders, shipmail_create_mailbox_folder, shipmail_update_mailbox_folder, shipmail_delete_mailbox_folder, shipmail_list_mailbox_identities, shipmail_get_mailbox_rules, shipmail_set_mailbox_rules, shipmail_reset_mailbox_password, shipmail_set_auto_reply, shipmail_set_spam_filter
Mailbox inbox	shipmail_list_mailbox_inbox_messages, shipmail_get_mailbox_inbox_thread, shipmail_update_inbox_message, shipmail_move_inbox_message, shipmail_delete_inbox_message
Messages and threads	shipmail_list_messages, shipmail_get_message, shipmail_send_message, shipmail_reply_to_message, shipmail_list_threads, shipmail_get_thread, shipmail_reply_to_thread
Webhooks	shipmail_list_webhooks, shipmail_get_webhook, shipmail_create_webhook, shipmail_update_webhook, shipmail_delete_webhook, shipmail_rotate_webhook_secret, shipmail_test_webhook, shipmail_list_webhook_deliveries
Suppressions	shipmail_list_suppressions, shipmail_remove_suppression

Resources and prompts

Resources expose common read-only objects by URI. Prompts provide guided workflows that help agents stay inside safe operating boundaries.

Resources

shipmail://account/status
shipmail://domains
shipmail://domains/{id}
shipmail://mailboxes
shipmail://mailboxes/{id}
shipmail://mailboxes/{id}/folders
shipmail://mailboxes/{id}/identities
shipmail://mailboxes/{id}/rules
shipmail://mailboxes/{id}/inbox/messages
shipmail://mailboxes/{id}/inbox/threads/{thread_id}
shipmail://messages/{id}
shipmail://threads/{id}

Prompts

setup_domain
triage_mailbox
draft_reply
configure_webhook

Security behavior

Email bodies, addresses, and error text are sanitized before reaching the LLM.
Unexpected upstream errors are redacted while preserving the request ID for support.
Webhook URLs must be public HTTPS endpoints.
Risky tools have per-session circuit-breaker limits.
Destructive tools are annotated so MCP hosts can require confirmation.

Production smoke test

The repository QA command installs the published npm package in a temporary directory and connects over MCP stdio. It verifies startup, tool registration, and status access without changing account state.

bun run qa

Not included

The MCP server currently runs over local stdio. A hosted Streamable HTTP endpoint is not available yet because it needs production OAuth, tenant isolation, abuse controls, and audit logging.

Domain purchase is also not exposed as an MCP tool. Domain registration can charge a saved payment method and requires explicit pricing, contact, and legal confirmation, so it should remain outside the agent tool surface until a dedicated approval flow exists.