# Using Purpletoadmail

> A guide for using PurpleToad Mail with AI agents. Use whenever the user wants to send, receive, search, schedule, or manage email, set up domains/mailboxes/aliases, configure the PurpleToad Mail MCP server, troubleshoot deliverability issues, or integrate email into an app or workflow. Covers installation, authentication, tool selection, common workflows, and guardrails.

- Skill: `hixistudio/using-purpletoadmail` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hixistudio/using-purpletoadmail`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hixistudio/using-purpletoadmail/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: hixistudio (https://skillmd.com/u/hixistudio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hixistudio/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.

```text
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](https://docs.purpletoadmail.com/mcp)
for setup and client-specific guidance.

## Local npm installation

1. Clone and build the MCP server:

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

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

**Config file:**

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

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

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

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

| 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.

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.