Core concepts

MCP server

Let AI assistants run your workspace in natural language — send mail, manage contacts, and launch campaigns.

The Model Context Protocol (MCP) server lets AI assistants — Claude, ChatGPT, Cursor, and any other MCP-capable client — operate your workspace directly. Once connected, you can ask in plain language to send an email, add contacts, build a template, or launch and track a campaign, and the assistant calls the same guarded operations the dashboard and REST API use.

It's a remote, streamable‑HTTP server hosted at a single endpoint:

bash

https://mailer123.com/api/mcp

For AI agents

Hand your AI coding assistant the integration guide — a single, self‑contained Markdown file covering all three ways to integrate (the Node SDK, the REST API, and this MCP server), plus security rules, personalization, error handling, and copy‑paste patterns for React/Node/Next.js apps. Paste it into Claude Code, Cursor, a system prompt, or project instructions (a CLAUDE.md, a custom GPT, etc.) and it will wire mailer123 in correctly.

bash

# Read or download the guide
curl https://mailer123.com/skills.md

The guide lives at /skills.md. It covers the SDK, the API, and MCP — so it works whether your assistant is writing app code or driving the product over MCP. A connected MCP assistant can also call the read_docs tool for live guidance.

Authentication

The MCP server uses the same API keys as the REST API. Create one under Settings → API, then have your client send it as a bearer token on every request:

bash

Authorization: Bearer m123_your_api_key

A sending key can use the email tools (send_email, send_test_email). A full key is required for everything else — contacts, groups, templates, campaigns, analytics, and viewing domains. See Authentication for how scopes work.

Choosing a project

Your key is authorized for one or more projects (workspaces). Every tool (except list_projects and read_docs) accepts an optional project_id argument naming which project to act on:

If the key covers a single project, omit project_id — that project is used automatically.
If the key covers several, pass project_id. Call list_projects first to get each project's id; omitting it returns an error asking you to specify one.

Just tell the assistant which project to work in ("use the Acme project") — it will call list_projects and pass the right project_id for you.

Connect a client

Claude Code (CLI)

Claude Code speaks HTTP transport with custom headers natively:

bash

claude mcp add --transport http mailer https://mailer123.com/api/mcp \
--header "Authorization: Bearer m123_your_api_key"

Claude Desktop, Cursor, Windsurf

Add the server to your client's MCP config. If the client supports remote HTTP servers, point it straight at the endpoint; if it only supports local (stdio) servers, bridge to it with mcp-remote.

{
"mcpServers": {
  "mailer": {
    "url": "https://mailer123.com/api/mcp",
    "headers": { "Authorization": "Bearer m123_your_api_key" }
  }
}
}

claude.ai & ChatGPT (web)

Add a custom connector pointing at the endpoint URL. The hosted web apps can only reach a public HTTPS URL, so connect them to your deployed workspace rather than a local dev server.

Verify the connection

You can exercise the server with a plain HTTP request — this lists every available tool:

bash

curl -X POST https://mailer123.com/api/mcp \
-H "Authorization: Bearer m123_your_api_key" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Available tools

Area	Tools
Projects	`list_projects`
Domains	`list_domains`, `get_domain` (read‑only)
Email	`send_email`, `send_test_email`
Contacts	`list_contacts`, `get_contact`, `create_contact`, `update_contact`, `delete_contact`, `list_custom_fields`
Groups	`list_groups`, `get_group`, `create_group`, `update_group`, `add_contacts_to_group`, `delete_group`
Templates	`list_templates`, `get_template`, `create_template`, `update_template`, `delete_template`
Campaigns	`list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `send_campaign`, `schedule_campaign`, `cancel_schedule`, `duplicate_campaign`, `resend_to_unopened`
Analytics	`get_metrics`
Help	`read_docs`

Tools are self‑describing, so the assistant discovers their arguments automatically. When in doubt, ask it to call read_docs for built‑in guidance on merge tags, the campaign workflow, and limits.

What the assistant can do

Every tool runs the exact guards the dashboard does — verified senders, send quotas, suppression, and moderation — so an AI can't do anything your account couldn't. A few examples to try once connected:

"Send a test of the Welcome template to me@example.com."
"Add jane@acme.com to the Newsletter group."
"Create a campaign to all contacts with subject Spring sale using the Promo template, but leave it as a draft."
"How did last week's campaigns perform?"

Limits

MCP tool calls share the same rate limit (~10 requests per second) and send quotas as the REST API. A call that exceeds your plan's send limit, or targets a suppressed address, fails with the same clear message you'd get from the API — the assistant can read it and adjust.

PreviousWebhooks NextBuilding with AI