MCP Server

The Postject MCP (Model Context Protocol) server lets AI assistants like Claude, Cursor, and Windsurf interact with your Postject account directly from your coding environment. Send test emails, audit deliverability, check domain verification, and more without leaving your editor.

Setup

Add the following to your AI assistant's MCP configuration. For Claude Desktop this is claude_desktop_config.json, for Cursor it is your MCP settings file.

json

{
  "mcpServers": {
    "postject": {
      "command": "npx",
      "args": ["@postject/mcp-server"],
      "env": {
        "POSTJECT_API_KEY": "pk_live_your_api_key_here"
      }
    }
  }
}

Replace pk_live_your_api_key_here with your actual API key from the Postject dashboard.

Environment Variables

Variable	Required	Description
POSTJECT_API_KEY	Yes	Your Postject API key (`pk_live_...` or `postject_...`)
POSTJECT_API_URL	No	API base URL (default: `https://api.postject.com/v1`)

Available Tools (17)

Email

send_email

Send an email with recipient, subject, HTML body, optional sender, template, and variables.

get_message

Get message details and full delivery trace by message ID.

analyze_content

Analyze email content for spam score, HTML quality, link safety, and actionable recommendations.

Infrastructure

list_servers

List all email servers with IDs, names, and token prefixes.

list_domains

List all domains with their verification status.

verify_domain

Check or trigger domain verification. Returns pending DNS records if unverified.

list_streams

List message streams for a given server.

list_templates

List all email templates with names, IDs, and variable lists.

get_template

Get a specific template with full HTML, subject, and variables.

list_suppressions

List suppressed email addresses for a stream with suppression reasons.

Analytics

get_analytics_overview

Get account-wide stats: total sent, delivered, bounced, opened, and more.

get_server_analytics

Get detailed server stats with domain and stream reputations.

get_domain_reputations

Get per-domain reputation scores, bounce rates, and complaint rates.

AI-Native Tools

These tools aggregate data from multiple API endpoints to provide rich context that AI assistants can analyze and act on.

audit_deliverability

Run a comprehensive deliverability audit. Aggregates domain authentication, reputation scores, delivery rates, and engagement insights into a structured report.

generate_email

Gather context for drafting an email: available sender addresses, existing templates, and stream options. The AI assistant uses this to compose the email.

optimize_campaign

Aggregate engagement patterns, domain health, and per-stream performance data. The AI assistant uses this to recommend send time, volume, and content improvements.

suggest_list_hygiene

Analyze suppressions and reputation data across all streams. The AI assistant uses this to recommend list cleaning strategies.

Example Workflows

Send a Test Email

Ask your AI assistant:

"Send a test email to test@example.com with subject 'Hello from Postject' and a simple welcome message."

The assistant will call send_email and return the message ID and status.

Audit Deliverability

Ask your AI assistant:

"Audit the deliverability for my production server and tell me what to fix."

The assistant will use list_servers to find your servers, then audit_deliverability to pull domain auth status, reputation scores, and delivery rates, and provide a plain-English summary with recommendations.

Draft an Email

Ask your AI assistant:

"Help me write a welcome email for new users."

The assistant will use generate_email to gather your available sender addresses and templates, then draft the email content using that context.

Local Development

bash

cd packages/mcp-server
pnpm install
pnpm build
POSTJECT_API_KEY=pk_live_... node dist/index.js

Testing with MCP Inspector

Use the official MCP Inspector to connect to the server and test each tool interactively:

bash

POSTJECT_API_KEY=pk_live_... npx @modelcontextprotocol/inspector node dist/index.js

Authentication

The MCP server authenticates with the same API keys you use for the Node.js SDK, Python SDK, and CLI. Your API key is passed via the POSTJECT_API_KEY environment variable and sent as a Bearer token with every request.

API keys can be created from the Postject dashboard or via the API. See Authentication for details.