Connect with MCP

MCP lets a compatible agent read your lists, prepare a campaign or follow its results in AgentsMail. You authorize the connection in your browser and choose the organization it can work in, without copying an API key.

Turn on sound in the player to hear the explanation.

Commands to copy

Claude Code

In your terminal, add AgentsMail to your personal configuration. The --scope user option makes this connection available across your projects.

Claude Code · terminal

claude mcp add --transport http --scope user agentsmail https://www.agentsmail.io/api/mcp

Open or restart Claude Code. In its conversation, enter:

Inside Claude Code

/mcp

Choose agentsmail, then start authentication. Your browser opens AgentsMail to ask for your approval.

Codex

In your terminal, add the server:

Codex · terminal

codex mcp add agentsmail --url https://www.agentsmail.io/api/mcp

If authorization did not open automatically, or to reconnect, run:

Codex · authorization

codex mcp login agentsmail

After consent, open or restart Codex. Use /mcp inside Codex to check the active tools.

The terminal commands configure the connection. Access to your data then requires your authorization in the browser, where you choose the organization. No API key to copy.

For client-specific settings, see the official Claude Code and Codex guides.

Authorize access in your browser

After starting authentication from your client, sign in to AgentsMail with your usual account. If you use two-factor authentication, complete that step too.
Check the application name, return address and requested permissions. A self-registered application is marked Unverified application: its name is supplied by the application, not verified by AgentsMail.
Under Organization, select where the agent should work. Only organizations you belong to are listed. If the list is empty, join or create an organization before continuing.
Choose Allow, or Deny to return without granting access. Use another account lets you sign in with a different account before deciding.
Ask your agent to call get_account, then list_lists. Check the organization in the response and find a list you recognize before asking for a change.

Each tool response names the authorized organization. Switching organizations in the web app does not move the agent’s connection; renewing its access keeps the same choice. To work elsewhere, reconnect and choose the other organization. If you leave the organization, the agent loses that access.

What you authorize when connecting

The permissions requested by the application, also called scopes, determine which families of tools this connection can use.

Permission	Tools
Read (`mcp:read`)	`get_account`, `list_lists`, `list_contacts`, `list_tags`, `list_templates`, `list_campaigns`, `get_campaign`, `get_campaign_stats`, `list_sequences`, `list_media`
Manage (`mcp:manage`)	`create_list`, `upsert_contact`, `create_template`, `create_campaign`, `upload_media`, `delete_media`
Send campaigns (`mcp:send`)	`send_campaign`
Stay connected (`offline_access`)	Keeps the connection working when a short-lived access token expires.

Permissions never increase your account rights. Organization members can read; management needs an organization administrator or owner. Starting campaigns also requires the campaign-sending permission available to your account. Your plan limits and available sending units still apply. You can later disable a family of actions in MCP permissions without reconnecting the agent. Turning on Manage there does not add tools to a connection that only requested read access: reconnect the application with the permissions it needs. list_contacts needs a listId: find it with list_lists first. Paginated tools accept page and limit (up to 100). create_template accepts HTML and reports unsupported merge tags. create_campaign creates a draft; it can copy a template from the same organization.

Adding a contact may trigger your configured confirmation emails and automations. Deleting a media file is permanent. Ask your agent to explain these effects before changing your data.

Approve each campaign send

Authorizing the connection does not approve campaign sends. Review the audience and content, then approve that specific campaign. The agent must pass confirmation: true to send_campaign. Approval for one campaign does not approve future campaigns. The result send_requested means that AgentsMail accepted the request. It does not mean every email was delivered. Follow progress with get_campaign and results with get_campaign_stats.

Change permissions without reconnecting

Open the menu under your name in the sidebar, choose Account, then the MCP permissions tab. It has three switches: Read, Manage and Send campaigns. Change your choices, then click Save permissions. They apply on the next request, including an already connected agent. These controls are personal: disabling reading disables it for all your MCP applications, across every organization they can access.

Set a daily sending limit

On the same page, enter Sending units per day, then click Save permissions.

Value	Effect
Empty field	No daily MCP limit
`0`	No paid campaign sends requested through MCP
Positive whole number	Daily maximum in the usual sending units

The counter is shared by your applications and follows your account timezone. It counts units reserved by send requests; requests already picked up for processing remain counted even if sending fails. Check the counter and limit before retrying. The organization’s balance and sending rules still apply.

This limit covers campaigns requested through MCP. It does not cap the configured confirmations and automations that adding a contact may trigger.

Revoke an application

Connected applications shows each application, its return address, permissions and authorized organizations. Revoke blocks that application on its next request across those organizations and prevents access renewal. Requests already in progress may finish. To block a family of actions for all your applications, turn off its permission. Confirm revocation in the dialog, or choose Cancel to keep the connection. To authorize the application again, start a new connection and check its organization and permissions.

If the connection fails

Situation	What to do
The authorization page has expired	Start a new connection from your agent.
A family of actions is disabled	Enable the permission in MCP permissions, then save.
The application never requested that permission	Reconnect with the permissions it needs.
A list or campaign cannot be found	Check the organization with `get_account` and confirm you still belong to it.
The daily sending limit is reached	Check the counter; adjust the limit or wait until the next day.
The application was revoked	Reconnect to grant fresh access.

A suspended account cannot continue using its connection. A send may also be refused if the campaign’s audience changes after the request: check its audience and available units before trying again.