Ask AI about this page

AI assistants (MCP)

Your SubsiMail server speaks MCP (the Model Context Protocol), the standard way AI assistants such as Claude, Cursor and VS Code connect to tools. Once connected you can just ask: “Which campaigns are under 2% replies?”, “Draft a three-step sequence for the Singapore list”, “Pause the mailbox that is bouncing.”

Nothing leaves your server except what the assistant asks for: the connection goes from your AI tool straight to your SubsiMail address, using one of your own API keys.

What it is

The MCP server is built into SubsiMail — there is nothing extra to install or run. It lives at /mcp on your instance (for example https://mail.yourcompany.com/mcp) and is a thin layer over the REST API: every tool the assistant uses is an API call made as the key's owner, so it has exactly that user's role, workspace and sharing rules, and every change appears in the audit history like any other API change.

Connect an assistant

In SubsiMail open Settings → API keys and create a key (for example “Claude”). Copy it — it is only shown once.
On the same page, scroll to Connect an AI assistant. It shows your server's exact address and copy-ready settings for each tool. They look like this:

Claude Code

claude mcp add --transport http subsimail https://mail.yourcompany.com/mcp \
  --header "Authorization: Bearer sk_live_xxxxxxxx"

Cursor

Add to ~/.cursor/mcp.json. VS Code uses the same fields in .vscode/mcp.json under "servers", with "type": "http".

{
  "mcpServers": {
    "subsimail": {
      "url": "https://mail.yourcompany.com/mcp",
      "headers": { "Authorization": "Bearer sk_live_xxxxxxxx" }
    }
  }
}

Claude Desktop

Claude Desktop connects to remote servers through the small mcp-remote helper (needs Node.js). Add to claude_desktop_config.json:

{
  "mcpServers": {
    "subsimail": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mail.yourcompany.com/mcp",
               "--header", "Authorization:${SUBSIMAIL_AUTH}"],
      "env": { "SUBSIMAIL_AUTH": "Bearer sk_live_xxxxxxxx" }
    }
  }
}

Any other MCP client that supports a remote HTTP server with a custom Authorization header works the same way.

What an assistant can do

Area	It can…
Campaigns	List and inspect campaigns, read their stats, steps and enrolled contacts; create a campaign as a draft, edit its settings, add and edit sequence steps, enrol contacts or lists, pause it, archive it.
Activity	Read the event feed (sent, opened, clicked, replied, bounced, failed) filtered by campaign, contact, type or time.
Contacts	List and search with the same query language as Smart Search, read a contact, create and update contacts, archive them.
Lists & fields	List lists and their members, create lists, add contacts to a list, view and create custom fields.
Mailboxes	See connected mailboxes (limits, paused or not, why) and pause or resume one.
Templates & suppression	Read, create and edit templates; view the suppression list and add an address to it.

It cannot see or change mailbox passwords, billing or licence settings, cannot invite or remove team members, and cannot read the inbox. Email-verification results are not exposed either — check those on the Contacts page.

Safety

Same permissions as you. A view-only user's key can only read; the write tools are not even offered to it. A manager's key can only touch what that manager can.
Nothing is ever deleted. There are no delete tools. “Remove” means archive or suppress, both of which you can undo in the app.
Drafts first. A campaign created by an assistant is a draft and sends nothing until a person starts it.
Revoke any time. Revoking the key on the API keys page cuts the assistant off immediately.
Your AI tool normally asks you to approve each tool call before it runs — keep that on for anything that changes data.

Letting an assistant start campaigns

Starting a campaign is the one action that emails real people, so it is off by default: the activate_campaign tool is not offered at all. The person who runs the server can turn it on by setting this environment variable and restarting SubsiMail:

MCP_ALLOW_ACTIVATE=1

Even then the assistant must pass an explicit confirm: true, and its instructions tell it to read the campaign back to you and get a clear “yes” first. Most teams are better off leaving it off and pressing Start themselves after reviewing the draft.

Playbooks (Skills)

SubsiMail ships three short playbooks that teach an assistant to do common jobs the careful way: set up a campaign (ends at a draft), weekly report (replies first, honest about open rates), and list hygiene (suppress, never delete).

Over MCP they are offered automatically as prompts — in clients that show MCP prompts you will see campaign_setup, weekly_report and list_hygiene.
As Claude Skills download the zips from the same Connect an AI assistant section in Settings. In Claude upload them under Settings → Capabilities → Skills; in Claude Code unzip them into ~/.claude/skills/.

Troubleshooting

“401 Unauthorized” — the key is missing, mistyped, revoked, or belongs to a different workspace than you expect. Keys only work in the workspace they were created in.
The assistant can read but not write — the key belongs to a view-only user.
Can't connect at all — the address must be reachable from where the AI tool runs. A SubsiMail on localhost works for desktop tools like Claude Code, but not for AI services that run in the cloud.
Browser opens a blank page at /mcp — that is normal: the endpoint only answers MCP requests (POST), not page loads.