Mailsoftly MCP Server
for Email Marketing & Automation

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. With Mailsoftly's MCP server, an assistant can read your contacts and lists, prepare campaign drafts, and (only if you allow it) send them.

Two ways to connect

Pick one. Most people want the hosted server; the local server exists for developers who prefer to run the process themselves.

The hosted server lives at https://app.mailsoftly.com/mcp. It speaks Streamable HTTP and is authorized with OAuth, so the only thing you ever give your AI client is that URL. Your client registers itself, sends you to Mailsoftly to sign in, and receives a token scoped to exactly the permissions you approved.

Connect from Claude

Connect from ChatGPT

Any other MCP client that supports remote servers with OAuth works the same way: give it the server URL and let it discover the rest.

How the connection is set up

You do not have to do any of this by hand, but here is what happens behind the URL:

• Your client reads /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server to learn where to register and where to authorize.
• It identifies itself either with a Client ID Metadata Document (its client id is an https URL that Mailsoftly fetches and verifies) or by registering with Dynamic Client Registration (RFC 7591) at POST /oauth/register. Either way it is a public client: no shared secret is created.
• It runs the authorization code flow with PKCE (S256). Nothing else is enabled, so there is no password grant and no implicit flow to get wrong.
• You approve the permissions, and the client exchanges the code for a token that is scoped to your company.

Permissions

An app has to ask for what it needs, and you see the request in plain language before anything is granted. Nothing is granted by default.

What the hosted server can do

The hosted server publishes 139 curated tools rather than every API operation, so the assistant picks the right one instead of guessing between near-identical endpoints. Reading tools cover contacts and their activity, lists, tags, segments, suppressions, imports, forms, templates, automations, campaigns with their reports (links, recipients, audience), files, images, content blocks, the brand kit, domain health and the team; writing tools add, import and update contacts, build lists, draft and edit campaigns, upload assets, invite teammates, and, only with the send permission, deliver mail or send a test.

Bring your own HTML, or use ours

A draft's body comes in two formats. body_format: "content" (the default) takes an HTML fragment and places it inside Mailsoftly's responsive layout, so it renders well on phones without any email-CSS work. body_format: "html" takes a complete HTML email you built yourself and stores and sends it exactly as written. Passing template_id instead starts the draft from a saved template, so an assistant can reuse a design your team already approved. update_campaign edits the draft in place afterwards.

Automations from a sentence

An assistant can build an automation the user describes, as a draft: a trigger (a contact is created or updated, a tag is added, a contact joins a list, a form is submitted, a contact unsubscribes) and ordered steps (send an email from a saved template, add or remove tags, add to or remove from lists, wait, post a webhook, stop). Activating it is a separate call that needs the send permission and a verified account, and a contact can be enrolled in an active automation on request. Plan caps apply exactly as in the builder: a free, unverified account may keep a small number of automations, forms and pages, and the response says so with an upgrade or verify path instead of a bare error.

When a send is held, the answer says why

Sending is gated on purpose: a new account needs a sending channel of its own, and every account's first campaigns pass a short content review. Instead of a bare error, send_campaign, get_account, list_senders and get_campaign_status return a gate object that names the level (account or campaign), the reason, a message the assistant can relay verbatim, and unlock_paths with links into your settings. Account-level gates unlock by connecting a Google Workspace or Microsoft 365 account (verified organizations are trusted automatically), connecting a personal Gmail or Outlook mailbox, or authenticating your own sending domain. Campaign-level gates, such as the content review, have no unlock path: the campaign goes out when it is approved, and no account change speeds that up.

Example prompts

Tokens, and turning access off

• Short-lived access tokens. An access token expires two hours after it is issued.
• Rotating refresh tokens. Each refresh issues a new pair and immediately invalidates the old refresh token, so a stolen one stops working as soon as the real client refreshes.
• Revoke at any time. In Mailsoftly, go to Settings > Connected apps to see every connected app, who authorized it and what it was granted. Revoking cuts the app off right away.
• Least privilege by default. A token carries only the permissions you approved, and each tool call is checked against them, so an app that was never granted sending cannot send.

The local server is a small open source Node.js process that runs on your machine and talks to the Mailsoftly API with your API key. It builds its tools from the published OpenAPI spec, so it exposes one tool per live endpoint rather than the curated 139. Use it when your client cannot connect to a remote MCP server, or when you want to run everything yourself.

Prerequisites

• Node.js 20+ installed on your machine
• A Mailsoftly account with an API key (Settings > API Keys)
• An MCP client that supports local servers (Claude Desktop, Cursor, VS Code)

# Navigate to the MCP server directory
cd mcp-server

# Install dependencies
npm install

# Build the server
npm run build

API_KEY_API_KEY=your-mailsoftly-api-key-here
API_BASE_URL=https://app.mailsoftly.com

{
  "mcpServers": {
    "mailsoftly": {
      "command": "node",
      "args": ["/path/to/mcp-server/build/index.js"],
      "env": {
        "API_KEY_API_KEY": "your-mailsoftly-api-key",
        "API_BASE_URL": "https://app.mailsoftly.com"
      }
    }
  }
}

{
  "mcpServers": {
    "mailsoftly": {
      "command": "node",
      "args": ["/path/to/mcp-server/build/index.js"],
      "env": {
        "API_KEY_API_KEY": "your-mailsoftly-api-key",
        "API_BASE_URL": "https://app.mailsoftly.com"
      }
    }
  }
}

About API keys

API keys are managed in Settings > API Keys. A new key expires one year after it is created, is stored as a hash so the key itself is visible only once at creation, and records when it was last used, which makes an unused key easy to spot and revoke. Keys created before this change keep working exactly as before, with no expiry.

Direct API access

Both servers sit on top of the same REST API: 151 live endpoints covering contacts, lists, tags, segments, custom fields, imports and activity, campaigns with their reports, templates, automations, forms, landing pages, files and images, sending identity, team and account. If you would rather call it directly, or wire it into a platform that speaks OpenAPI instead of MCP, everything is documented at API Documentation with a machine-readable spec at app.mailsoftly.com/developers/openapi.json.

For direct API calls the key goes in the Authorization header without a Bearer prefix. OAuth access tokens from the hosted server are sent as Authorization: Bearer <token>.

Security

Hosted server. No key is ever pasted into a client. Access is granted by OAuth after a Mailsoftly admin approves it on a consent screen that lists the permissions in plain language, sending is a separate opt-in, access tokens are short-lived, refresh tokens rotate, and every connection can be revoked from Settings > Connected apps. Each tool call is checked against the permissions that were actually granted, and the connected app is recorded on the contact activity it creates, so you can see later which app did what.

Local server. The process runs on your machine and never sends your key anywhere except app.mailsoftly.com. The key sits in your .env file or MCP config, is stored hashed on our side, and expires a year after you create it.

Either way you are talking only to Mailsoftly: there is no third-party relay in between, and the data an assistant can reach is the data of the one account you connected. See our privacy policy for how account data is handled.