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/mcpInside Claude Code
/mcpagentsmail, 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/mcpCodex · authorization
codex mcp login agentsmail/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.
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, thenlist_lists. Check the organization in the response and find a list you recognize before asking for a change.
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, 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. |
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 passconfirmation: 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.| 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 |
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. |
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
Callupsert_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.