Purpletoadmail skill

PurpleToad Mail Skill

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.

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="[email protected]"

Config file:

mkdir -p ~/.purpletoad
cat > ~/.purpletoad/config.json <<EOF
{
  "apiKey": "pt_live_your_key_here",
  "defaultFrom": "[email protected]"
}
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": "[email protected]"
      }
    }
  }
}

Kimi Code:

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

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

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="[email protected]",
  to=["[email protected]"],
  subject="Welcome!",
  text="Thanks for signing up."
)

Check unread emails

1. Call list_messages(mailbox="[email protected]", 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=["[email protected]", "[email protected]"]).
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

Variable	Required	Default	Description
PURPLETOAD_API_KEY	Yes	—	API key (pt_live_* or pt_test_*)
PURPLETOAD_DEFAULT_FROM	No	—	Default sender address
PURPLETOAD_BASE_URL	No	https://api.purpletoadmail.com	API base URL
PURPLETOAD_TIMEOUT	No	30	Request timeout (seconds)
PURPLETOAD_TRANSPORT	No	stdio	stdio or sse
PURPLETOAD_PORT	No	3001	Port for SSE transport

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.