# Postmark MCP

> Postmark MCP Server lets your AI client manage all outbound communication tasks in one chat session. Send emails using pre-built templates, retrieve raw SMTP logs for bounce failures, track delivery statistics across massive volumes, and list spam complaints—all without opening a dashboard.

## Overview
- **Category:** communication-messaging
- **Price:** Free
- **Tags:** transactional-email, smtp-delivery, email-templates, bounce-tracking, email-api, delivery-metrics

## Description

Your AI client handles every outbound comms task, so you don't gotta open a dashboard or copy-paste anything. This server gives your agent direct access to Postmark—you can send emails, debug bounce failures down to the SMTP level, track total delivery metrics, and even manage all your templates, all from one chat session.

### Dispatching Emails
When you need to blast out messages, your AI client uses dedicated tools. If it's a quick shot in the dark—like a simple plain text or basic HTML notice—it hits **`send_email`**. But if you gotta send something structured that needs to look right every time (think password resets or invoices), you use **`send_with_template`** with a specific template ID. This guarantees consistent formatting and makes sure all the necessary variables get populated correctly.

### Diagnosing Failures & Bounces
If an email bounces, you don't just wanna know *that* it bounced; you wanna know *why*. The client first runs **`list_bounces`** to give a summary count and category of recent failures. If that summary isn't enough, the agent pulls the raw data using **`get_bounce_logs`**. This gives you the full SMTP log for that specific failure event, letting you pinpoint rejection codes—whether it was a DNS timeout or something else dirty. You can also check out your spam risk by running **`list_spam_complaints`** to see what people are complaining about against your sending domain.

### Monitoring Sending Health
Need to know if your mailing efforts are working? The agent pulls operational data with **`get_delivery_stats`**. This single call gives you comprehensive metrics, like open rates and the total bytes sent across your server history. You can also check out the core setup anytime by running **`get_server_config`** to display the active configuration details for your Postmark instance.

### Managing Templates & Settings
Your AI client lets you manage system assets without touching a settings page. Want to see what templates you have? Use **`list_templates`**. Need to clean house and delete an old template? You run **`delete_template`** with the ID. If you gotta change core details, like updating the sender name or other server specifics, you use **`update_server_config`**. All these tools keep your outbound communication workflow contained right here in the chat.

### Quick Reference of What It Does
*   **Send Messages:** You can send plain text/HTML using `send_email`, or guarantee structure with `send_with_template`. 
*   **Check Bounces:** Get a quick count via `list_bounces`, then drill down to the raw rejection codes using **`get_bounce_logs`**. 
*   **Track Success:** Pull operational metrics like open rates and total bytes sent by running **`get_delivery_stats`**. 
*   **Audit Spam & Assets:** See recent complaints with `list_spam_complaints`, list existing templates with `list_templates`, or remove old ones using `delete_template`. 
*   **Control Settings:** Read your current setup details with `get_server_config`, and change core settings like the sender name by running **`update_server_config`**.

## Tools

### delete_template
Removes a specified email template from your Postmark account.

### get_bounce_logs
Retrieves the raw SMTP logs for a specific failed bounce event, detailing rejection codes.

### get_delivery_stats
Pulls current operational metrics, such as open rates and total bytes sent, across your server history.

### get_server_config
Displays the active configuration details for your Postmark server instance.

### list_bounces
Lists a summary of recent email bounces, allowing you to count and categorize failed deliveries.

### list_spam_complaints
Retrieves a record of recent spam complaints against your sending domain.

### list_templates
Shows a full list of all active email templates stored on the server.

### send_email
Sends a basic, non-templated HTML or plain text message immediately.

### send_with_template
Sends an email using a specific template ID, ensuring consistent formatting and required variables are populated.

### update_server_config
Changes the configured sender name or other core server details.

## Prompt Examples

**Prompt:** 
```
Can you check if we had any hard bounces yesterday, and tell me why?
```

**Response:** 
```
I checked `list_bounces`. You had exactly 2 hard bounces related to the `@test.local` domain. Fetching `get_bounce_logs` for UUID `192...`, the upstream MTA rejected it throwing a `550 5.1.1 User Unknown` SMTP code. The inbox genuinely doesn't exist.
```

**Prompt:** 
```
List all active Postmark templates, then delete the one clearly named 'Legacy Promo'.
```

**Response:** 
```
Listing your templates... Found 5 active. I have identified 'Legacy Promo' mapped to `template_id` 89321. I'm now invoking `delete_template` on 89321. The layout has been completely purged from your Postmark server.
```

**Prompt:** 
```
Send a welcome email through Postmark using template ID `10101` to `user@example.com`.
```

**Response:** 
```
Dispatched gracefully using `send_with_template`. Postmark accepted the request to route template `10101` towards `user@example.com` specifying the sender address `admin@yourdomain.com`. It resolved via message UUID `abc-123`.
```

## Capabilities

### Dispatch Emails
Send plain text or HTML emails using either general content via `send_email` or structured templates via `send_with_template`.

### Analyze Delivery Failures
Retrieves raw SMTP logs (`get_bounce_logs`) and lists recent bounces (`list_bounces`) to diagnose the exact technical cause of a failed message.

### Monitor Sending Health
Gathers comprehensive operational data, including open rates and total bytes sent, using `get_delivery_stats`.

### Audit Spam & Templates
Lists recent spam complaints (`list_spam_complaints`) and manages your assets by listing or deleting templates (`list_templates`, `delete_template`).

### Control Server Settings
Reads current server settings with `get_server_config` or updates the sender name using `update_server_config`.

## Use Cases

### Handling a Hard Bounce Report
A support agent gets a ticket: 'My invoice email bounced.' Instead of asking the user for a UUID and searching through logs, the agent runs `list_bounces` to narrow down the date, then executes `get_bounce_logs`. The AI reads the resulting SMTP code (e.g., 550 User Unknown) and tells the support team exactly that the recipient's inbox doesn't exist.

### Running a QA Test Cycle
A QA tester needs to verify five different email flows. They first run `list_templates` to get all available IDs, then loop through them using `send_with_template` for each one to ensure the correct variables populate and that delivery metrics are recorded via `get_delivery_stats`.

### Pre-deployment Audit
A backend engineer is about to launch a new service. They first run `list_spam_complaints` to check for any existing reputation issues, then use `get_server_config` to verify the current sender name, and finally update it using `update_server_config` before going live.

### Debugging Mass Failure
The system reports a 10% drop in delivery. The agent runs `list_bounces`, notices a cluster of failures from a specific domain, and immediately uses `get_bounce_logs` to pinpoint the failure reason—a clear rate limit hit by an upstream MTA.

## Benefits

- Stop manually cross-referencing dashboards. When an email fails, simply ask your agent to run `get_bounce_logs` and it delivers the raw SMTP trace directly, telling you if the issue is a DNS timeout or a user error.
- Maintain brand consistency effortlessly. Use `send_with_template` to dispatch messages that pull from pre-approved layouts, guaranteeing every email looks right without needing manual HTML edits.
- Stay ahead of spam filters by monitoring complaints. Running `list_spam_complaints` gives you a direct count and list of recent flags, helping pinpoint content issues before they cause major delivery dips.
- Track volume and performance metrics instantly. The `get_delivery_stats` tool pulls operational data like open rates and physical bytes sent, giving you high-level health checks without leaving your workflow.
- Manage system assets on the fly. Need to clean up? Use `list_templates` followed by `delete_template` to purge outdated layouts when migrating services.

## How It Works

The bottom line is, you get immediate, actionable insights into your email program's health without leaving your chat interface.

1. Subscribe to this server and provide your Postmark Server Token.
2. Reference the required action in your chat (e.g., 'Check bounces for yesterday').
3. The AI client executes the necessary tool calls (`list_bounces`, `get_bounce_logs`) and returns a plain-language summary of the data.

## Frequently Asked Questions

**How do I check bounce history using list_bounces?**
You ask the agent to run `list_bounces`. It pulls a summary of recent failures, letting you count how many bounces occurred and giving you enough context (like domain names) to know where to look next.

**What is the best way to send emails with send_with_template?**
To use it, you must provide the specific template ID. The agent handles the rest by dispatching the email and populating all necessary variables using that single tool call.

**Can I check spam complaints with list_spam_complaints?**
Yes. Running `list_spam_complaints` retrieves a record of recent flags against your sending domain, giving you immediate visibility into reputation risks.

**How do I get the raw error codes using get_bounce_logs?**
You must provide the specific UUID of the bounce. The agent then runs `get_bounce_logs` and delivers the full, technical SMTP trace, which is key for debugging.

**How do I check overall delivery performance using get_delivery_stats?**
The `get_delivery_stats` tool provides a real-time overview of your server's health. It pulls metrics like total bytes sent, open rates, and volume statistics for the reporting period.

**What is the best practice for removing old email templates using delete_template?**
First, use `list_templates` to get all existing template IDs. Then, invoke `delete_template` with the specific ID of any layout you want permanently removed from your server.

**When should I use send_email instead of sending through a template?**
Use `send_email` when you need to dispatch simple plain text or basic HTML content without requiring complex variable mapping. It's for quick, non-templated messages.

**How do I verify my account details and webhook setup using get_server_config?**
`get_server_config` pulls all current server settings, letting you see things like active webhooks or configured domain names. It’s a quick check before making changes.

**Can the AI send emails dynamically using my existing templates?**
Yes. Using `send_with_template`, you merely tell the AI the template ID and the JSON parameters (Template Model). It perfectly injects the data into your Postmark layouts.

**Is it possible to debug a complex email bounce natively inside Claude?**
Absolutely. First command `list_bounces` to find failing message UUIDs. Then ask the agent to run `get_bounce_logs` on that UUID—it will interpret the pure SMTP error code for you naturally.

**Which Postmark token should I use?**
This MCP server uses the Postmark Server Token. Each Server in Postmark functions as an isolated environment (e.g. Production Server vs Staging Server).