Using Purpletoadmail

PurpleToad Mail Skill

PurpleToad Mail supports two separate MCP integrations: a hosted remote MCP server for compatible remote clients, and a local npm package for clients that need a local stdio process. Keep their transports and authentication models separate.

When to use this skill

• The user wants to send, receive, search, schedule, or track email.
• The user wants to add a domain, create a mailbox, or set up an alias.
• The user wants to install or configure the PurpleToad Mail MCP server.
• The user is troubleshooting email delivery, DNS, or API errors.
• The user is building an app or automation that uses PurpleToad Mail.

What is PurpleToad Mail?

PurpleToad Mail is a programmable email platform. You bring your own domains, create mailboxes and aliases, and send/receive email through an API and an MCP server. The MCP server lets any compatible AI agent call PurpleToad Mail tools natively.

Hosted remote MCP

Use the hosted service first when the AI client supports remote MCP, Streamable HTTP, or custom OAuth connectors.

https://mcp.purpletoadmail.com/mcp

The user authorizes the connection through PurpleToad Mail, selects the domain and mailbox boundary, and can revoke the grant from Settings → Connected Apps. Do not ask for a PurpleToad Mail password. Do not ask for an API key when the client supports the hosted authorization flow.

The hosted service supports scoped reading and email workflows including message search, threads, replies, forwarding, sending, scheduling, delivery status, templates, attachment metadata, and short-lived signed download URLs. Sending requires the account owner to enable send automation for the connected app. Destructive account, domain, mailbox, credential, and permanent-message operations are not available through the hosted service.

Use the PurpleToad Mail MCP documentation for setup and client-specific guidance.

Local npm installation

1. Clone and build the MCP server:

git clone https://github.com/hixistudio/purpletoadmail-mcp.git
cd purpletoadmail-mcp
npm install
npm run build

2. Get an API key from the dashboard at https://app.purpletoadmail.com → Settings → API Keys. Keys start with pt_live_ or pt_test_.

3. Configure the server. Choose one method:

Environment variables:

export PURPLETOAD_API_KEY="pt_live_your_key_here"
export PURPLETOAD_DEFAULT_FROM="agent@yourdomain.com"

Config file:

mkdir -p ~/.purpletoad
cat > ~/.purpletoad/config.json <<EOF
{
  "apiKey": "pt_live_your_key_here",
  "defaultFrom": "agent@yourdomain.com"
}
EOF

4. Add the MCP server to your AI client:

Claude Desktop:

{
  "mcpServers": {
    "purpletoad": {
      "command": "npx",
      "args": ["-y", "purpletoadmail-mcp"],
      "env": {
        "PURPLETOAD_API_KEY": "pt_live_your_key_here",
        "PURPLETOAD_DEFAULT_FROM": "agent@yourdomain.com"
      }
    }
  }
}

Kimi Code:

{
  "mcpServers": {
    "purpletoad": {
      "command": "npx",
      "args": ["-y", "purpletoadmail-mcp"],
      "env": {
        "PURPLETOAD_API_KEY": "pt_live_your_key_here",
        "PURPLETOAD_DEFAULT_FROM": "agent@yourdomain.com"
      }
    }
  }
}

Cursor / Windsurf:

{
  "mcpServers": {
    "purpletoad": {
      "command": "npx",
      "args": ["-y", "purpletoadmail-mcp"],
      "env": {
        "PURPLETOAD_API_KEY": "pt_live_your_key_here"
      }
    }
  }
}

If you are running from the local repo instead of npm, replace purpletoadmail-mcp with the path to the built repo.

Tool reference

For hosted remote MCP, prefer the remote tool catalog and its explicit scopes. For local MCP, use the package tools with the user’s API-key permissions. Never describe the local npm process as the hosted OAuth service.

Use these tools when helping the user. Always prefer tool calls over explaining how to use the API.

Account

• get_account — Show account profile, plan, and usage stats. Use when the user asks about limits, quota, or subscription.

Sending email

• send_email — Send an email from a PurpleToad Mail mailbox.
• schedule_email — Schedule a future email.
• cancel_scheduled_email — Cancel a scheduled email before it sends.
• list_outbound_messages — List sent emails with delivery status.
• get_outbound_message — Get detailed delivery history for one sent email.

Receiving email

• list_messages — List inbound emails with filters (unread, since, from, thread).
• get_message — Get full message body and attachments.
• search_messages — Full-text search across inbound email.
• mark_read — Mark a message as read.
• archive_message — Archive a message.

Domains and infrastructure

• list_domains — List domains with verification status and mailbox counts.
• get_domain — Show DNS records and verification details for one domain.
• create_domain — Add a new domain and return DNS records to copy-paste. Requires manage scope.
• list_mailboxes — List mailboxes with quota usage.
• get_mailbox — Show mailbox details.
• create_mailbox — Create a mailbox. Returns a one-time password. Requires manage scope.
• update_mailbox_password — Change a mailbox password. Requires manage scope.
• list_aliases — List aliases and their targets.
• create_alias — Create an alias that forwards to one or more mailboxes. Requires manage scope.

Common workflows

Send a simple email

1. If from is not provided, call get_account or list_mailboxes to confirm the default sender is valid.
2. Call send_email with from, to, subject, and either text or html.
3. Return the message_id and any rate-limit info to the user.

Example:

send_email(
  from="hello@mycompany.com",
  to=["john@example.com"],
  subject="Welcome!",
  text="Thanks for signing up."
)

Check unread emails

1. Call list_messages(mailbox="support@mycompany.com", unread_only=true).
2. For the most relevant message, call get_message(message_id=...) .
3. If the user wants to reply, call send_email with a thread_id if available.

Search for an email

1. Call search_messages(query="invoice Acme").
2. Ask the user which result, or call get_message on the top match.

Add a new domain

1. Call create_domain(domain="mycompany.com").
2. Format the returned DNS records as a table (MX, SPF, DKIM, DMARC).
3. Tell the user to paste them into their DNS provider.
4. After the user confirms, call get_domain(domain="mycompany.com") to check verification status.

Create a mailbox

1. Call create_mailbox(domain_id="...", local_part="support", display_name="Support", quota_mb=512).
2. Show the generated password once and tell the user to change it immediately.

Create an alias

1. Call create_alias(domain_id="...", source="support", targets=["alice@mycompany.com", "bob@mycompany.com"]).
2. Confirm the alias and its targets.

Schedule a follow-up

1. Call schedule_email(..., send_at="2026-06-08T09:00:00Z").
2. Return the scheduled message ID and send time.

Track delivery

1. Call list_outbound_messages(date_from="...", status="delivered").
2. For any interesting message, call get_outbound_message(message_id=...).

Configuration options

Guardrails and troubleshooting

Before sending

• The from address must be a real mailbox owned by the account, not an alias.
• Use list_mailboxes if you are unsure which addresses are valid.
• If from is omitted, PURPLETOAD_DEFAULT_FROM must be set.

Deliverability checklist

If an email bounces or lands in spam:

1. Call get_domain for the sender domain and confirm all DNS records are published: MX, SPF, DKIM, DMARC.
2. Verify the DKIM public key in DNS matches the value returned by get_domain.
3. Check the sender reputation with list_outbound_messages and get_outbound_message.
4. Ask the user to confirm the receiving domain is not suppressing the address.
5. For attachment failures, ensure the attachment size is within the plan limit and the content is not flagged by the recipient provider.

Common errors

• INVALID_FROM — Use list_mailboxes to pick a valid sender.
• DOMAIN_NOT_VERIFIED / DOMAIN_NOT_ACTIVE — DNS records are missing or wrong. Use get_domain to see the required records.
• RATE_LIMIT_EXCEEDED — Plan quota reached. Suggest waiting or upgrading.
• INSUFFICIENT_SCOPE — The API key lacks permission. Create a key with the required scope (send, read, manage).
• NO_DEFAULT_FROM — Provide from in the tool call or set PURPLETOAD_DEFAULT_FROM.

Security notes

• API keys are shown once in the dashboard. If lost, revoke and create a new one.
• Do not commit API keys to Git.
• The SSE transport requires Authorization: Bearer <PURPLETOAD_API_KEY> on the initial /sse request.
• Mailbox passwords are shown once. Tell the user to change them immediately.

For hosted remote MCP, access revocation belongs in the dashboard rather than in an MCP tool. Never claim that a tool can revoke access, delete resources, reset credentials, close an account, refund, purge data, or permanently delete messages. Signed attachment URLs are short-lived and must not be logged or published.