Guides

MCP server

ChatGPT, Claude and Grok Bot connect to http://localhost:3000/mcp: you sign in to ApresMail and allow them, no key to copy. Claude Code, Codex and Cursor use a scoped API key. Each sees only tools allowed by its grant, with the same inputs, checks and errors as the REST API.

For audience v2, use Subscriber tools for the one person profile and separate newsletter subscriptions. Contact tools remain compatibility aliases for a newsletter subscription ID; legacy Recipient tools serve v1 accounts and return conflict on v2. A group has one newsletter parent, and neither membership nor CSV import grants consent. The preview is read-only; the durable CSV importer and qualified MailerLite Classic importer are later work.

Choose agent permissions

Create a key on the API keys page. Content read/write is the default; sending and subscriber data stay unchecked. Keys expire after 7, 30 or 90 days. OAuth connections select a subset of the permissions the app requests.

  • Read content: Read drafts, newsletter content and aggregate results.
  • Create and edit content: Work on drafts and media. Pause or cancel campaigns.
  • Send messages and run automations: Send tests, approve or schedule campaigns, resume sequences and enable sending flows.
  • Read subscriber data: Read people, contact exports, memberships and individual activity.
  • Manage subscribers: Change subscribers, imports and memberships. Operations returning personal data also need read access.
  • Manage settings and publication: Manage newsletter settings, sending domains, forms and archives. Live sending settings also need send access.

Send permission also covers tests, scheduling, sequence publication/resumption, live group joins and signup-form publication. Changes to newsletter or sender settings need both settings and send permission. An app requesting only legacy full access must reconnect with granular scopes or use a scoped key.

Connector URL
http://localhost:3000/mcp

ChatGPT

  1. 1Go to Plugins (chatgpt.com/plugins), click + and pick Add custom MCP server.
  2. 2Name it ApresMail, enter http://localhost:3000/mcp as the server URL and pick OAuth, with no client ID or secret. If ChatGPT asks how to register, pick Client ID Metadata Document.
  3. 3Check I understand and want to continue, then click Create as a plugin.
  4. 4Install the plugin, sign in to ApresMail when ChatGPT asks, choose permissions and click Allow.
  5. 5In a chat, type @ and pick ApresMail.

Custom MCP servers are on ChatGPT on the web, for Business, Enterprise and Edu workspaces: on Business, admins and owners add them; on Enterprise and Edu, so can the members an admin allows. On Pro, ChatGPT only uses the read-only tools for now.

Claude

  1. 1Go to Customize › Connectors and click Add custom connector.
  2. 2Name it ApresMail and enter http://localhost:3000/mcp. If Claude asks how it identifies itself, keep Use Claude's published identity. Click Add.
  3. 3Click Connect, sign in to ApresMail, choose permissions and click Allow.
  4. 4The connector works in claude.ai, Claude Desktop and the mobile apps. Turn it on or off in a chat from + › Connectors.

On Team and Enterprise plans, an owner adds it once in Organization settings › Connectors › Add › Custom › Web, then each member clicks Connect under Customize › Connectors. The Free plan has one custom connector.

Grok Bot

  1. 1In a chat, ask Grok Bot to add the custom MCP server http://localhost:3000/mcp.
  2. 2Sign in to ApresMail when it asks, choose permissions and click Allow.

Claude Code

Terminal
claude mcp add --transport http --scope user apresmail http://localhost:3000/mcp \
  --header "Authorization: Bearer $APRESMAIL_API_KEY"

The shell puts the key in Claude Code's settings when the command runs. --scope user makes the server available in every project; run /mcp in Claude Code to check it's connected.

Codex

~/.codex/config.toml
[mcp_servers.apresmail]
url = "http://localhost:3000/mcp"
bearer_token_env_var = "APRESMAIL_API_KEY"

Codex reads the key from APRESMAIL_API_KEY each time it starts, so export it in your shell profile. The same server from the terminal: codex mcp add apresmail --url http://localhost:3000/mcp --bearer-token-env-var APRESMAIL_API_KEY

Cursor

~/.cursor/mcp.json
{
  "mcpServers": {
    "apresmail": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${env:APRESMAIL_API_KEY}"
      }
    }
  }
}

Cursor reads APRESMAIL_API_KEY from the environment it was opened in. If it isn't set there, put the key itself after Bearer, and keep the file out of version control.

Sends can't be undone

schedule_campaign, send_campaign, send_campaign_to_more, resume_campaign, approve_campaign_review are marked destructive, and their descriptions ask the assistant to check with you first. Most clients ask before running them. send_test_email sends only to the account owner.

Connected apps

An app gets only the permissions you select, in your account only. Sending and subscriber data are separate. Older full grants stay labeled legacy until you revoke or replace them. The API keys page lists connected apps with when they were last used. Revoke one there and its tokens stop working right away; it has to ask you again to come back.

Tools

A scoped key sees its permitted tools. Some arguments, such as resuming a sequence, require extra permission. Credential management is only available in the dashboard for scoped users. Each tool's inputs and outputs are in the API reference.

Campaigns

Overview

SMS

Contacts

Subscribers

Recipients

Segments

Groups

Signup forms

Domains

API keys

Protocol

The server is stateless: no sessions, every request carries a key or a token. It speaks the 2026-07-28 revision and answers clients on the 2025 revisions the same way. /api/mcp is the same server, for clients that want an /api path.

OAuth follows the MCP authorization spec. A request without credentials gets a 401 pointing at /.well-known/oauth-protected-resource/mcp, whose authorization server is http://localhost:3000. Apps identify themselves with a client metadata document (Grok Bot, on Cursor's agents, registers instead), sign the user in with the authorization code flow and PKCE, and get tokens bound to http://localhost:3000/mcp with the mailcheap:content:read mailcheap:content:write mailcheap:messages:send mailcheap:audience:read mailcheap:audience:write mailcheap:settings:manage scope. Access tokens last an hour; refresh tokens rotate and keep the connection for 90 days after its last use.