MCP server
Connect an AI client to Lettermint to inspect email activity and manage your email setup. Lettermint hosts the server, so you do not need to install a local process.
Code
Before you connect
You need:
- A verified and active Lettermint account.
- At least one team where MCP access is enabled.
- An MCP client that supports remote Streamable HTTP servers and OAuth.
Use OAuth to connect. Project API tokens and Team API tokens do not work with the hosted MCP server.
Connect your client
Choose your client. Cursor users can also add Lettermint in one click.
The named clients below register an OAuth client automatically. You do not need to enter an OAuth client ID or client secret.
Run these commands:
Code
Use /mcp in Codex or run codex mcp list to check the connection.
The ChatGPT desktop app, Codex CLI, and Codex IDE extension share MCP settings for the same Codex host. A server that you add with the Codex CLI is available in the ChatGPT desktop app on that host. If you use the desktop app, open Settings > MCP servers, add a Streamable HTTP server with the URL above, save it, restart the app, and sign in.
Your client opens a browser. Sign in to Lettermint, review the connection, and approve access.
ChatGPT web uses remote MCP tools supplied by plugins. It does not load the MCP settings from your local Codex clients.
Check the connection
Start with a read-only request:
Use Lettermint to list my teams and projects. Do not change anything.
The client should call list_teams first. This tool returns only the teams that you can access through MCP. It also returns the effective capabilities for each team.
What you can do
Lettermint provides focused tools for these areas:
| Area | Capabilities |
|---|---|
| Documentation search | Find Lettermint product and API guidance. |
| Teams, roles, and members | List teams and effective capabilities. Inspect roles and members. Update team settings or member assignments when allowed. |
| Projects and routes | List, create, update, and delete projects and routes. |
| Domains and DNS | Manage domains and project associations. Check sending DNS and verify inbound domains. |
| Email activity, content, statistics, and usage | Search messages, inspect delivery events, read permitted message content, review delivery statistics, and check usage. |
| Sending and scheduled email | Send one message or a batch. Schedule, reschedule, or cancel messages. |
| Webhooks | Manage webhook endpoints, inspect deliveries, send tests, and rotate signing secrets. |
| Suppressions | Search, add, and remove suppression entries. |
Your MCP client loads current tool names and input schemas from the live catalogue. Use list_teams to see the actions that your role can use for each team.
How access works
- The OAuth connection belongs to your user account, not to one team.
- Every team-scoped request includes an explicit
team_id. Every project-scoped request also includes an explicitproject_id. - Lettermint checks your current membership, project access, role permissions, MFA requirements, and team settings on every call.
- Disabling MCP for a team blocks new and existing connections from that team at once. It does not disconnect the user from other teams.
- Reading message metadata and reading message content are separate permissions.
- Message content follows the data retention policy.
- MCP OAuth credentials work only with the hosted MCP server. They cannot call
/v1or/rest/v1.
See Roles and Project access for the permissions that Lettermint applies.
Personal-information filtering
Personal-information filtering is enabled by default for each team. The filter limits data that can identify a person and actions that can confirm an identity.
| Area | Result while filtering is enabled |
|---|---|
| Message lists and details | Lettermint hides sender and recipient identities, recipient names, subjects, tags, metadata, attachment names, and media types. Delivery IDs, dates, status, and other operational fields remain available. |
| Message content | Message bodies and raw source are not available. |
| Identity searches | Free-text message searches and searches by suppression value are not available. |
| Team members | Member lists, member details, and member assignment changes are not available. Role definitions remain available. |
| Sending | Single and batch sending are not available. |
| Suppressions | Values are hidden. New entries and searches by value are not available. Removal by suppression ID can still be available. |
| Configuration | Permitted team, project, route, domain, and webhook configuration remains available. |
A member with Manage team security can change this setting in Manage team > Settings.
If you turn off the filter, an MCP client can receive personal information and perform permitted identity-related actions. The normal role and project checks still apply.
Write actions and confirmations
MCP actions change live Lettermint data when your permissions and team settings allow them.
- Destructive actions require
confirm=true. Lettermint rejects the action without this value. - Every email send requires an
idempotency_key. See Idempotency. - Webhook creation returns the signing secret once. Secret rotation also returns the new secret once and requires confirmation. Webhook read tools never return a signing secret.
- Your MCP client can require its own approval or block a write action before the request reaches Lettermint.
Use the Lettermint test address when you test sending:
Send one test email to ok@testing.lettermint.co. Use a new idempotency key. Show me the message details before you send it.
Messages to this address simulate a successful delivery. They do not reach a real inbox. See Test email addresses.
Example prompts
- "List the Lettermint teams and projects I can access."
- "Summarize delivery statistics for this project for the last seven days."
- "Find failed messages from today and explain their delivery events."
- "Check the DNS verification state for this sending domain."
- "Create a project and add a route for its production traffic. Show me the planned changes first."
- "Schedule an email for tomorrow at 09:00 Europe/Amsterdam. Show me the message and time before you send it."
- "Create a webhook for failed and delivered events, then send a test event."
- "Search the Lettermint documentation for sending domains and DKIM."
Manage the connection
Open User settings > Applications to review or revoke a connection. Revoking a connection invalidates its MCP access across all teams.
A member with Manage team security can open Manage team > Settings to disable MCP access or change personal-information filtering for a team.
Troubleshooting
| Problem | What to check |
|---|---|
| OAuth registration failed before | Remove the failed Lettermint connector or server entry. Add it again with https://api.lettermint.co/mcp. Select automatic registration if the client gives you that choice. |
| Lettermint does not appear in Codex | Run codex mcp list or use /mcp. Confirm that the server is enabled and authenticated. Restart the desktop app or IDE after you add the server. |
| ChatGPT web does not show Lettermint | ChatGPT web does not load local Codex MCP settings. It can use remote MCP tools when an installed plugin supplies them. |
| The sign-in page is unavailable | Confirm that your account is active and verified. Confirm that at least one team allows MCP access. |
| A team or project is missing | Check your membership, project assignment, MFA state, and the team's Allow MCP access setting. |
| A tool returns a permission error | Check your role. A new connection does not change your permissions. |
| Personal data or sending is unavailable | Check the team's personal-information filtering setting. |
| Sending is denied when filtering is off | Check sender verification, team status, quota, spend limits, and suppressions. |
| The client blocks a write action | Review the client's approval and safety settings. If the client blocks the action, Lettermint receives no tool call. |
| A webhook signing secret is missing | Lettermint returns the secret only after creation or rotation. Rotate the secret with confirmation if you did not store it. |
An OAuth token cannot call /v1 or /rest/v1 | This is expected. MCP OAuth credentials work only with the hosted MCP server. |
Related documentation
Roles
Review the permissions that MCP follows.
Project access
Control which projects a team member can use.
Test email addresses
Test delivery outcomes without sending to a real inbox.
Account and team security
Review account and team security controls.