mailrelay-mcp-server

An unofficial Model Context Protocol (MCP) server for the Mailrelay.com email marketing API. It lets AI assistants like Claude manage groups, subscribers, tags, senders, custom fields, and campaigns in your own Mailrelay account.

Not affiliated with Mailrelay. This is an independent, community-built integration against Mailrelay's public REST API. You need your own Mailrelay account and API key to use it.

Features

Subscribers — list, get, create, update, delete
Groups (lists) — list, get, create
Tags — manage account tags and assign/remove them on subscribers
Senders — list, get, create, update, delete verified sender identities
Custom fields — list, create, delete subscriber custom fields
Campaigns — create drafts, send test emails, send to a real audience, delete drafts
Campaign folders — organize campaigns into folders
A/B tests — split-test sender or subject on a draft campaign and pick (or auto-pick) a winner
Imports — bulk-import subscribers from a local CSV file
Sent campaigns — list and inspect delivery stats (opens, clicks, bounces) for past sends

Requirements

Node.js 18 or later
A Mailrelay account and its API key (Mailrelay → Settings → API)

Installation

Option A: npx (no install)

Run it directly without installing, pointing your MCP client at:

npx mailrelay-mcp-server

Option B: from source

git clone https://github.com/YOUR_GITHUB_USERNAME/mailrelay-mcp-server.git
cd mailrelay-mcp-server
npm install

Configuration

The server reads two environment variables:

Variable	Description
`MAILRELAY_BASE_URL`	Your account's base URL, e.g. `https://youraccount.ipzmarketing.com`
`MAILRELAY_API_KEY`	Your Mailrelay API key

If running from source, copy .env.example to .env and fill in your values:

cp .env.example .env

Usage with Claude Code

claude mcp add mailrelay -e MAILRELAY_BASE_URL=https://youraccount.ipzmarketing.com -e MAILRELAY_API_KEY=your-api-key -- npx mailrelay-mcp-server

Or add it manually to your MCP configuration (.mcp.json, or claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "mailrelay": {
      "command": "npx",
      "args": ["mailrelay-mcp-server"],
      "env": {
        "MAILRELAY_BASE_URL": "https://youraccount.ipzmarketing.com",
        "MAILRELAY_API_KEY": "your-api-key"
      }
    }
  }
}

If you installed from source, replace the command/args with "node" / ["/absolute/path/to/mailrelay-mcp-server/src/index.js"].

Available tools

Health

mailrelay_ping — check connectivity and authentication

Groups

mailrelay_list_groups, mailrelay_get_group, mailrelay_create_group

Subscribers

mailrelay_list_subscribers (filter by group or email), mailrelay_get_subscriber, mailrelay_create_subscriber (status: 'active' skips double opt-in; only settable at creation), mailrelay_update_subscriber, mailrelay_delete_subscriber, mailrelay_resend_confirmation_email (double opt-in)

Campaigns

mailrelay_list_campaigns, mailrelay_get_campaign, mailrelay_delete_campaign — draft/scheduled campaigns
mailrelay_create_campaign, mailrelay_send_test_campaign, mailrelay_send_campaign — create and send. mailrelay_send_campaign is irreversible — it delivers real emails to the configured audience.
mailrelay_list_sent_campaigns, mailrelay_get_sent_campaign — past sends with delivery stats

Campaign folders

mailrelay_list_campaign_folders, mailrelay_get_campaign_folder, mailrelay_create_campaign_folder, mailrelay_update_campaign_folder, mailrelay_delete_campaign_folder

A/B tests

mailrelay_list_ab_tests, mailrelay_get_ab_test, mailrelay_create_ab_test, mailrelay_delete_ab_test, mailrelay_cancel_ab_test, mailrelay_set_ab_test_manual, mailrelay_choose_ab_test_winner — requires at least 10 subscribers in the target audience

Imports

mailrelay_list_imports, mailrelay_get_import, mailrelay_cancel_import, mailrelay_start_import — reads a local CSV file and imports it (Mailrelay's API takes the file base64-encoded inline as JSON, not as a multipart upload)

Tags

mailrelay_list_tags, mailrelay_create_tag, mailrelay_delete_tag
mailrelay_list_subscriber_tags, mailrelay_add_subscriber_tags, mailrelay_remove_subscriber_tags

Senders

mailrelay_list_senders, mailrelay_get_sender, mailrelay_create_sender, mailrelay_update_sender, mailrelay_delete_sender

Custom fields

mailrelay_list_custom_fields, mailrelay_create_custom_field, mailrelay_delete_custom_field

Not yet covered: media files, SMS, WhatsApp, ecommerce. Contributions welcome.

Manual testing

npm start

The server speaks MCP over stdio — it isn't meant to be run standalone in an interactive terminal, but launched by an MCP client (Claude Code, Claude Desktop, etc.).

Running it remotely (HTTP mode)

Besides stdio, the server can run as an HTTP service so that MCP clients connect to a URL instead of spawning a local process. Authentication works two ways against the same MCP_AUTH_TOKEN:

Authorization: Bearer <token> header — for clients that let you set headers (Claude Code, Claude Desktop's config file).
OAuth 2.1 handshake — for clients whose UI requires it (Claude Desktop's "Connectors" screen). The authorize step shows a consent page that asks for the same token, so reaching the URL is not by itself enough to gain access.

For a permanent deployment on your own domain, see DEPLOY.md (Hetzner VPS + Caddy). The rest of this section covers a quick temporary tunnel instead.

Temporary tunnel (e.g. to let someone else try it)

For a one-off test where someone else should add this server as a custom connector without installing anything locally, run it over HTTP and expose it through a tunnel:

Add to .env (see .env.example):

PORT=3939
MCP_AUTH_TOKEN=<a long random secret, e.g. `openssl rand -hex 32`>
PUBLIC_URL=<the tunnel URL, filled in after step 3>

Start the HTTP server:
```
npm run start:http
```
It binds to 127.0.0.1 only — it must be reached through a tunnel, not directly.
In another terminal, start a Cloudflare quick tunnel (no account needed):
```
cloudflared tunnel --url http://127.0.0.1:3939
```
It prints a random https://<name>.trycloudflare.com URL.
Give the other person the full endpoint URL (https://<name>.trycloudflare.com/mcp) and the MCP_AUTH_TOKEN value, through a secure channel — not in the same message/channel as anything public.

Either of these works:
- A "Connectors" UI that runs OAuth (e.g. Claude Desktop → Settings → Connectors → Add custom connector): paste the URL, click Connect, and enter the token on the consent screen that appears. Note these UIs cannot send a custom Authorization header on Free/Pro plans (that's Team/Enterprise-only) — which is exactly why the OAuth path exists.
- A client that sets headers directly in its config, skipping the handshake entirely:
- Claude Desktop — add to claude_desktop_config.json:
```
{
  "mcpServers": {
    "mailrelay": {
      "url": "https://<name>.trycloudflare.com/mcp",
      "headers": { "Authorization": "Bearer <the MCP_AUTH_TOKEN value>" }
    }
  }
}
```
  Then restart Claude Desktop.
- Claude Code CLI:
```
claude mcp add --transport http mailrelay https://<name>.trycloudflare.com/mcp \
  --header "Authorization: Bearer <the MCP_AUTH_TOKEN value>"
```
Stop both processes (Ctrl+C) when you're done testing. The trycloudflare.com URL is randomly generated and stops working the moment cloudflared exits, and the token should be rotated (edit MCP_AUTH_TOKEN in .env) if this ever runs unattended for long.

This exposes a server that can send real campaigns (mailrelay_send_campaign is irreversible) — never skip the auth token, and don't leave the tunnel running longer than needed for the test.

Contributing

Issues and pull requests are welcome. Please don't commit real API keys or account URLs — use .env (gitignored) for local testing.

License

MIT

MCP endpoint: https://mailrelay-mcp.com/mcp