# postmark-mcp

A [FastMCP](https://gofastmcp.com) server that exposes the
[Postmark API](https://postmarkapp.com/developer/api/overview) 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.

## Run

```bash
# 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.

```json
{
  "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

```bash
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"})`).