@postilon/mcp
v0.1.0
Published
MCP server for the Postilon transactional email API: send email and read its status from Claude, Cursor and other MCP clients
Maintainers
Readme
@postilon/mcp
Model Context Protocol server for the Postilon transactional email API. It lets AI assistants such as Claude Desktop, Claude Code and Cursor send email, follow its delivery, read inbound email and manage templates and domains in your Postilon workspace.
Full documentation: postilon.com/docs/mcp. Needs Node.js 18 or later.
Get an API key
In the Postilon dashboard, open API Keys and create a key.
- Start with a
ps_test_…key: emails are accepted and reported like real ones, but nothing is delivered and no credits are used. - A
ps_live_…key sends real mail from a verified domain. Your assistant can then send email to anyone, so review what it sends. - A key with sending access can only use the email tools; the domain, inbound and template tools need full access.
Configuration
| Environment variable | Description |
| --- | --- |
| POSTILON_API_KEY | Your API key (required). |
| POSTILON_FROM | Sender used when the assistant gives none, such as Acme <[email protected]>. |
| 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 and add:
{
"mcpServers": {
"postilon": {
"command": "npx",
"args": ["-y", "@postilon/mcp"],
"env": {
"POSTILON_API_KEY": "ps_test_…",
"POSTILON_FROM": "Acme <[email protected]>"
}
}
}
}Restart Claude Desktop to load it.
Cursor
Add the same entry to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):
{
"mcpServers": {
"postilon": {
"command": "npx",
"args": ["-y", "@postilon/mcp"],
"env": {
"POSTILON_API_KEY": "ps_test_…",
"POSTILON_FROM": "Acme <[email protected]>"
}
}
}
}Claude Code
claude mcp add postilon -e POSTILON_API_KEY=ps_test_… -e POSTILON_FROM="Acme <[email protected]>" -- npx -y @postilon/mcpTools
| Tool | Description |
| --- | --- |
| send_email | Send one email: HTML and/or text, or a template with variables; cc, bcc, reply-to, scheduling and an idempotency key. |
| 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, source or age. |
| cancel_email | Cancel a queued or scheduled email. |
| list_domains | List sending domains and their verification 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 authentication results. |
| list_templates | List templates. |
| get_template | Get a template. |
| create_template | Create a template with {{ variable }} placeholders. |
| update_template | Change a template. |
| delete_template | Delete a template. |
Lists return 20 items unless the assistant asks for more. Every tool answers with the API's JSON response, or with the API's error (403 domain_not_verified: …) so the assistant can explain or fix it.
Example prompts
Send [email protected] a short note saying the invoice is attached to her account, and tell me when 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, then send it to these three addresses.
Add the domain mail.acme.com and tell me which DNS records to create.
Use it in your own server
The package also exports createServer, which builds the MCP server around a client of @postilon/node:
import { createServer } from "@postilon/mcp";
import { Postilon } from "@postilon/node";
const server = createServer(new Postilon(process.env.POSTILON_API_KEY!), { defaultFrom: "[email protected]" });
// await server.connect(transport);License
MIT
