Skip to main content

PurpleToad Mail MCP

PurpleToad Mail has a hosted remote MCP server for compatible AI clients. It lets an AI environment work with the domains, mailboxes, and messages you choose without putting a PurpleToad Mail password or API key into the client configuration.

The remote endpoint is:

https://mcp.purpletoadmail.com/mcp

It uses Streamable HTTP and PurpleToad Mail authorization. The API remains authoritative for account ownership, scopes, domain and mailbox boundaries, sending permissions, rate limits, and revocation.

Remote setup​

  1. Add https://mcp.purpletoadmail.com/mcp as a remote MCP server in an MCP-compatible client.
  2. Choose Connect or the equivalent authorization action in that client.
  3. Sign in to PurpleToad Mail and review the requested permissions.
  4. Choose the domains and mailboxes the connection should be able to use.
  5. Return to the client and try a read-only task first, such as searching for an email.

The exact screens differ between clients. Use the client’s remote MCP or custom connector settings rather than a local npx command.

What the remote server can do​

The available tools are grouped by the permission they require:

Read account and configuration​

  • Inspect service capabilities and the authorized account.
  • List domains, mailboxes, and aliases.
  • Read domain status, DNS records, and stored DNS health.
  • Read mailbox status, setup, and quota details.
  • List and inspect email templates, and preview a template without sending.

Read and organize mail​

  • List and search messages in authorized mailboxes.
  • Read message bodies and thread summaries.
  • List the messages in a thread.
  • Mark messages read or unread.
  • Archive messages. Archived messages remain recoverable in PurpleToad Mail.
  • List outbound messages and inspect delivery history.

Work with attachments​

  • List attachment metadata.
  • Inspect metadata for one attachment.
  • Request a short-lived signed download URL for an authorized attachment.

Signed URLs expire quickly. Do not put them in logs, public documents, or long-lived prompts.

Send and schedule mail​

When the account owner enables send automation for the connected app, the server can:

  • Send email with text, HTML, and bounded attachments.
  • Reply to a message while preserving thread continuity.
  • Forward a message, optionally including stored attachments.
  • Schedule an email.
  • Cancel an authorized scheduled email before delivery starts.
  • Send an existing PurpleToad Mail template.

Sending changes the outside world. A compatible client may show its own confirmation prompt, but the durable permission boundary is the send-automation setting on the PurpleToad Mail grant. A queued response is not proof that a recipient received the message; use outbound status and delivery history when that distinction matters.

Permissions and resource scope​

Remote MCP grants use explicit scopes. Depending on the tools selected, a client may request scopes such as:

  • mcp.connect — connect to the remote server.
  • account.read — read the account profile and usage summary.
  • domains.read — inspect authorized domain information.
  • mailboxes.read — inspect authorized mailbox and alias information.
  • mail.read — read authorized messages, threads, and attachment metadata.
  • mail.modify — mark messages and archive messages.
  • mail.send — send, reply, forward, schedule, or inspect outbound mail.
  • templates.read — list, inspect, and preview templates.
  • templates.use — use an existing template for an outbound message.

The grant can also be limited to selected domains and mailboxes. The API checks those boundaries for each request; a client cannot widen its own access by changing a tool argument.

Enable or disable sending​

Read access and send access are separate decisions. If a connected client tries to send while send automation is disabled, PurpleToad Mail rejects the operation.

To allow sending:

  1. Open the PurpleToad Mail dashboard.
  2. Go to Settings → Connected Apps.
  3. Open the relevant MCP connection.
  4. Review the warning and enable send automation only if you accept the risk of an AI client sending from the selected mailbox scope.

To stop access:

  1. Open Settings → Connected Apps.
  2. Revoke the individual connection, or revoke all remote MCP access.

Revocation invalidates the grant and its tokens. The next MCP request is checked against the API again, so a revoked connection cannot continue using an old authorization decision.

What remote MCP cannot do​

The remote server deliberately does not expose destructive account operations. It cannot:

  • Delete domains, mailboxes, aliases, templates, or messages permanently.
  • Revoke MCP access or API credentials as a tool call.
  • Reset mailbox passwords or credentials.
  • Close accounts, cancel subscriptions, issue refunds, or purge data.

Access revocation belongs in the PurpleToad Mail dashboard, where the account owner can see the connection and confirm the action.

Remote MCP versus the local npm server​

These are two separate integrations:

IntegrationBest forTransportAuthentication
Hosted remote MCPCompatible AI clients that support remote MCPStreamable HTTPPurpleToad Mail authorization
purpletoadmail-mcp npm packageLocal development and clients that require a local processstdioPurpleToad Mail API key

Use the local MCP package only when you specifically need a local process. Its configuration and available tools are not the same as the hosted remote service.

Troubleshooting​

The client asks for a bearer token instead of opening authorization​

That client may support a manually supplied token but not the hosted OAuth flow. Check whether it has a separate Remote MCP, Custom Connector, or OAuth configuration. Do not paste a PurpleToad Mail password or an API key into an untrusted client.

A read tool works but sending fails​

Check the connected app in Settings → Connected Apps. The grant needs mail.send and send automation must be enabled by the account owner. Also confirm that the selected sender is an authorized mailbox and that the account has not reached its sending limit.

An attachment URL no longer works​

Signed attachment URLs are intentionally short-lived. Request a fresh URL through the MCP tool instead of saving or reusing an old one.

The connection no longer works after being revoked​

That is expected. Reconnect the client from its remote MCP settings and authorize a new grant with the scopes and resources you want.