MCP server
Connect an MCP-compatible AI assistant to Lettermint to inspect email activity, check delivery and DNS, and perform a small set of controlled actions. Lettermint hosts the server, so there is nothing to install or run locally.
MCP (Model Context Protocol) is an open standard that lets AI applications discover tools and use them with your approval.
The hosted server uses Streamable HTTP and OAuth:
Code
Before you connect
You need:
- A verified Lettermint account
- At least one team where MCP access is enabled
- An MCP client that supports remote HTTP servers and OAuth
- A browser to sign in and approve the connection
Lettermint MCP is OAuth-only. Do not paste a Project API token or Team API token into your MCP client. Those tokens continue to work with their existing APIs, but they do not work with the hosted MCP server.
Connect your client
Use the hosted server URL in your preferred MCP client.
For clients with a connector screen, add a custom remote MCP server and enter https://api.lettermint.co/mcp.
-
Add the server
Use one of the configurations above. In Claude Code, open
/mcpafter adding the server and select Lettermint. -
Sign in to Lettermint
Your client opens a browser. Sign in, review the application and redirect address, then approve access.
-
Choose your working context
Ask the assistant to list your Lettermint teams first. Team-scoped actions need a
team_id; project-scoped actions also need aproject_id.
Start with: “List the Lettermint teams and projects I can access.”
How access works
OAuth connects the application to Lettermint. It does not replace Lettermint permissions.
Code
The OAuth connection requests one scope: mcp:use. This scope lets the application use the curated MCP server. It does not grant every tool or copy your team permissions into a token.
Lettermint checks your access again whenever a tool or resource runs. Disabling MCP for a team, changing a role or project assignment, removing a member, or revoking the application therefore takes effect on the next call.
Lettermint MCP follows your current team permissions. Reconnecting the application does not fix a role or project-access denial.
Teams and projects
The OAuth connection belongs to you, not to one team.
list_teamsreturns only teams you can currently access where MCP is enabled.- Each team includes the capabilities available to you at that moment.
- Team-scoped tools require an explicit
team_id. - Project-scoped tools also require an explicit
project_id. - Joining another team can make it available to an existing connection when that team allows MCP and your permissions allow the requested action.
- Selecting a team in your MCP client never changes the team selected in the Lettermint dashboard.
See Roles and Project access for the permissions that apply outside OAuth.
What your assistant can do
Lettermint publishes a curated catalogue instead of exposing a generic API executor.
| Area | Available tools |
|---|---|
| Documentation | search_documentation |
| Teams and projects | list_teams, list_projects, get_project |
| Email activity | search_messages, get_message, list_message_events, get_message_content |
| Delivery and usage | get_delivery_stats, get_team_usage |
| Routes and domains | list_routes, get_route, list_domains, get_domain, verify_domain_dns, verify_inbound_domain |
| Webhooks | list_webhooks, get_webhook, list_webhook_deliveries |
| Suppressions | search_suppressions, add_suppression (when personal-information filtering is disabled) |
| Sending | send_email (when personal-information filtering is disabled) |
Your current role and project assignment determine which of these tools can succeed. For example, reading message metadata and reading message content are separate permissions.
Message content
Search and detail tools leave message bodies out by default. When your role permits it, get_message_content returns an authenticated resource for HTML, plain text, or raw source.
The resource checks your access again when it is read. The normal 28-day data retention policy still applies.
Personal information filtering
Teams filter personal information returned through MCP by default. When filtering is enabled, message tools hide stored sender and recipient details, subjects, tags, attachment names and types, message metadata, and suppression values. HTML, plain-text, and raw message content are unavailable because free-form content cannot be reliably de-identified. Free-text message and suppression-value searches are also unavailable, so a client cannot use match results to confirm a guessed identity. When filtering is disabled, adding a suppression still returns only an acknowledgement and does not reveal whether that value already existed.
Team, project, route, domain, and webhook configuration remains visible so your assistant can select context and diagnose operational issues. The filter cannot hide information that you enter into a prompt yourself. Email sending and suppression additions are unavailable while filtering is enabled because their outcomes could otherwise reveal stored recipient or suppression information.
Members with Manage team security can change this under Manage team → Settings. The setting is evaluated on every call and acts as a ceiling over message-content and PII-bearing write permissions.
Sending email
When team personal-information filtering is disabled, send_email sends one email at a time and requires an idempotency key. It uses the same sender verification, recipient, payload limits, trust, quota, spend-limit, and suppression checks as other Lettermint sending methods.
MCP actions are real. If your role allows it, an assistant can send email, start domain verification, verify an inbound domain, or add a suppression. Review the requested team, project, recipients, and content before approving a sensitive action in your client.
Safeguards
The MCP server deliberately excludes broad or destructive administration.
- There is no generic REST or API execution tool.
- Project and Team API tokens cannot be created, read, rotated, or deleted.
- Members, roles, billing, and project settings cannot be administered.
- Email sending requires team personal-information filtering to be disabled, is limited to one message per call, and does not support batches.
- Suppression values are filtered from listings. Adding a suppression requires personal-information filtering to be disabled; removal is never available.
- Webhook signing secrets are never returned.
- Message content requires its own permission, requires team personal-information filtering to be disabled, and is never exposed through a public download URL.
- Delivery statistics are limited to 90 days.
- List and search results are capped and paginated.
Try these prompts
- “List the Lettermint teams and projects I can access.”
- “Summarize delivery statistics for this project over the last seven days.”
- “Find failed messages from today and explain their delivery events.”
- “Read the plain-text content of this message.” (Requires your team to allow personal information in MCP.)
- “Check the DNS verification status for this sending domain.”
- “Show recent webhook deliveries that failed.”
- “Search suppressions for
user@example.comin this project.” (Requires your team to allow personal information in MCP.) - “Send one test email from this project with this idempotency key.” (Requires your team to allow personal information in MCP.)
- “Search the Lettermint documentation for sending domains and DKIM.”
Use team and project names in the conversation, then let the assistant resolve them to the explicit IDs required by the tools.
Manage access
You and your team have separate controls.
Revoke a connected application
Open User settings → Applications to review and revoke a connection. Revoking it invalidates the application's access and refresh tokens across every team.
Reconnect through your MCP client when you want to authorize the application again.
Disable MCP for a team
A member with Manage team security can open Manage team → Settings and turn off Allow MCP access.
The team becomes unavailable to every MCP connection immediately. This does not disconnect a member's application from other teams.
Troubleshooting
| Problem | What to check |
|---|---|
| The consent page is unavailable | Confirm your account is active and verified, and that you belong to at least one team where MCP is enabled. |
| A team is missing | Confirm your membership, the team's Allow MCP access setting, and any required account security setup. |
| A project is missing | Review your project assignment in Team members. |
| A tool returns a permission error | Review your role. Reconnecting does not change your permissions. |
An OAuth token cannot call /v1 or /rest/v1 | This is expected. MCP OAuth tokens work only with the hosted MCP server. |
| Sending is denied | Check sender verification, team status, quota or spend limits, and suppressions. |
Related documentation
Roles
Review the permissions that MCP follows.
Project access
Control which projects a team member can use.
Email activity
Search messages and understand delivery events.
Account and team security
Review account, team, and token security controls.