Alienmail MCP server
Work with your Alienmail account from Claude, Cursor and other AI tools.
Alienmail has a Model Context Protocol server. Connect it to an AI tool and the assistant can work with your workspace: list campaigns, add leads, check mailboxes and more. Sign in from the AI tool with your Alienmail account, or use an API key.
https://app.alienmail.io/api/mcpThis is not the docs MCP server. That one only reads this documentation and needs no key. This one acts on your account.
Building your own app or agent? See Connect your own app for the OAuth flow, the endpoints and the errors.
Connect by signing in
Most AI tools can sign in to Alienmail for you (OAuth). You only need the server address; no key to create or paste.
- Add
https://app.alienmail.io/api/mcpas a connector in your AI tool (below). - When the tool asks, sign in to Alienmail in the browser window it opens.
- Pick the workspace the tool may use (if you have more than one), check what it will be able to do, and choose Allow.
In claude.ai or Claude Desktop, open Settings → Connectors, choose Add custom connector, enter https://app.alienmail.io/api/mcp and choose Connect. Leave the advanced settings (client ID and secret) empty.
What a connected app can do
- It works in the one workspace you picked, as you, with your role in that workspace. It can never do more than you can, and it never sees your other workspaces.
- On the screen where you allow the app, each permission has a switch. Turn off the one for creating and changing things and the app only gets the tools that read (campaigns, leads, templates, mailboxes, analytics). Connected apps then shows it as Read only, without Make changes.
get_user_profile,list_workspacesandcreate_workspaceare not available to connected apps.- To use an app with another workspace, connect it again and pick that workspace. Connecting the same app to the same workspace again replaces the earlier connection.
- See and disconnect connected apps in Workspace settings → Integrations → Connected apps. Owners and admins see every member's apps; other members see their own. A disconnected app stops at once.
The app gets an access token that lasts an hour and renews itself while you keep using it; after 90 days without use you sign in again. Only a fingerprint of each token is stored.
When a connected app stops working
A connected app loses access, and asks you to sign in again, when:
- you or a workspace owner or admin disconnected it in Connected apps;
- you changed or reset your Alienmail password (this ends every app you connected, in every workspace);
- you left the workspace, or your account was suspended or deleted;
- the workspace was archived or deleted;
- the app wasn't used for 90 days.
To fix it, remove the Alienmail connector in the AI tool, add it again and sign in. If the sign-in screen says the link has expired, start again from the AI tool: the screen stays valid for 15 minutes and works once.
Connect with an API key
For tools that can't sign in, or for automation without a person, create an API key in Workspace settings → Integrations and send it in the Authorization header. The same page in Alienmail shows these snippets with your endpoint filled in.
claude mcp add --transport http alienmail https://app.alienmail.io/api/mcp \
--header "Authorization: Bearer YOUR_API_KEY"Send the key in a header
Don't put the key in the URL. URLs end up in logs, proxies and browser history.
What the key can do
An API key works in its own workspace only, and each tool needs the same permission as the matching action in Alienmail. The tool list your AI tool receives shows only the tools the key's role allows, so a read-only key is not offered tools that change anything. Calling a tool the role doesn't allow returns an error instead of a result.
Three tools work across workspaces and are not available to API keys: get_user_profile, list_workspaces and create_workspace.
Tools
| Area | Tools |
|---|---|
| Workspace | get_workspace_credits, get_workspace_analytics |
| Campaigns | list_campaigns, get_campaign, create_campaign, update_campaign, duplicate_campaign, delete_campaign, start_campaign, toggle_campaign_status, update_campaign_settings |
| Sequence and templates | get_campaign_flow, list_templates, create_template, get_campaign_conditions, create_campaign_condition |
| Leads | list_leads, get_lead, add_lead_to_campaign, import_leads_csv, enroll_leads_in_campaign, bulk_enroll_leads, bulk_update_lead_status, get_lead_email_timeline, create_lead (deprecated: use add_lead_to_campaign) |
| Mailboxes | list_smtp_accounts, add_smtp_account, update_smtp_account, delete_smtp_account, test_smtp_connection |
Your AI tool reads each tool's description and inputs from the server, so you don't need to copy them from here. Each tool also says whether it only reads, whether it deletes or can't be undone (deleting a campaign or a mailbox, changing many leads' status, starting a campaign), and whether it reaches outside Alienmail. Most AI tools use this to ask you before they run one that changes things.
Limits
Each API key, and each connected app, can make 60 tool calls per minute and 2,000 per day. Over the limit, the tool call returns an error that says how long to wait.
Repeated requests with a wrong API key are also limited: after 30 in a minute from one IP address, the server answers 429 with a Retry-After header. The sign-in endpoints have their own limits, listed in Connect your own app.
Try it
After connecting, ask for example:
- "List my active Alienmail campaigns and how many leads each has."
- "Add ada@example.com to the Q1 outreach campaign."
- "Which of my mailboxes are disconnected?"
The assistant acts on your real account. Give the key a role with only the access it needs (or connect the app read-only), and review what the assistant plans to do before it starts campaigns or changes leads.