Skip to main content
Glama
@postilon/mcp

@postilon/mcp

Official
by postilon

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

Related MCP server: agentisend

Configuration

Environment 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 and add:

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

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 <hello@acme.com>"
      }
    }
  }
}

Claude Code

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

Tools

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 jane@example.com 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: "hello@acme.com" });
// await server.connect(transport);

License

MIT

Available Tools

16 tools
add_domainAdd domainA

Add a sending domain. The response lists the DNS records to create before calling verify_domain.

Inputs: domain_name (required).

cancel_emailCancel emailA
DestructiveIdempotent

Cancel a queued or scheduled email before it is sent. Fails with cannot_cancel once delivery started.

Inputs: id (required).

create_templateCreate templateB

Create a template to send with send_email's template_id. Placeholders are written {{ name }}.

Inputs: name (required), variables, html_template, text_template, +1 more.

delete_templateDelete templateA
DestructiveIdempotent

Delete a template. Emails that use its ID can no longer be sent.

Inputs: id (required).

get_domainGet domainB
Read-only

Get one domain with the DNS records it needs and whether each was found.

Inputs: id (required).

get_emailGet emailA
Read-only

Get one sent email with its status and events (sent, delivered, opened, bounced, …).

Inputs: id (required).

get_inboundGet inbound emailA
Read-only

Get one received email with its headers, content, attachments list and SPF/DKIM/DMARC results.

Inputs: id (required).

get_templateGet templateA
Read-only

Get one template with its subject, HTML and text.

Inputs: id (required).

list_domainsList domainsA
Read-only

List the workspace's sending domains with their verification status.

Inputs: limit, offset.

list_emailsList emailsA
Read-only

List sent emails, newest first, optionally filtered by status, search text, source or age.

Inputs: q, days, limit, offset, +2 more.

list_inboundList inbound emailA
Read-only

List email received on the workspace's inbound domains, newest first.

Inputs: q, limit, offset.

list_templatesList templatesC
Read-only

List stored email templates.

Inputs: limit, offset.

send_batchSend batchA

Send the same email to up to 100 recipients, one email each, with per-recipient variables. All or nothing: if one is rejected, none is sent.

Inputs: batch (required), from, html, text, +2 more.

send_emailSend emailA

Send one email through Postilon. Give subject with html and/or text, or a template_id with variables. A ps_test_ key accepts and reports the email without delivering it.

Inputs: to (required), cc, bcc, from, +8 more.

update_templateUpdate templateB
DestructiveIdempotent

Change a template. Fields left out keep their current value.

Inputs: id (required), name, variables, html_template, +2 more.

verify_domainVerify domainA
Idempotent

Check a domain's DNS records now, and mark it verified once the required ones are found.

Inputs: id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool targets a distinct resource+action pair, and the resource is explicit in the name (email, inbound, template, domain). Overlaps like send_email vs send_batch or get_email vs get_inbound are disambiguated by the descriptions (single vs up to 100 recipients, sent vs received). No two tools appear to do the same thing.

    Naming Consistency5/5

    All 16 tools follow a strict snake_case verb_noun pattern (list_/get_/create_/update_/delete_/send_/cancel_/verify_ + resource). The only slight oddity is send_batch naming the shape rather than the object, but it still reads naturally alongside send_email.

    Tool Count4/5

    16 tools sits at the upper end of comfortable but is justified by four distinct sub-domains (templates, sending, sent-mail inspection, domains, inbound). Each tool maps to a real workflow step, with no filler. Just slightly heavier than ideal.

    Completeness4/5

    Templates have full CRUD, emails cover send/get/list/cancel, and domains cover add/list/get/verify. The notable gap is domain lifecycle teardown (no delete_domain or update_domain), and inbound/email data is read-only, but core transactional workflows have no dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to send transactional email, authenticate sending domains, track delivery, and diagnose deliverability issues programmatically.
      13
      74 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to send transactional emails and manage email infrastructure through the AgentiSend API, including domain verification, budgeted keys, and message logs.
      46
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to send, receive, and track email and manage templates, domains, webhooks, and other email API operations from AI assistants.
      122 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to inspect verified sending domains and submit transactional emails through hosted tool discovery, schema validation, and policy-governed execution using a single gateway API key.
      MIT