Sign inGet started

MCP server

The Postilon MCP server lets AI assistants that speak the Model Context Protocol, such as Claude Desktop, Claude Code and Cursor, use your workspace: send email, follow its delivery, read inbound email and manage templates and domains. It is the npm package @postilon/mcp (source, MIT), runs on your computer with Node.js 18 or later, and calls the API with your API key.

Choose a key

Create a key in the dashboard under API Keys.

  • Start with a ps_test_… key. Emails are accepted, rendered and reported like real ones, but nothing is delivered and no credits are used, and any from address works.
  • A ps_live_… key sends real mail from a verified domain and uses credits. Your assistant can then email anyone, so check what it is about to send.
  • A key with sending access can only use the email tools. The domain, inbound and template tools need full access.

Set it up

The server reads its settings from environment variables:

Variable Description
POSTILON_API_KEY Your API key (required).
POSTILON_FROM Sender used when the assistant gives none, such as Acme <hello@acme.com>.
POSTILON_REPLY_TO Reply-to address used when the assistant gives none.
POSTILON_BASE_URL API base URL; defaults to https://api.postilon.com.

Claude Desktop

Open Settings → Developer → Edit Config, add the server to claude_desktop_config.json, and restart Claude Desktop:

{
  "mcpServers": {
    "postilon": {
      "command": "npx",
      "args": ["-y", "@postilon/mcp"],
      "env": {
        "POSTILON_API_KEY": "ps_test_…",
        "POSTILON_FROM": "Acme <hello@acme.com>"
      }
    }
  }
}

Cursor

Add the same mcpServers entry to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json in one project.

Claude Code

claude mcp add postilon -e POSTILON_API_KEY=ps_test_… -e POSTILON_FROM="Acme <hello@acme.com>" -- npx -y @postilon/mcp

Other MCP clients start the server the same way: the command npx -y @postilon/mcp with the variables above, over stdio.

Tools

Tool Description
send_email Send one email: HTML and/or text, or a template_id with variables; cc, bcc, reply_to, scheduled_at and an idempotency_key. See Send email.
send_batch Send up to 100 emails in one request, each with its own recipient and variables.
get_email Get an email with its status and events.
list_emails List emails, filtered by status, search text q, source or days.
cancel_email Cancel a queued or scheduled email.
list_domains List sending domains and their status.
get_domain Get a domain with its DNS records.
add_domain Add a sending domain.
verify_domain Check a domain's DNS records now.
list_inbound List received email.
get_inbound Get a received email with its headers and SPF, DKIM and DMARC results.
list_templates List templates.
get_template Get a template.
create_template Create a template with {{ variable }} placeholders.
update_template Change a template; fields left out keep their value.
delete_template Delete a template.

Lists return 20 items unless the assistant asks for more. Each tool answers with the API's JSON response, or with its error, such as 403 domain_not_verified: …, which the assistant can explain to you. See Errors and limits for the codes.

Try it

Ask your assistant, for example:

  • "Send jane@example.com a note that her order shipped, and tell me once it's delivered."
  • "Did any email bounce in the last 7 days? Show me who and why."
  • "Create a welcome template with a first_name variable and send it to these three addresses."
  • "Add mail.acme.com and tell me which DNS records to create."
NextWebhooks