Skip to main content
Glama

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

Email

—

send_email, send_email_batch, send_email_with_template, send_email_batch_with_templates

Templates

list_templates, get_template, validate_template

create_template, edit_template, delete_template

Bounces

get_delivery_stats, list_bounces, get_bounce, get_bounce_dump

activate_bounce

Messages

search_outbound_messages, get_outbound_message_details, search_message_opens, search_message_clicks

—

Stats

get_outbound_overview, get_sent_counts, get_bounce_counts, get_spam_counts, get_open_counts, get_click_counts

—

Suppressions

list_suppressions

create_suppressions, delete_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-mcp

The 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

POSTMARK_SERVER_TOKEN

yes

—

Postmark server token (sent as X-Postmark-Server-Token)

POSTMARK_READ_ONLY

no

false

When truthy (1/true/yes/on), hide and block all write tools, including sending email

POSTMARK_BASE_URL

no

https://api.postmarkapp.com

API base URL (override for testing)

POSTMARK_TIMEOUT

no

30

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 tools
activate_bounceActivate BounceA
Idempotent

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 SuppressionsA
Destructive

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 TemplateA
Destructive

Permanently delete a template by ID or alias. BLOCKED in read-only mode.

Inputs: template_id_or_alias (required). Returns: object

edit_templateEdit TemplateA
Destructive

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 BounceA
Read-onlyIdempotent

Get the full detail record for a single bounce.

Inputs: bounce_id (required). Returns: object

get_bounce_countsGet Bounce CountsB
Read-onlyIdempotent

Get counts of bounced emails, broken down by bounce type.

Inputs: tag, todate, fromdate, messagestream. Returns: object

get_bounce_dumpGet Bounce DumpA
Read-onlyIdempotent

Get the raw SMTP source/dump of a single bounce.

Inputs: bounce_id (required). Returns: object

get_click_countsGet Click CountsA
Read-onlyIdempotent

Get counts of unique link clicks (requires link tracking).

Inputs: tag, todate, fromdate, messagestream. Returns: object

get_delivery_statsGet Delivery StatsA
Read-onlyIdempotent

Get aggregate delivery statistics, including a per-type bounce breakdown.

Inputs: no named parameters. Returns: object

get_open_countsGet Open CountsA
Read-onlyIdempotent

Get counts of recipients who opened emails (requires open tracking).

Inputs: tag, todate, fromdate, messagestream. Returns: object

get_outbound_message_detailsGet Outbound Message DetailsA
Read-onlyIdempotent

Get full detail for one outbound message, including body and message events.

Inputs: message_id (required). Returns: object

get_outbound_overviewGet Outbound OverviewB
Read-onlyIdempotent

Get a brief overview of statistics for all outbound email.

Inputs: tag, todate, fromdate, messagestream. Returns: object

get_sent_countsGet Sent CountsA
Read-onlyIdempotent

Get the total count of sent emails, optionally bucketed over time.

Inputs: tag, todate, fromdate, messagestream. Returns: object

get_spam_countsGet Spam Complaint CountsB
Read-onlyIdempotent

Get the count of recipients who marked email as spam.

Inputs: tag, todate, fromdate, messagestream. Returns: object

get_templateGet TemplateA
Read-onlyIdempotent

Fetch a single template's full details by ID or alias.

Inputs: template_id_or_alias (required). Returns: object

list_bouncesList BouncesA
Read-onlyIdempotent

Search bounces with optional filters (paginated; up to 10,000 results).

Inputs: tag, count, offset, todate, +6 more. Returns: object

list_suppressionsList SuppressionsA
Read-onlyIdempotent

List suppressions for a message stream, with optional filters.

Inputs: origin, todate, fromdate, stream_id, +2 more. Returns: object

list_templatesList TemplatesA
Read-onlyIdempotent

List templates and layouts on the server (paginated).

Inputs: count, offset, template_type, layout_template. Returns: object

search_message_clicksSearch Message ClicksA
Read-onlyIdempotent

Search link click events across outbound messages (requires link tracking).

Inputs: tag, count, offset, recipient, +1 more. Returns: object

search_message_opensSearch Message OpensA
Read-onlyIdempotent

Search email open events across outbound messages (requires open tracking).

Inputs: tag, count, offset, recipient, +1 more. Returns: object

search_outbound_messagesSearch Outbound MessagesA
Read-onlyIdempotent

Search outbound messages with optional filters (paginated; up to 10,000 results).

Inputs: tag, count, offset, status, +6 more. Returns: object

send_emailSend EmailA
Destructive

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 BatchA
Destructive

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 TemplatesA
Destructive

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 TemplateA
Destructive

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 TemplateA
Read-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

    A3.7/5.0

    Scored across 28 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables sending and managing emails via Postmark, including email delivery with templates, template listing, and delivery statistics.
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables sending transactional emails, managing templates, suppression lists, sending domains, webhooks, subaccounts, and retrieving account metrics via the SparkPost API.
      20
      356 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to send transactional email, authenticate sending domains, track delivery, and diagnose deliverability issues programmatically.
      13
      61 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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