postmark-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@postmark-mcp send a welcome email to john@example.com with the subject 'Welcome!'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
postmark-mcp
A FastMCP server that exposes the Postmark API as MCP tools, so an LLM agent can send transactional email and monitor delivery (templates, bounces, outbound messages, stats, and suppressions).
It supports a read-only mode: when enabled, every mutating tool — including all email-sending tools — is hidden from the tool list and cannot be called.
Scope
Server-token (single Postmark server) endpoints only:
Area | Read tools | Write tools |
— |
| |
Templates |
|
|
Bounces |
|
|
Messages |
| — |
Stats |
| — |
Suppressions |
|
|
Account-level admin (servers, domains, sender signatures, webhooks, template push) is out of scope — those require an account token.
Related MCP server: sparkpost-mcp
Run
# Published to PyPI:
uvx postmark-mcp
# Local checkout, before publishing:
uvx --from . postmark-mcpThe server speaks MCP over stdio (the transport MCP clients spawn).
Configuration
All configuration comes from environment variables. The MCP client injects them into the
spawned process via its server config env block.
Env var | Required | Default | Purpose |
| yes | — | Postmark server token (sent as |
| no |
| When truthy ( |
| no |
| API base URL (override for testing) |
| no |
| Per-request timeout, in seconds |
If POSTMARK_SERVER_TOKEN is missing the server exits immediately with an actionable message,
rather than failing on the first tool call.
MCP client config
Add to your client's mcpServers block (e.g. Claude Desktop). Restart the client after editing
env so the server is re-spawned.
{
"mcpServers": {
"postmark": {
"command": "uvx",
"args": ["postmark-mcp"],
"env": {
"POSTMARK_SERVER_TOKEN": "your-server-token",
"POSTMARK_READ_ONLY": "false"
}
}
}
}Set POSTMARK_READ_ONLY to true for a monitoring-only deployment that cannot send email or
change any state.
Development
uv sync --extra dev # install deps (incl. dev tools)
uv run ruff check . # lint
uv run ruff format . # format
uv run pytest # tests (no network — Postmark calls are mocked with respx)
uv run postmark-mcp # run locally (requires POSTMARK_SERVER_TOKEN)Notes
Batch sends return HTTP 200 even when individual messages fail; the batch tools return the raw per-message array so you can inspect each element's
ErrorCode/Message.Postmark errors are surfaced as the tool error message; unexpected internal errors are masked (
mask_error_details=True) to avoid leaking details.Built for FastMCP 3.x (read-only filtering uses
mcp.disable(tags={"write"})).
Available Tools
28 toolsactivate_bounceActivate BounceAIdempotent
Reactivate a deactivated address tied to a bounce. BLOCKED in read-only mode.
Inputs: bounce_id (required). Returns: object
create_suppressionsCreate SuppressionsA
Add up to 50 addresses to a stream's suppression list. BLOCKED in read-only mode.
Inputs: email_addresses (required), stream_id. Returns: object
create_templateCreate TemplateA
Create a new template or layout. BLOCKED in read-only mode.
Provide at least one of html_body or text_body.
Inputs: name (required), alias, subject, html_body, +3 more. Returns: object
delete_suppressionsDelete SuppressionsADestructive
Remove up to 50 addresses from a stream's suppression list (reactivate them).
SpamComplaint suppressions cannot be deleted. BLOCKED in read-only mode.
Inputs: email_addresses (required), stream_id. Returns: object
delete_templateDelete TemplateADestructive
Permanently delete a template by ID or alias. BLOCKED in read-only mode.
Inputs: template_id_or_alias (required). Returns: object
edit_templateEdit TemplateADestructive
Update an existing template. Only provided fields change. BLOCKED in read-only mode.
Inputs: template_id_or_alias (required), name, alias, subject, +3 more. Returns: object
get_bounceGet BounceARead-onlyIdempotent
Get the full detail record for a single bounce.
Inputs: bounce_id (required). Returns: object
get_bounce_countsGet Bounce CountsBRead-onlyIdempotent
Get counts of bounced emails, broken down by bounce type.
Inputs: tag, todate, fromdate, messagestream. Returns: object
get_bounce_dumpGet Bounce DumpARead-onlyIdempotent
Get the raw SMTP source/dump of a single bounce.
Inputs: bounce_id (required). Returns: object
get_click_countsGet Click CountsARead-onlyIdempotent
Get counts of unique link clicks (requires link tracking).
Inputs: tag, todate, fromdate, messagestream. Returns: object
get_delivery_statsGet Delivery StatsARead-onlyIdempotent
Get aggregate delivery statistics, including a per-type bounce breakdown.
Inputs: no named parameters. Returns: object
get_open_countsGet Open CountsARead-onlyIdempotent
Get counts of recipients who opened emails (requires open tracking).
Inputs: tag, todate, fromdate, messagestream. Returns: object
get_outbound_message_detailsGet Outbound Message DetailsARead-onlyIdempotent
Get full detail for one outbound message, including body and message events.
Inputs: message_id (required). Returns: object
get_outbound_overviewGet Outbound OverviewBRead-onlyIdempotent
Get a brief overview of statistics for all outbound email.
Inputs: tag, todate, fromdate, messagestream. Returns: object
get_sent_countsGet Sent CountsARead-onlyIdempotent
Get the total count of sent emails, optionally bucketed over time.
Inputs: tag, todate, fromdate, messagestream. Returns: object
get_spam_countsGet Spam Complaint CountsBRead-onlyIdempotent
Get the count of recipients who marked email as spam.
Inputs: tag, todate, fromdate, messagestream. Returns: object
get_templateGet TemplateARead-onlyIdempotent
Fetch a single template's full details by ID or alias.
Inputs: template_id_or_alias (required). Returns: object
list_bouncesList BouncesARead-onlyIdempotent
Search bounces with optional filters (paginated; up to 10,000 results).
Inputs: tag, count, offset, todate, +6 more. Returns: object
list_suppressionsList SuppressionsARead-onlyIdempotent
List suppressions for a message stream, with optional filters.
Inputs: origin, todate, fromdate, stream_id, +2 more. Returns: object
list_templatesList TemplatesARead-onlyIdempotent
List templates and layouts on the server (paginated).
Inputs: count, offset, template_type, layout_template. Returns: object
search_message_clicksSearch Message ClicksARead-onlyIdempotent
Search link click events across outbound messages (requires link tracking).
Inputs: tag, count, offset, recipient, +1 more. Returns: object
search_message_opensSearch Message OpensARead-onlyIdempotent
Search email open events across outbound messages (requires open tracking).
Inputs: tag, count, offset, recipient, +1 more. Returns: object
search_outbound_messagesSearch Outbound MessagesARead-onlyIdempotent
Search outbound messages with optional filters (paginated; up to 10,000 results).
Inputs: tag, count, offset, status, +6 more. Returns: object
send_emailSend EmailADestructive
Send a single email with content supplied directly.
Requires html_body and/or text_body. BLOCKED in read-only mode.
Inputs: to (required), subject (required), from_email (required), cc, +10 more. Returns: object
send_email_batchSend Email BatchADestructive
Send up to 500 individually-composed emails in one request.
Returns one result per message; Postmark returns HTTP 200 even when individual messages fail, so inspect each element's ErrorCode/Message. BLOCKED in read-only mode.
Inputs: messages (required). Returns: result
send_email_batch_with_templatesSend Email Batch With TemplatesADestructive
Send up to 500 template-rendered emails in one request.
Returns one result per message (inspect each element's ErrorCode/Message). BLOCKED in read-only mode.
Inputs: messages (required). Returns: result
send_email_with_templateSend Email With TemplateADestructive
Send a single email rendered from a stored template.
Provide exactly one of template_id or template_alias. The subject comes from the template. BLOCKED in read-only mode.
Inputs: to (required), from_email (required), template_model (required), cc, +11 more. Returns: object
validate_templateValidate TemplateARead-onlyIdempotent
Validate and render-preview template content. Persists nothing (safe to run).
Provide at least one of subject, html_body, or text_body.
Inputs: subject, html_body, text_body, template_type, +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tools have clear, distinct purposes. The main ambiguity is among statistics tools: get_delivery_stats and get_outbound_overview both provide aggregate overviews, and get_bounce_counts overlaps with the bounce breakdown in get_delivery_stats.
All tool names follow a consistent verb_noun pattern in snake_case. Retrieval operations consistently use get_ for single items and list_ for collections, while action verbs like send, create, edit, delete, activate, validate, and search are used appropriately throughout.
At 28 tools, this server exceeds the recommended range, feeling heavy and somewhat redundant. The statistics surface alone accounts for 7 tools with overlapping functionalities, which could be consolidated.
The tool set provides comprehensive coverage of Postmark's email capabilities, including sending, templates, suppressions, bounces, and outbound message tracking. CRUD operations are present where applicable, and the inclusion of search and validation tools ensures agents can fully manage the email lifecycle.
Related MCP Connectors
Send, track, and manage transactional and bulk email delivery
Send transactional email over a verified domain — templates, attachments, custom headers.
Send transactional email and check delivery: bounces, suppressions, per-provider stats.
Send transactional email, run campaigns, manage contacts and automations, audit deliverability.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables sending and managing emails via Postmark, including email delivery with templates, template listing, and delivery statistics.MIT
- AlicenseBqualityDmaintenanceEnables sending transactional emails, managing templates, suppression lists, sending domains, webhooks, subaccounts, and retrieving account metrics via the SparkPost API.20356 npmMIT
- AlicenseAqualityBmaintenanceEnables AI agents to send transactional email, authenticate sending domains, track delivery, and diagnose deliverability issues programmatically.1361 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables sending transactional emails individually or in batches, checking delivery status, and monitoring domain email reputation metrics. It supports email tracking with tags and custom metadata.MIT