Connect Claude, ChatGPT, Cursor, or any MCP-compatible client to your Mailsoftly account and work with contacts, lists and campaigns in plain language.
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.
Pick one. Most people want the hosted server; the local server exists for developers who prefer to run the process themselves.
Paste one URL into your AI client and sign in with your Mailsoftly account. No install, no API key to copy, no key sitting in a config file. Works with Claude and ChatGPT.
Run the open source Node.js server on your own machine and point Claude Desktop, Cursor or VS Code at it. Authenticates with a Mailsoftly API key.
| Hosted server | Local server (stdio) | |
|---|---|---|
| Setup | Paste a URL, approve the permissions | Clone, build, edit a JSON config |
| Sign-in | OAuth, no key to copy | Mailsoftly API key |
| Runs on | Mailsoftly servers | Your machine |
| Tools | 16 curated tools | One tool per live API endpoint |
| Turn it off | Settings > Connected apps | Delete the key or the config entry |
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.
In Claude, go to Settings, then Connectors, then Add custom connector.
Give it the name Mailsoftly and the URL https://app.mailsoftly.com/mcp, then confirm.
Claude opens Mailsoftly in your browser. Sign in, read the list of permissions the app is asking for, and approve. You land back in Claude with the connector ready.
In ChatGPT, open the settings area where connectors and apps are managed and choose to add one by URL.
https://app.mailsoftly.com/mcp. ChatGPT walks the same sign-in and consent flow as Claude.
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.
Connecting a third-party app is an admin action. If you are not an admin on your company, the consent screen tells you so and asks you to have an admin connect the app instead.
You do not have to do any of this by hand, but here is what happens behind the URL:
/.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server to learn where to register and where to authorize.POST /oauth/register. Registrations are public clients: no shared secret is created.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.
| Permission | What the app can do with it |
|---|---|
contacts:read | Read your contacts, lists and tags |
contacts:write | Create and update contacts, lists and tags |
campaigns:read | Read your campaigns and their status |
campaigns:draft | Create and edit campaign drafts. Drafts are never delivered on their own |
campaigns:send | Send or schedule campaigns to your contacts. Separate opt-in, see below |
suppressions:write | Add addresses to your suppression list so they stop receiving mail |
account:read | Read your account and company profile |
Sending mail cannot be undone, so approving an app never grants it on its own. When an app asks for campaigns:send, the consent screen shows a separate checkbox that starts unchecked. Leave it off and everything else still works: the app can research, draft and prepare, and you press send yourself.
The hosted server publishes 16 curated tools rather than every API operation, so the assistant picks the right one instead of guessing between near-identical endpoints.
| Tool | What it does | Permission |
|---|---|---|
search_contacts | Find contacts by exact email, first name or last name | contacts:read |
get_contact | Read one contact by id, with an optional detailed view | contacts:read |
create_contact | Add one new person to the account | contacts:write |
update_contact | Change fields on an existing contact | contacts:write |
create_or_update_contact | Update a contact by id, or create one when no id is given | contacts:write |
create_contact_list | Create a new, empty contact list | contacts:write |
add_contact_to_contact_list | Put an existing contact into an existing list | contacts:write |
list_contact_lists | List the account's contact lists with their ids and sizes | contacts:read |
list_contacts_in_list | Return the contacts that belong to one list | contacts:read |
list_tags | List the contact tags defined in the account | contacts:read |
get_custom_fields | List the custom contact fields this account has defined | contacts:read |
list_senders | List the senders a draft can send from, and which one is the default | account:read |
draft_campaign | Write an email campaign into the account as a draft. Sends nothing | campaigns:draft |
get_campaign_status | Report where a draft stands and whether it is ready to send | campaigns:read |
send_campaign | Deliver an existing draft to its recipients. Cannot be undone | campaigns:send |
unsubscribe_contact | Globally unsubscribe an email address from every campaign | suppressions:write |
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 16. Use it when your client cannot connect to a remote MCP server, or when you want to run everything yourself.
The server lives in the Mailsoftly repository under mcp-server/.
# Navigate to the MCP server directory cd mcp-server # Install dependencies npm install # Build the server npm run build
Create a .env file in the mcp-server/ directory with your Mailsoftly API key.
API_KEY_API_KEY=your-mailsoftly-api-key-here API_BASE_URL=https://app.mailsoftly.com
Add the following to your Claude Desktop configuration file.
{
"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"
}
}
}
}
Add the same configuration to your Cursor or VS Code MCP settings.
{
"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"
}
}
}
}
Restart your AI tool and ask it to work with your account. Try "List my contact lists" or "Create a new contact".
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.
Both servers sit on top of the same REST API: 26 live endpoints covering contacts, contact lists, tags, custom fields, campaign drafts, sending and unsubscribes. 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.
Use the OpenAPI spec in a custom GPT's actions to work with campaigns and contacts. Spec: /developers/openapi.json
Import the OpenAPI spec as a Vertex AI Extension to manage contacts and campaigns from Gemini.
The same spec drives tool use and function calling in any framework that reads OpenAPI.
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>.
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.
Add https://app.mailsoftly.com/mcp in your AI client and approve the permissions. That is the whole setup.