![\"Add](\"https://img.shields.io/badge/Add_Postmark_MCP_Server-to_Cursor-00A4DB?style=for-the-badge&logo=cursor&logoColor=white\"){kind=icon}
\n \n\n \nDon't forget our team meeting tomorrow at 2 PM.
\",\n \"from\": \"sender@example.com\",\n \"cc\": \"manager@example.com\",\n \"bcc\": \"archive@example.com\",\n \"replyTo\": \"support@example.com\",\n \"tag\": \"meetings\"\n}\n```\n\n`to` accepts a single address or an array of up to 50 addresses. `htmlBody`, `from`, `cc`, `bcc`, `replyTo`, and `tag` are optional. If `from` is omitted, `DEFAULT_SENDER_EMAIL` is used.\n\n**Response:**\n```\nEmail sent successfully!\nMessageID: 0a1b2c3d-...\nTo: recipient@example.com\nSubject: Meeting Reminder\n```\n\n### sendEmailWithTemplate\nSends an email using a Postmark template.\n\n**Example Prompt:**\n```\nSend the \"welcome\" template to customer@example.com with name \"John Doe\" and login_url \"https://myapp.com/login\".\n```\n\n**Expected Payload:**\n```json\n{\n \"to\": \"customer@example.com\",\n \"templateAlias\": \"welcome\",\n \"templateModel\": {\n \"name\": \"John Doe\",\n \"login_url\": \"https://myapp.com/login\"\n },\n \"from\": \"sender@example.com\",\n \"tag\": \"onboarding\"\n}\n```\n\nProvide **either** `templateId` (number) **or** `templateAlias` (string), not both.\n\n**Response:**\n```\nTemplate email sent successfully!\nMessageID: 0a1b2c3d-...\nTo: customer@example.com\nTemplate: welcome\n```\n\n### sendBatch\nSends up to 500 emails in a single API call. Each message is fully independent β its own recipient, subject, and body. This wraps Postmark's *synchronous* batch endpoint (`POST /email/batch`), which returns immediate per-message results.\n\n> **Note:** Postmark also offers an asynchronous [bulk email API](https://postmarkapp.com/developer/api/bulk-email) (`POST /email/bulk`) for large-volume jobs with no message-count cap and a 50 MB payload limit. That endpoint uses a submit-and-poll workflow and is not currently wrapped by this MCP server.\n\n**Expected Payload:**\n```json\n{\n \"messages\": [\n {\n \"to\": \"alice@example.com\",\n \"subject\": \"Order #1234 confirmed\",\n \"textBody\": \"Thanks Alice β your order is on its way.\",\n \"tag\": \"order-confirmation\"\n },\n {\n \"to\": \"bob@example.com\",\n \"subject\": \"Order #1235 confirmed\",\n \"textBody\": \"Thanks Bob β your order is on its way.\",\n \"tag\": \"order-confirmation\"\n }\n ]\n}\n```\n\nPer-message fields: `to`, `subject`, `textBody` are required. `htmlBody`, `from`, `cc`, `bcc`, `replyTo`, and `tag` are optional. If `from` is omitted on a message, `DEFAULT_SENDER_EMAIL` is used.\n\n**Response:**\n```\nSent 2/2 successfully\n\nSuccesses:\n - alice@example.com β abc-123-def\n - bob@example.com β abc-456-ghi\n```\n\nWhen some messages fail at submission (e.g., suppressed recipients), failures are listed first with their `ErrorCode` and reason:\n```\nSent 8/10 successfully (2 failed)\n\nFailures:\n - blocked@example.com β 406: Address has been suppressed.\n - bad@example.com β 300: Inactive recipient\n...\n```\n\n### sendBatchWithTemplate\nSends up to 500 templated emails β same template, per-recipient template models. Ideal for \"render this onboarding template for each new user\" flows.\n\n**Expected Payload:**\n```json\n{\n \"templateAlias\": \"welcome\",\n \"from\": \"hello@yourapp.com\",\n \"tag\": \"onboarding\",\n \"recipients\": [\n { \"to\": \"alice@example.com\", \"templateModel\": { \"name\": \"Alice\", \"plan\": \"Pro\" } },\n { \"to\": \"bob@example.com\", \"templateModel\": { \"name\": \"Bob\", \"plan\": \"Free\" } }\n ]\n}\n```\n\nProvide **either** `templateId` (number) **or** `templateAlias` (string). Top-level `from` and `tag` apply to all recipients but can be overridden per-recipient. Each recipient also accepts optional `cc`, `bcc`, and `replyTo`.\n\n**Response:** same format as `sendBatch`.\n\n---\n\n## Templates\n\n### listTemplates\nLists saved templates on this server. Returns the first 100 templates; if a server has more than 100, pagination is not yet supported and the response will indicate that results are truncated.\n\n**Response:**\n```\nFound 2 templates:\n\nβ’ **Welcome**\n - ID: 12345678\n - Alias: welcome\n - Subject: Welcome to {{product_name}}\n```\n\n### getTemplate\nRetrieves a single template's full content (HTML body, text body, subject, type).\n\n**Payload:** `{ \"templateIdOrAlias\": \"welcome\" }` β accepts numeric ID or string alias.\n\n### createTemplate\nCreates a new template. Requires `name`. At least one of `htmlBody` or `textBody` must be provided.\n\n`subject` is required for Standard templates and must be **omitted** for Layout templates β Postmark rejects the field on Layouts.\n\n`layoutTemplate` (Standard only) binds the new template to an existing Layout by alias. Without it, the new template renders unwrapped (no chrome from any layout).\n\n**Expected Payload:**\n```json\n{\n \"name\": \"Order Confirmation\",\n \"subject\": \"Your order #{{order_id}} is confirmed\",\n \"htmlBody\": \"Thanks {{name}}
\",\n \"textBody\": \"Thanks {{name}}\",\n \"testRenderModel\": { \"order_id\": 42, \"name\": \"John\" },\n \"templateType\": \"Standard\"\n}\n```\n\n---\n\n## Messages\n\n### searchOutboundMessages\nSearches the outbound message history.\n\n**Expected Payload (all filters optional):**\n```json\n{\n \"recipient\": \"user@example.com\",\n \"fromEmail\": \"sender@example.com\",\n \"tag\": \"marketing\",\n \"subject\": \"Welcome\",\n \"status\": \"sent\",\n \"messageStream\": \"outbound\",\n \"fromDate\": \"2025-05-01\",\n \"toDate\": \"2025-05-15\",\n \"count\": 50,\n \"offset\": 0\n}\n```\n\n`status` is one of `queued`, `sent`, `processed`. `count` is 1β500 (default 50).\n\n### getMessageDetails\nRetrieves full details and event timeline for a single outbound message.\n\n**Payload:** `{ \"messageId\": \"0a1b2c3d-...\" }`\n\n---\n\n## Diagnostics\n\n### diagnoseDelivery\nComposite triage tool. Answers \"did my email reach X, and if not, why?\" by running message search, suppression check, and bounce history lookups in parallel against a recipient address, then synthesizing a plain-English recommendation.\n\nThis is a **diagnostic** tool: it composes multiple Postmark API calls into a single coherent answer rather than mirroring a single endpoint.\n\n**Example Prompt:**\n```\nDid my email to recipient@example.com get delivered? If not, what should I do?\n```\n\n**Expected Payload:**\n```json\n{\n \"recipient\": \"recipient@example.com\",\n \"messageId\": \"0a1b2c3d-...\",\n \"fromDate\": \"2026-04-21\",\n \"toDate\": \"2026-04-28\",\n \"messageStream\": \"outbound\"\n}\n```\n\nAll fields except `recipient` are optional. If `messageId` is omitted, the most recent message to the recipient is used. The default search window is the last 7 days.\n\n**Sample response:**\n```\nDelivery Diagnosis: recipient@example.com\nββββββββββββββββββββββββββββββββββββββββββββββββ\n\nSuppression: not suppressed on stream \"outbound\"\n\nMost recent message:\n MessageID: fadeae4e-fb04-4102-9303-9876078c7b81\n Subject: Welcome to MyApp\n Sent: 2026-04-27T18:42:19.0000000-04:00\n Status: Sent\n Events: Delivered, OpenedΓ2, Clicked\n\nBounce history: none\n\nRecommended action:\n Email was delivered. If recipient says they didn't see it, check their\n spam folder or ask them to whitelist the sender domain.\n```\n\nWhen the recipient is suppressed, the recommendation differs based on reason: `SpamComplaint` is permanent, `HardBounce` may be reactivatable, `ManualSuppression` can be deleted via `deleteSuppressions`.\n\n---\n\n## Bounces\n\n### searchBounces\nSearches the bounce log with optional filters by type, recipient, tag, message ID, message stream, date range, and active/inactive status.\n\n**Expected Payload (all optional):**\n```json\n{\n \"type\": \"HardBounce\",\n \"inactive\": true,\n \"emailFilter\": \"@example.com\",\n \"tag\": \"marketing\",\n \"messageID\": \"0a1b2c3d-...\",\n \"messageStream\": \"outbound\",\n \"fromDate\": \"2025-05-01\",\n \"toDate\": \"2025-05-15\",\n \"count\": 50,\n \"offset\": 0\n}\n```\n\nSupported `type` values (matches Postmark's `BounceType` enum β 22 values): `AddressChange`, `AutoResponder`, `BadEmailAddress`, `Blocked`, `ChallengeVerification`, `DMARCPolicy`, `DnsError`, `HardBounce`, `InboundError`, `ManuallyDeactivated`, `OpenRelayTest`, `SMTPApiError`, `SoftBounce`, `SpamComplaint`, `SpamNotification`, `Subscribe`, `TemplateRenderingFailed`, `Transient`, `Unconfirmed`, `Unknown`, `Unsubscribe`, `VirusNotification`.\n\n### getBounceDump\nReturns the raw SMTP dump for a bounce. Bounce dumps are retained for 30 days.\n\n**Payload:** `{ \"bounceId\": 123456 }`\n\n### activateBounce\nReactivates a deactivated email address (only bounces where `CanActivate: true`).\n\n**Payload:** `{ \"bounceId\": 123456 }`\n\n---\n\n## Suppressions\n\n### listSuppressions\nLists suppressions for a message stream.\n\n**Expected Payload (all optional):**\n```json\n{\n \"messageStream\": \"outbound\",\n \"suppressionReason\": \"HardBounce\",\n \"origin\": \"Recipient\",\n \"emailAddress\": \"user@example.com\",\n \"fromDate\": \"2025-05-01\",\n \"toDate\": \"2025-05-15\"\n}\n```\n\n`suppressionReason` β `HardBounce`, `SpamComplaint`, `ManualSuppression`. `origin` β `Recipient`, `Customer`, `Admin`. If `messageStream` is omitted, `DEFAULT_MESSAGE_STREAM` is used.\n\n### createSuppressions\nSuppresses up to 50 email addresses on a message stream.\n\n**Payload:** `{ \"emailAddresses\": [\"a@example.com\", \"b@example.com\"], \"messageStream\": \"outbound\" }`\n\n### deleteSuppressions\nRemoves up to 50 addresses from the suppression list. Note: `SpamComplaint` suppressions cannot be deleted.\n\n**Payload:** `{ \"emailAddresses\": [\"a@example.com\"], \"messageStream\": \"outbound\" }`\n\n---\n\n## Stats & Server\n\n### getDeliveryStats\nUnified stats tool. Default behavior returns a friendly headline summary; pass an optional `stat` for a focused breakdown.\n\n**Expected Payload (all optional):**\n```json\n{\n \"stat\": \"summary\",\n \"tag\": \"marketing\",\n \"fromDate\": \"2025-05-01\",\n \"toDate\": \"2025-05-15\",\n \"messageStream\": \"outbound\"\n}\n```\n\nSupported `stat` values:\n\n| `stat` | What it returns |\n|---|---|\n| `summary` *(default)* | Headline open / click / bounce / spam rates |\n| `overview` | All overview counts (sent, tracked, opens, clicks, bounces, β¦) |\n| `sent` | Sent count |\n| `bounces` | Bounce breakdown by type |\n| `spam` | Spam complaint count |\n| `tracked` | Tracked email count |\n| `opens` | Total + unique opens |\n| `openPlatforms` | Open platform breakdown (Desktop / Mobile / WebMail / Unknown) |\n| `openClients` | Top 10 email clients (Apple Mail, Gmail, β¦) |\n| `openReadTimes` | Read-time histogram |\n| `clicks` | Total + unique link clicks |\n| `clickBrowsers` | Top 10 browsers used to click |\n| `clickPlatforms` | Click platform breakdown (Desktop / Mobile / WebMail / Unknown) |\n| `clickLocation` | HTML vs. plain-text click location |\n\n**Default summary response:**\n```\nEmail Delivery Summary\n\nSent: 74\nTracked: 33 (44.6% of sent)\nOpen rate: 93.9% (31/33 unique opens)\nClick rate: 4.8% (10/207 unique links clicked)\nBounced: 1 (1.4%)\nSpam: 0 (0.0%)\n\nPeriod: 2025-05-01 β 2025-05-15\nTag: marketing\n```\n\n**Sample `stat: \"openPlatforms\"` response:**\n```\nOpen Platform Usage\n\n Desktop 20 (64.5%)\n Mobile 0 (0.0%)\n WebMail 11 (35.5%)\n Unknown 0 (0.0%)\n```\n\n### getServerInfo\nReturns the Postmark server's name, color, tracking settings, and webhook URLs.\n\n**Payload:** `{}`\n\n---\n\n## Webhooks\n\n### listWebhooks\nLists configured webhooks. Optional `messageStream` filter.\n\n### createWebhook\nCreates a webhook subscription. Requires a `url` and **at least one** trigger.\n\n**Security note:** Webhooks are persistent β once registered, Postmark will POST event data (opens, clicks, bounces, spam complaints, etc.) to the target URL for all future matching events on that server, until the webhook is deleted. Only register webhooks pointing to URLs you control. Use `WEBHOOK_URL_ALLOWLIST` to restrict accepted URLs to known prefixes.\n\nThe `url` must use **HTTPS**. HTTP URLs are rejected. If `WEBHOOK_URL_ALLOWLIST` is set, the URL must also match one of the configured prefixes.\n\n**Expected Payload:**\n```json\n{\n \"url\": \"https://hooks.yourapp.com/postmark\",\n \"messageStream\": \"outbound\",\n \"openEnabled\": true,\n \"clickEnabled\": true,\n \"deliveryEnabled\": false,\n \"bounceEnabled\": true,\n \"spamComplaintEnabled\": true,\n \"subscriptionChangeEnabled\": false\n}\n```\n\n### deleteWebhook\nDeletes a webhook by ID.\n\n**Payload:** `{ \"webhookId\": 1234567 }`\n\n## Implementation Details\n### API Request Headers\nAll requests to the Postmark API include the following headers for client identification:\n\n| Header | Description |\n|---|---|\n| `X-Postmark-Client` | Always `postmark-mcp` β identifies this server as the request origin |\n| `X-Postmark-Client-Version` | Version of this MCP server, matching the package version |\n| `X-Postmark-MCP-Client` | Name and version of the MCP host application (e.g., `claude-desktop/1.0`), captured from the MCP `initialize` handshake. Omitted if the client does not provide this information. |\n| `X-Agent-Label` | Value of the `AGENT_LABEL` environment variable. Omitted when not set. |\n\nThis server uses its own HTTP client (no postmark npm package) so that MCP traffic is identifiable as `postmark-mcp` in Postmark logs and support tickets.\n\n### Automatic Configuration\nAll emails are automatically configured with:\n- `TrackOpens: true`\n- `TrackLinks: \"HtmlAndText\"`\n- Message stream from `DEFAULT_MESSAGE_STREAM` environment variable\n\n### Error Handling\nThe server implements comprehensive error handling:\n- Validation of all required environment variables\n- Graceful shutdown on SIGTERM and SIGINT\n- Proper error handling for API calls\n- No exposure of sensitive information in logs\n- Consistent error message formatting\n\n### Logging\nEvery tool invocation emits a structured JSON line to **stderr**. If `LOG_FILE` is set, the same line is also appended to that file.\n\n**Log entry shape:**\n```json\n{\n \"timestamp\": \"2026-06-16T20:34:01.123Z\",\n \"tool\": \"sendEmail\",\n \"clientName\": \"claude-desktop\",\n \"clientVersion\": \"1.0\",\n \"args\": {\n \"to\": \"u**r@example.com\",\n \"subject\": \"Meeting Reminder\",\n \"textBody\": \"[312ch]\"\n },\n \"status\": \"ok\",\n \"durationMs\": 243\n}\n```\n\nOn error, `status` is `\"error\"` and an `error` field contains the message.\n\n**What is and isn't logged:**\n\n| Data | Logged as |\n|---|---|\n| Email addresses | Partially masked: `u**r@example.com` (set `LOG_EMAIL_FULL=true` to disable) |\n| `htmlBody` / `textBody` | Byte count only: `[312ch]` |\n| `templateModel` and other data objects | Key names only: `{ \"_keys\": [\"name\", \"plan\"] }` |\n| Batch `messages` / `recipients` arrays | Count + recipient list: `{ \"_count\": 2, \"_recipients\": [\"u**r@β¦\", \"a*b@β¦\"] }` |\n| Fields matching `password`, `secret`, `token`, `apikey` | `[redacted]` |\n| Tool name, duration, MCP client identity, status | Logged in full |\n\n> Unstructured operational messages (startup, shutdown, API connectivity) continue to write to stderr as plain text alongside the JSON tool logs.\n\n---\n\n## Security Considerations\n\n### Access scope\nThis MCP server acts with the full permissions of the configured `POSTMARK_SERVER_TOKEN`. It exposes 24 tools β including bulk email sends, template management, webhook registration, and suppression list edits β to any MCP client that connects.\n\nPostmark has [two token types](https://postmarkapp.com/developer/api/overview#authentication): a **Server Token** (used here) and an **Account Token**. Neither supports sub-scoped permissions β a Server Token grants full access to all operations on the server it belongs to. The practical way to limit exposure is structural:\n\n- Create a **dedicated Postmark server** used exclusively for MCP traffic. A compromise is then limited to that server's data and settings rather than your entire account.\n- Configure that server with only the message streams and verified sender signatures it actually needs.\n- Rotate the token if it is ever exposed.\n\n### Tool blast radius\nThe 24 tools include several high-impact operations. Below is the breakdown by risk level:\n\n| Category | Tools |\n|---|---|\n| **Destructive** (irreversible) | `editTemplate`, `deleteTemplate`, `deleteWebhook`, `deleteSuppressions` |\n| **Sending** (outbound email) | `sendEmail`, `sendEmailWithTemplate`, `sendBatch`, `sendBatchWithTemplate` |\n| **Additive** (account-state changes) | `createTemplate`, `createSuppressions`, `createWebhook`, `activateBounce` |\n| **Read-only** | All remaining 12 tools |\n\nAll tools carry MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`). MCP clients that respect annotations β including Cursor and Claude Desktop β can auto-approve safe read-only lookups (`readOnlyHint: true`) and will surface confirmation prompts for anything that isn't a read: sends, template edits, suppression changes, and webhook management. Tools that permanently delete data additionally carry `destructiveHint: true` for clients that distinguish destructive from merely mutating actions.\n\n### Webhook URL policy\n`createWebhook` enforces HTTPS on all URLs. Once a webhook is registered, Postmark will POST event data (opens, clicks, bounces, spam complaints) to that URL on an ongoing basis until the webhook is deleted. To prevent a compromised or misdirected tool call from registering a callback you don't control, set `WEBHOOK_URL_ALLOWLIST` to the HTTPS prefixes you own. Audit registered webhooks regularly with `listWebhooks` or via the [Postmark dashboard](https://account.postmarkapp.com).\n\nTo secure your webhook receiver, whitelist [Postmark's published sending IPs](https://postmarkapp.com/support/article/800-what-are-the-postmark-ip-addresses) at the network or firewall level so only Postmark can POST to your endpoint.\n\n### Prompt injection risk\nBecause this MCP server can send email and register webhooks, it is a potential target for [prompt injection](https://owasp.org/www-project-top-10-for-large-language-model-applications/) β where malicious content in an email, template, or repository tricks the AI into invoking a tool with unintended arguments. The mitigations above (dedicated token, tool approval in your MCP client, `WEBHOOK_URL_ALLOWLIST`) reduce the blast radius if this occurs. Never configure auto-approval for sending or destructive tools in untrusted environments.\n\n---\n\n*For more information about the Postmark API, visit [Postmark's Developer Documentation](https://postmarkapp.com/developer).*\n\n## License\n[MIT](LICENSE) Β© ActiveCampaign","readmeFilename":"README.md"}