MCP Serverjaballerpublic

postmark api mcp

实现 Model Context Protocol 的 Postmark 邮件 API 服务器。

Repository Info

Stars

Forks

Watchers

Issues

TypeScript

Language

License

View on GitHubGitHub Download DocumentationDocs

About This Server

实现 Model Context Protocol 的 Postmark 邮件 API 服务器。

Model Context Protocol (MCP) - This server can be integrated with AI applications to provide additional context and capabilities, enabling enhanced AI interactions and functionality.

Documentation

Model Context Protocol Server for Postmark Email API

This server implements the Model Context Protocol (MCP) for the Postmark Email API, allowing language models to send emails through Postmark using a standardized protocol.

Features

Send single emails through Postmark
Send template-based emails using Postmark templates
Send batch emails in a single request
Support for both stdio and HTTP transports
Configurable via environment variables
Error handling and validation
Health check endpoint for monitoring
Rate limiting and logging configuration
Docker support for development and production

Prerequisites

Node.js 16 or higher
npm or yarn
A Postmark account with an API token
Docker and Docker Compose (optional, for containerized deployment)

Installation

Clone the repository or download the source code
Install dependencies:

npm install

Create a .env file based on the .env.example template:

cp .env.example .env

Edit the .env file to add your Postmark API token and other configuration options:

POSTMARK_SERVER_TOKEN=your_postmark_server_token
DEFAULT_FROM_ADDRESS=your_default_sender@example.com
DEFAULT_MESSAGE_STREAM=outbound
PORT=3000
RATE_LIMIT_MAX_REQUESTS=60
ENABLE_LOGGING=true

Usage

Starting the Server

Development Mode (with hot-reloading):

npm run dev:http

Production Mode:

npm start

With HTTP transport:

npm run start:http

Testing the Server

Health Check

curl http://localhost:3000/health

Expected response:

{"status":"ok"}

Send Test Email

curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test-email-1",
    "method": "send_email",
    "params": {
      "from": "info@jabaltorres.com",
      "to": "jabaltorres@gmail.com",
      "subject": "Test Email",
      "textBody": "This is a test email from the MCP Postmark server"
    }
  }'

Expected response:

{
  "jsonrpc": "2.0",
  "id": "test-email-1",
  "result": {
    "messageId": "12345678-1234-1234-1234-123456789012",
    "status": "sent"
  }
}

Interacting with the Server

The server implements the Model Context Protocol, which uses JSON-RPC 2.0 for communication. You can interact with it using any MCP client or by sending JSON-RPC requests directly.

Available Tools

The server provides the following tools:

send_email - Send a single email
send_template_email - Send an email using a Postmark template
send_batch_emails - Send multiple emails in a batch

Example Requests

List Available Tools

{
  "jsonrpc": "2.0",
  "id": "list-request-123",
  "method": "tools/list"
}

Send an Email

{
  "jsonrpc": "2.0",
  "id": "send-request-123",
  "method": "tools/call",
  "params": {
    "name": "send_email",
    "arguments": {
      "from": "sender@example.com",
      "to": "recipient@example.com",
      "subject": "Test Email from MCP",
      "textBody": "This is a test email sent via MCP.",
      "htmlBody": "<html><body><p>This is a test email sent via MCP.</p></body></html>",
      "trackOpens": true
    }
  }
}

Send a Template Email

{
  "jsonrpc": "2.0",
  "id": "template-request-123",
  "method": "tools/call",
  "params": {
    "name": "send_template_email",
    "arguments": {
      "from": "sender@example.com",
      "to": "recipient@example.com",
      "templateId": "template_id",
      "templateModel": {
        "name": "Test User",
        "message": "Hello from MCP!"
      }
    }
  }
}

Send Batch Emails

{
  "jsonrpc": "2.0",
  "id": "batch-request-123",
  "method": "tools/call",
  "params": {
    "name": "send_batch_emails",
    "arguments": {
      "emails": [
        {
          "from": "sender@example.com",
          "to": "recipient1@example.com",
          "subject": "Test Batch Email 1",
          "textBody": "This is test batch email 1."
        },
        {
          "from": "sender@example.com",
          "to": "recipient2@example.com",
          "subject": "Test Batch Email 2",
          "textBody": "This is test batch email 2."
        }
      ]
    }
  }
}

HTTP Transport

When using the HTTP transport, send POST requests to the server's endpoint (default: http://localhost:3000) with the JSON-RPC request in the body:

curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"list-request-123","method":"tools/list"}'

Configuration Options

The server can be configured using environment variables:

Variable	Description	Default
`POSTMARK_SERVER_TOKEN`	Your Postmark API token	`POSTMARK_API_TEST`
`DEFAULT_FROM_ADDRESS`	Default sender email address	(empty)
`DEFAULT_MESSAGE_STREAM`	Default Postmark message stream	`outbound`
`PORT`	HTTP server port	`3000`
`RATE_LIMIT_MAX_REQUESTS`	Maximum requests per minute	`60`
`ENABLE_LOGGING`	Enable detailed logging	`true`

Development

Building the Project

npm run build

Running Tests

npm test

Docker Development

For local development with Docker:

docker-compose up --build

This will:

Mount your local source code
Enable hot-reloading
Use development environment variables

Docker Production

For production deployment:

docker build -t mcp-postmark-server .
docker run -p 3000:3000 \
  -e POSTMARK_SERVER_TOKEN=your_token \
  -e DEFAULT_FROM_ADDRESS=your_email@example.com \
  -e DEFAULT_MESSAGE_STREAM=outbound \
  -e PORT=3000 \
  -e RATE_LIMIT_MAX_REQUESTS=60 \
  -e ENABLE_LOGGING=true \
  mcp-postmark-server

Architecture

The server follows a modular architecture with the following components:

MCP Server: Core component implementing the Model Context Protocol
Postmark API Client: Handles communication with the Postmark Email API
Email Formatter: Transforms between MCP tool parameters and Postmark API format
Configuration Manager: Manages server configuration

For more details, see the architecture documentation and data flow documentation.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Quick Start

Clone the repository

git clone https://github.com/jaballer/postmark-api-mcp

Install dependencies

cd postmark-api-mcp
npm install

Follow the documentation

Check the repository's README.md file for specific installation and usage instructions.

Repository Details

Ownerjaballer

Repopostmark-api-mcp

LanguageTypeScript

License-

Last fetched8/10/2025

Quick Links

Issues

Releases

License

Recommended MCP Servers

💬

Discord MCP

Enable AI assistants to seamlessly interact with Discord servers, channels, and messages.

integrationsdiscordchat

🔗

Knit MCP

Connect AI agents to 200+ SaaS applications and automate workflows.

integrationsautomationsaas

🕷️

Apify MCP Server

Deploy and interact with Apify actors for web scraping and data extraction.

apifycrawlerdata

🌐

BrowserStack MCP

BrowserStack MCP Server for automated testing across multiple browsers.

testingqabrowsers

⚡

Zapier MCP

A Zapier server that provides automation capabilities for various apps.

zapierautomation