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

  1. After starting authentication from your client, sign in to AgentsMail with your usual account. If you use two-factor authentication, complete that step too.
  2. 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.
  3. 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.
  4. Choose Allow, or Deny to return without granting access. Use another account lets you sign in with a different account before deciding.
  5. 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.
PermissionTools
Read (mcp:read)get_account, list_lists, list_contacts, get_contact, list_tags, list_templates, list_campaigns, get_campaign, get_campaign_stats, list_sequences, list_media, list_custom_fields
Manage (mcp:manage)create_list, upsert_contact, update_contact, create_template, create_campaign, update_campaign, upload_media, delete_media, create_custom_field, rename_custom_field, delete_custom_field
Send campaigns (mcp:send)send_campaign, schedule_campaign, unschedule_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. update_campaign changes a draft with the same fields as the API: omitted fields stay as they are, null removes a value, and a campaign that is no longer a draft is refused. upload_media accepts a public https image address (url), downloaded by AgentsMail and checked on its content, or a small image in base64, never both.
Adding a contact may trigger your configured confirmation emails and automations. Deleting a media file is permanent. Deleting a custom field erases its value on every contact: delete_custom_field needs confirmation: true, passed only after you approve that field. 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. Scheduling follows the same rule: schedule_campaign books a real send at the time you approve, and also needs confirmation: true. It schedules a draft or moves a campaign that is already scheduled. send_campaign sends immediately; unschedule_campaign puts a scheduled or paused campaign back to draft, and nothing is sent. 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.
ValueEffect
Empty fieldNo daily MCP limit
0No paid campaign sends requested through MCP
Positive whole numberDaily 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

SituationWhat to do
The authorization page has expiredStart a new connection from your agent.
A family of actions is disabledEnable the permission in MCP permissions, then save.
The application never requested that permissionReconnect with the permissions it needs.
A list or campaign cannot be foundCheck the organization with get_account and confirm you still belong to it.
The daily sending limit is reachedCheck the counter; adjust the limit or wait until the next day.
The application was revokedReconnect 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.

See also

The AgentsMail skill provides additional guidance on writing emails and using the product. MCP exposes the tools above; the API reference describes the wider API.

Capture email, then enrich the contact

Call upsert_contact with {listId, email} and retain the returned data.id. Then call update_contact with {contactId: data.id, phone: "+33612345678"}. Read it back with get_contact({contactId}). The four profile fields phone, birthDate, locale and country are optional on upsert and update. Omitted fields stay unchanged; null clears them. Phone uses international + format, birth date uses YYYY-MM-DD (a valid day no later than today in UTC), locale is a BCP 47 tag, and country is two letters, stored uppercase (shape validation only). See Update a contact for exact formats. Saving a phone number does not grant SMS or WhatsApp consent.