postmark-mcp 1.0.0

package/.env.example

@@ -0,0 +1,4 @@
+# Postmark Configuration
+POSTMARK_SERVER_TOKEN=your-postmark-server-token-here
+DEFAULT_SENDER_EMAIL=your-sender-email@example.com
+DEFAULT_MESSAGE_STREAM=outbound

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ActiveCampaign
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,247 @@
+# Postmark MCP Server
+
+An MCP server implementation for Postmark email services.
+
+## Features
+- Exposes a Model Context Protocol (MCP) server for sending emails via Postmark
+- Simple configuration via environment variables
+- Comprehensive error handling and graceful shutdown
+- Secure logging practices (no sensitive data exposure)
+- Automatic email tracking configuration
+
+## Feedback
+We'd love to hear from you! Please share your feedback and suggestions through our [feedback form](https://forms.gle/zVdZLAJPM81Vo2Wh8).
+
+## Requirements
+- Node.js (v16 or higher recommended)
+- A Postmark account and server token
+
+## Setup
+
+1. **Clone the repository:**
+   ```sh
+   git clone https://github.com/ActiveCampaign/postmark-mcp
+   cd postmark-mcp
+   ```
+
+2. **Install dependencies:**
+   ```sh
+   npm install
+   ```
+
+3. **Configure environment variables:**
+   - Copy `.env.example` to `.env`:
+     ```sh
+     cp .env.example .env
+     ```
+   - Edit `.env` and fill in your Postmark credentials and settings.
+
+   | Variable                | Description                                      | Required |
+   |------------------------|--------------------------------------------------|----------|
+   | POSTMARK_SERVER_TOKEN  | Your Postmark server API token                   | Yes      |
+   | DEFAULT_SENDER_EMAIL   | Default sender email address                     | Yes      |
+   | DEFAULT_MESSAGE_STREAM | Postmark message stream (e.g., 'outbound')      | Yes      |
+
+4. **Run the server:**
+   ```sh
+   npm start
+   ```
+
+## Quick Install via Cursor Deeplink
+
+You can quickly install this MCP server in Cursor by clicking the following button:
+
+<div>
+  <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=Postmark&config=eyJjb21tYW5kIjoibm9kZSIsImFyZ3MiOlsiaW5kZXguanMiXSwiZW52Ijp7IlBPU1RNQVJLX1NFUlZFUl9UT0tFTiI6IiIsIkRFRkFVTFRfU0VOREVSX0VNQUlMIjoiIiwiREVGQVVMVF9NRVNTQUdFX1NUUkVBTSI6Im91dGJvdW5kIn19">
+    <img src="https://img.shields.io/badge/Add_Postmark_MCP_Server-to_Cursor-00A4DB?style=for-the-badge&logo=cursor&logoColor=white" alt="Add Postmark MCP Server to Cursor" />
+  </a>
+</div>
+
+> **Note**: After clicking the button, you'll need to:
+> 1. Set your `POSTMARK_SERVER_TOKEN` in the MCP configuration
+> 2. Set your `DEFAULT_SENDER_EMAIL` in the MCP configuration
+> 3. Set your `DEFAULT_MESSAGE_STREAM` in the MCP configuration (defaults to "outbound")
+
+## Claude and Cursor MCP Configuration Example
+
+```json
+{
+  "mcpServers": {
+    "postmark": {
+      "command": "node",
+      "args": ["path/to/postmark-mcp/index.js"],
+      "env": {
+        "POSTMARK_SERVER_TOKEN": "your-postmark-server-token",
+        "DEFAULT_SENDER_EMAIL": "your-sender-email@example.com",
+        "DEFAULT_MESSAGE_STREAM": "your-message-stream"
+      }
+    }
+  }
+}
+```
+
+## Tool Reference
+
+This section provides a complete reference for the Postmark MCP server tools, including example prompts and expected payloads for each.
+
+### Table of Contents
+
+- [Email Management Tools](#email-management-tools)
+  - [sendEmail](#1-sendemail)
+  - [sendEmailWithTemplate](#2-sendemailwithtemplate)
+- [Template Management Tools](#template-management-tools)
+  - [listTemplates](#3-listtemplates)
+- [Statistics & Tracking Tools](#statistics--tracking-tools)
+  - [getDeliveryStats](#4-getdeliverystats)
+
+## Email Management Tools
+
+### 1. sendEmail
+
+Sends a single text email.
+
+**Example Prompt:**
+```
+Send an email using Postmark to recipient@example.com with the subject "Meeting Reminder" and the message "Don't forget our team meeting tomorrow at 2 PM. Please bring your quarterly statistics report (and maybe some snacks).""
+```
+
+**Expected Payload:**
+```json
+{
+  "to": "recipient@example.com",
+  "subject": "Meeting Reminder",
+  "textBody": "Don't forget our team meeting tomorrow at 2 PM. Please bring your quarterly statistics report (and maybe some snacks).",
+  "htmlBody": "HTML version of the email body", // Optional
+  "from": "sender@example.com", // Optional, uses DEFAULT_SENDER_EMAIL if not provided
+  "tag": "meetings" // Optional
+}
+```
+
+**Response Format:**
+```
+Email sent successfully!
+MessageID: message-id-here
+To: recipient@example.com
+Subject: Meeting Reminder
+```
+
+### 2. sendEmailWithTemplate
+
+Sends an email using a pre-defined template.
+
+**Example Prompt:**
+```
+Send an email with Postmark template alias "welcome" to customer@example.com with the following template variables:
+{
+  "name": "John Doe",
+  "product_name": "MyApp",
+  "login_url": "https://myapp.com/login"
+}
+```
+
+**Expected Payload:**
+```json
+{
+  "to": "customer@example.com",
+  "templateId": 12345, // Either templateId or templateAlias must be provided, but not both
+  "templateAlias": "welcome", // Either templateId or templateAlias must be provided, but not both
+  "templateModel": {
+    "name": "John Doe",
+    "product_name": "MyApp",
+    "login_url": "https://myapp.com/login"
+  },
+  "from": "sender@example.com", // Optional, uses DEFAULT_SENDER_EMAIL if not provided
+  "tag": "onboarding" // Optional
+}
+```
+
+**Response Format:**
+```
+Template email sent successfully!
+MessageID: message-id-here
+To: recipient@example.com
+Template: template-id-or-alias-here
+```
+
+## Template Management Tools
+
+### 3. listTemplates
+
+Lists all available templates.
+
+**Example Prompt:**
+```
+Show me a list of all the email templates available in our Postmark account.
+```
+
+**Response Format:**
+```
+📋 Found 2 templates:
+
+• Basic
+  - ID: 12345678
+  - Alias: basic
+  - Subject: none
+
+• Welcome
+  - ID: 02345679
+  - Alias: welcome
+  - Subject: none
+```
+
+## Statistics & Tracking Tools
+
+### 4. getDeliveryStats
+
+Retrieves email delivery statistics.
+
+**Example Prompt:**
+```
+Show me our Postmark email delivery statistics from 2025-05-01 to 2025-05-15 for the "marketing" tag.
+```
+
+**Expected Payload:**
+```json
+{
+  "tag": "marketing", // Optional
+  "fromDate": "2025-05-01", // Optional, YYYY-MM-DD format
+  "toDate": "2025-05-15" // Optional, YYYY-MM-DD format
+}
+```
+
+**Response Format:**
+```
+Email Statistics Summary
+
+Sent: 100 emails
+Open Rate: 45.5% (45/99 tracked emails)
+Click Rate: 15.2% (15/99 tracked links)
+
+Period: 2025-05-01 to 2025-05-15
+Tag: marketing
+```
+
+## Implementation Details
+
+### Automatic Configuration
+All emails are automatically configured with:
+- `TrackOpens: true`
+- `TrackLinks: "HtmlAndText"`
+- Message stream from `DEFAULT_MESSAGE_STREAM` environment variable
+
+### Error Handling
+The server implements comprehensive error handling:
+- Validation of all required environment variables
+- Graceful shutdown on SIGTERM and SIGINT
+- Proper error handling for API calls
+- No exposure of sensitive information in logs
+- Consistent error message formatting
+
+### Logging
+- Uses appropriate log levels (`info` for normal operations, `error` for errors)
+- Excludes sensitive information from logs
+- Provides clear operation status and results
+
+---
+
+*For more information about the Postmark API, visit [Postmark's Developer Documentation](https://postmarkapp.com/developer).* 

package/index.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+
+/**
+ * @file Postmark MCP Server - Official SDK Implementation
+ * @description Universal MCP server for Postmark using the official TypeScript SDK
+ * @author Jabal Torres
+ * @version 1.0.0
+ * @license MIT
+ */
+
+import { config } from 'dotenv';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Load environment variables from .env file
+config();
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import postmark from "postmark";
+
+// Postmark configuration
+const serverToken = process.env.POSTMARK_SERVER_TOKEN;
+const defaultSender = process.env.DEFAULT_SENDER_EMAIL;
+const defaultMessageStream = process.env.DEFAULT_MESSAGE_STREAM;
+
+// Initialize Postmark client and MCP server
+async function initializeServices() {
+  try {
+    // Validate required environment variables
+    if (!serverToken) {
+      console.error('Error: POSTMARK_SERVER_TOKEN is not set');
+      process.exit(1);
+    }
+    if (!defaultSender) {
+      console.error('Error: DEFAULT_SENDER_EMAIL is not set');
+      process.exit(1);
+    }
+    if (!defaultMessageStream) {
+      console.error('Error: DEFAULT_MESSAGE_STREAM is not set');
+      process.exit(1);
+    }
+
+    console.error('Initializing Postmark MCP server (Official SDK)...');
+    console.error('Default sender:', defaultSender);
+    console.error('Message stream:', defaultMessageStream);
+
+    // Initialize Postmark client
+    const client = new postmark.ServerClient(serverToken);
+    
+    // Verify Postmark client by making a test API call
+    await client.getServer();
+    
+    // Create MCP server
+    const mcpServer = new McpServer({
+      name: "postmark-mcp",
+      version: "1.0.0"
+    });
+
+    return { postmarkClient: client, mcpServer };
+  } catch (error) {
+    if (error.code || error.message) {
+      throw new Error(`Initialization failed: ${error.code ? `${error.code} - ` : ''}${error.message}`);
+    }
+    throw new Error('Initialization failed: An unexpected error occurred');
+  }
+}
+
+// Start the server
+async function main() {
+  try {
+    const { postmarkClient, mcpServer: server } = await initializeServices();
+    
+    // Register tools with validated client
+    registerTools(server, postmarkClient);
+    
+    console.error('Connecting to MCP transport...');
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    
+    console.error('Postmark MCP server is running and ready!');
+    
+    // Setup graceful shutdown
+    process.on('SIGTERM', () => handleShutdown(server));
+    process.on('SIGINT', () => handleShutdown(server));
+  } catch (error) {
+    console.error('Server initialization failed:', error.message);
+    process.exit(1);
+  }
+}
+
+// Graceful shutdown handler
+async function handleShutdown(server) {
+  console.error('Shutting down server...');
+  try {
+    await server.disconnect();
+    console.error('Server shutdown complete');
+    process.exit(0);
+  } catch (error) {
+    console.error('Error during shutdown:', error.message);
+    process.exit(1);
+  }
+}
+
+// Global error handlers
+process.on('uncaughtException', (error) => {
+  console.error('Uncaught exception:', error.message);
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason) => {
+  console.error('Unhandled rejection:', reason instanceof Error ? reason.message : reason);
+  process.exit(1);
+});
+
+// Move tool registration to a separate function for better organization
+function registerTools(server, postmarkClient) {
+  // Define and register the sendEmail tool
+  server.tool(
+    "sendEmail",
+    {
+      to: z.string().email().describe("Recipient email address"),
+      subject: z.string().describe("Email subject"),
+      textBody: z.string().describe("Plain text body of the email"),
+      htmlBody: z.string().optional().describe("HTML body of the email (optional)"),
+      from: z.string().email().optional().describe("Sender email address (optional, uses default if not provided)"),
+      tag: z.string().optional().describe("Optional tag for categorization")
+    },
+    async ({ to, subject, textBody, htmlBody, from, tag }) => {
+      const emailData = {
+        From: from || defaultSender,
+        To: to,
+        Subject: subject,
+        TextBody: textBody,
+        MessageStream: defaultMessageStream,
+        TrackOpens: true,
+        TrackLinks: "HtmlAndText"
+      };
+
+      if (htmlBody) emailData.HtmlBody = htmlBody;
+      if (tag) emailData.Tag = tag;
+
+      console.error('Sending email...', { to, subject });
+      const result = await postmarkClient.sendEmail(emailData);
+      console.error('Email sent successfully:', result.MessageID);
+      
+      return {
+        content: [{
+          type: "text",
+          text: `Email sent successfully!\nMessageID: ${result.MessageID}\nTo: ${to}\nSubject: ${subject}`
+        }]
+      };
+    }
+  );
+
+  // Define and register the sendEmailWithTemplate tool
+  server.tool(
+    "sendEmailWithTemplate",
+    {
+      to: z.string().email().describe("Recipient email address"),
+      templateId: z.number().optional().describe("Template ID (use either this or templateAlias)"),
+      templateAlias: z.string().optional().describe("Template alias (use either this or templateId)"),
+      templateModel: z.object({}).passthrough().describe("Data model for template variables"),
+      from: z.string().email().optional().describe("Sender email address (optional)"),
+      tag: z.string().optional().describe("Optional tag for categorization")
+    },
+    async ({ to, templateId, templateAlias, templateModel, from, tag }) => {
+      if (!templateId && !templateAlias) {
+        throw new Error("Either templateId or templateAlias must be provided");
+      }
+
+      const emailData = {
+        From: from || defaultSender,
+        To: to,
+        TemplateModel: templateModel,
+        MessageStream: defaultMessageStream,
+        TrackOpens: true,
+        TrackLinks: "HtmlAndText"
+      };
+
+      if (templateId) {
+        emailData.TemplateId = templateId;
+      } else {
+        emailData.TemplateAlias = templateAlias;
+      }
+
+      if (tag) emailData.Tag = tag;
+
+      console.error('Sending template email...', { to, templateId: templateId || templateAlias });
+      const result = await postmarkClient.sendEmailWithTemplate(emailData);
+      console.error('Template email sent successfully:', result.MessageID);
+      
+      return {
+        content: [{
+          type: "text", 
+          text: `Template email sent successfully!\nMessageID: ${result.MessageID}\nTo: ${to}\nTemplate: ${templateId || templateAlias}`
+        }]
+      };
+    }
+  );
+
+  // Define and register the listTemplates tool
+  server.tool(
+    "listTemplates",
+    {},
+    async () => {
+      console.error('Fetching templates...');
+      const result = await postmarkClient.getTemplates();
+      console.error(`Found ${result.Templates.length} templates`);
+      
+      const templateList = result.Templates.map(t => 
+        `• **${t.Name}**\n  - ID: ${t.TemplateId}\n  - Alias: ${t.Alias || 'none'}\n  - Subject: ${t.Subject || 'none'}`
+      ).join('\n\n');
+      
+      return {
+        content: [{
+          type: "text",
+          text: `Found ${result.Templates.length} templates:\n\n${templateList}`
+        }]
+      };
+    }
+  );
+
+  // Define and register the getDeliveryStats tool
+  server.tool(
+    "getDeliveryStats",
+    {
+      tag: z.string().optional().describe("Filter by tag (optional)"),
+      fromDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("Start date in YYYY-MM-DD format (optional)"),
+      toDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("End date in YYYY-MM-DD format (optional)")
+    },
+    async ({ tag, fromDate, toDate }) => {
+      const query = [];
+      if (fromDate) query.push(`fromdate=${encodeURIComponent(fromDate)}`);
+      if (toDate) query.push(`todate=${encodeURIComponent(toDate)}`);
+      if (tag) query.push(`tag=${encodeURIComponent(tag)}`);
+      
+      const url = `https://api.postmarkapp.com/stats/outbound${query.length ? '?' + query.join('&') : ''}`;
+      
+      console.error('Fetching delivery stats...');
+      
+      const response = await fetch(url, {
+        headers: {
+          "Accept": "application/json",
+          "X-Postmark-Server-Token": serverToken
+        }
+      });
+
+      if (!response.ok) {
+        throw new Error(`API request failed: ${response.status} ${response.statusText}`);
+      }
+
+      const data = await response.json();
+      console.error('Stats retrieved successfully');
+      
+      const sent = data.Sent || 0;
+      const tracked = data.Tracked || 0;
+      const uniqueOpens = data.UniqueOpens || 0;
+      const totalTrackedLinks = data.TotalTrackedLinksSent || 0;
+      const uniqueLinksClicked = data.UniqueLinksClicked || 0;
+      
+      const openRate = tracked > 0 ? ((uniqueOpens / tracked) * 100).toFixed(1) : '0.0';
+      const clickRate = totalTrackedLinks > 0 ? ((uniqueLinksClicked / totalTrackedLinks) * 100).toFixed(1) : '0.0';
+      
+      return {
+        content: [{
+          type: "text",
+          text: `Email Statistics Summary\n\n` +
+                `Sent: ${sent} emails\n` +
+                `Open Rate: ${openRate}% (${uniqueOpens}/${tracked} tracked emails)\n` +
+                `Click Rate: ${clickRate}% (${uniqueLinksClicked}/${totalTrackedLinks} tracked links)\n\n` +
+                `${fromDate || toDate ? `Period: ${fromDate || 'start'} to ${toDate || 'now'}\n` : ''}` +
+                `${tag ? `Tag: ${tag}\n` : ''}`
+        }]
+      };
+    }
+  );
+}
+
+// Start the server
+main().catch((error) => {
+  console.error('💥 Failed to start server:', error.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "postmark-mcp",
+  "version": "1.0.0",
+  "description": "Universal Postmark MCP server using official SDK",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "postmark-mcp": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "inspector": "npx @modelcontextprotocol/inspector index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ActiveCampaign/postmark-mcp.git"
+  },
+  "homepage": "https://github.com/ActiveCampaign/postmark-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/ActiveCampaign/postmark-mcp/issues"
+  },
+  "keywords": ["postmark", "email", "mcp", "ai", "model-context-protocol"],
+  "author": "Jabal Torres",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "dotenv": "^16.4.5",
+    "node-fetch": "^3.3.2",
+    "postmark": "^4.0.5",
+    "zod": "^3.23.8"
+  }
+}