Skip to main content
Lettr’s remote MCP server is hosted at https://app.lettr.com/mcp and authenticates through OAuth 2.1. Connect directly from Claude.ai, Claude Desktop, Claude Code, ChatGPT, Cursor, or GitHub Copilot — no API key required.
No browser available — CI, a cron job, a headless agent? The same server also accepts a lttr_ API key in an Authorization header: see Connect with an API Key. The lettr-mcp npm package that ran on your own machine is no longer updated.

​
Prerequisites

You’ll need a Lettr account with at least one verified sending domain and an AI assistant that supports the Model Context Protocol.

​
Connection Details

When configuring your AI client, use the following settings:

​
Setup by AI Client

​
Claude.ai and Claude Desktop

Claude connects to remote MCP servers as custom connectors. A connector added on Claude.ai is also available in Claude Desktop.
1

Open Connectors

Open Customize → Connectors, click +, and select Add custom connector.
2

Add the Lettr Server

Enter “Lettr” as the name and https://app.lettr.com/mcp as the remote MCP server URL, then click Add.
3

Sign In

Click Connect. A browser window opens to Lettr’s OAuth flow. Sign in and authorize Claude to access your account.
4

Verify Connection

Start a new conversation and ask Claude about your email infrastructure.
On Claude Team and Enterprise plans, an Owner adds the connector once under Organization settings → Connectors. Each member then finds Lettr in their connector list, marked Custom, and clicks Connect to sign in with their own Lettr account.

​
Verifying the Connection

After connecting, verify that your AI assistant can access Lettr by asking a simple question:
“List my sending domains”
The AI should respond with your verified sending domains. If you see domain information, the connection is working correctly.

​
Available Tools

Once connected, your AI assistant can work with every part of your Lettr account. Each tool does exactly what the matching API endpoint does. See the Tools Reference for every tool by name.

​
Permissions and Confirmations

Every tool runs as you, in the team you choose (see Choosing a Team), and goes through the same team permission checks as the dashboard. The AI can’t reach other teams’ data. Tools that send email, overwrite data, or delete it are marked as destructive using the MCP tool annotations. Clients that support these annotations, such as Claude, can ask you to approve each destructive call before it runs. The Tools Reference marks which tools are destructive.
Campaign tools such as send_campaign and schedule_campaign send real email to a campaign’s whole audience. Review the campaign and its audience before approving.

​
Example Workflows

​
Sending a Quick Email

Ask your AI assistant:
“Send an email to support@customer.com from hello@mycompany.com with subject ‘Your request has been received’ and body ‘We’ve received your support request and will respond within 24 hours.’”
The AI will compose and send the email using your verified domain.

​
Debugging Delivery Issues

“Check if the email I sent to john@example.com yesterday was delivered”
The AI will search your email events and report the delivery status, including any bounce information or error codes.

​
Using Templates with Personalization

“Send the ‘order-confirmation’ template to buyer@example.com with order_id ‘12345’ and customer_name ‘Sarah’”
The AI will use your saved template and substitute the merge tags with the provided values.

​
Checking Domain Health

“Are all my sending domains verified and ready to use?”
The AI will list your domains and highlight any with verification issues.

​
Setting Up a New Domain

“Add notifications.example.com as a sending domain and tell me which DNS records to create”
The AI registers the domain and shows the records to publish. Once you’ve added them, ask it to verify the domain, or to diagnose what’s wrong if verification still fails.

​
Scheduling an Email

“Schedule the ‘weekly-digest’ template to team@example.com for Monday at 9am”
The AI schedules the email and returns its ID, so you can check on it or cancel it later.

​
Choosing a Team

An OAuth token identifies you, and you may belong to more than one team. When you do, every tool takes a team_id and will refuse to guess:
This account belongs to more than one team, so team_id is required.
Two tools exist to resolve that without asking you:
  • list_teams — the teams this connection can act on
  • current_team — which team a call would act on, and why
To stop passing team_id on every call, pin a team in your client configuration by adding it to the server URL:
With a team pinned, team_id is removed from the tools altogether, so the assistant cannot act on another team. A Lettr-Team-Id header does the same. If you belong to exactly one team, none of this appears — there is nothing to choose.
Ask your assistant to call current_team before anything destructive. It reports the team and how it was chosen, so you are never relying on it having guessed right.

​
Troubleshooting

Start by ensuring you’re already signed in to Lettr in your browser before initiating the OAuth flow. Check that pop-ups aren’t blocked for the AI client’s domain. If the flow still fails, try disconnecting and reconnecting the MCP server, or clear your browser cache and attempt the connection again.Desktop apps such as Claude Code and Cursor finish sign-in through a callback address on your own machine (localhost). Lettr used to reject these callbacks, so if an earlier attempt from a desktop app failed, remove the server and add it again.
First, verify that the MCP server URL is exactly https://app.lettr.com/mcp with no trailing slash or typos. Confirm that your Lettr session is active by signing in to the dashboard in your browser. Make sure the AI client has MCP support enabled in its settings. If problems persist, try removing the server connection entirely and adding it fresh.
MCP tools use your Lettr team permissions and act on the team you choose. If a tool reports that you aren’t authorized, ask the assistant to call current_team to see which team it is acting on, and check that you’re still a member of it. Tools only see resources owned by that team, so an ID from another team is treated as not found.
Verify that your sending domain is both verified and approved in the Lettr dashboard. Check that the “from” address in your email uses one of your verified domains. Ensure the recipient isn’t on your suppression list due to previous bounces or complaints. Finally, review your account’s sending limits to make sure you haven’t exceeded them.
Email events typically appear within a few seconds of delivery, but there can be slight delays. Check your date range filters, as event queries default to recent activity. For open and click events specifically, ensure that tracking is enabled for the emails you sent—events won’t be recorded for emails sent with tracking disabled.

​
Security Best Practices

When using MCP with Lettr, keep these security considerations in mind:
  • Only connect trusted clients — MCP allows AI assistants to send emails and access account data on your behalf, so treat authorization requests with the same caution you’d apply to any OAuth connection
  • Review before confirming — Tools that send email or change data are marked as destructive, and most AI clients ask before running them. Review email content, recipient lists, and IDs before confirming, especially for campaigns, bulk audience changes, and deletions
  • Audit connected clients — Periodically revoke access for clients you no longer use via Settings → Connected Apps
  • Permission scoping — MCP respects your Lettr team permissions and only acts on the team you choose or pin

​
Disconnecting

To revoke an AI client’s access to your Lettr account, sign in to the Lettr dashboard, navigate to Settings → Connected Apps, find the AI client you want to disconnect, and click Revoke Access. You can also disconnect from within the AI client’s own settings.

​
Rate Limits

MCP requests share your team’s REST API budget, at a higher per-second ceiling: 10 requests per second, because connecting a client costs about 4 requests before it does any work. Exceeding it returns 429 with error_code: rate_limit_exceeded.
  • Sending — Standard API rate limits apply to emails sent through AI assistants
  • Event queries — 25 results per request by default (configurable: 10, 25, 50, or 100)
  • API log queries — 20 results per request by default (configurable: 1, 20, 50, or 100)
  • Pagination — Both support cursor-based pagination for accessing larger result sets
See Rate Limits for detailed information.

​
Learn More

Local Server (deprecated)

Run the MCP server locally with an API key

Tools Reference

Every MCP tool, grouped by area

Sending Domains

Set up domains for sending emails

Templates

Create reusable email templates