Scoped API keys for AI agents on Lettr's MCP server

Lettr, a sending platform for transactional and marketing email, runs a remote MCP server that an AI agent can connect to with its own API key. The key's permission level, Full access or Sending only, fixes the list of tools the server offers the agent, so a Sending only key gives an agent no tools for changing templates, domains, webhooks, or the audience.

How an agent connects with an API key

An agent that connects with an API key acts as a team (the Lettr workspace that holds its own domains, templates, and audience) rather than as a person. The key belongs to one team, so the agent can reach no other team, and its tools take no team ID. The client config needs the server URL and the key in an Authorization header:

{
  "url": "https://app.lettr.com/mcp",
  "headers": {
    "Authorization": "Bearer lttr_xxxxxxxxx"
  }
}

Anyone who can read a client config file can use the key in it, so keep the key in an environment variable and keep config files out of version control.

A key's IP allowlist applies to its MCP calls exactly as it does to its REST calls, and Lettr refuses a call from any other address with a 403 error. MCP and REST calls also draw on one per-team rate-limit budget. The MCP endpoint allows up to 10 requests per second against REST's 3, because connecting a client alone takes several requests.

For an assistant a person uses directly, signing in is the better fit. A signed-in connection acts as the person who signed in, so it can reach every team they belong to.

Which tools does each permission level give an agent?

The remote MCP server builds the tool list from the key's permission level, and it checks the list again on every request:

• Full access gives every tool except list_api_keys and browse_api_logs, which no API key can use.
• Sending only gives send_email, send_template_email, schedule_email, and cancel_scheduled_email, plus current_team and list_teams, which report the key's team.

Behind the two levels, each tool checks one scope, the same one the REST API checks for the matching endpoint: listing contacts needs audience:read, and sending a campaign needs campaigns:write. The permission level decides which scopes a key holds.

When an agent calls a tool its key excludes, the call returns a "tool not found" error rather than one that names a missing scope, because the server never registers the tool for that key.

Choose the permission level for each agent's job

Give each agent its own key, so that revoking or rotating one agent's key leaves the other agents working. Then choose the narrower level whenever the job allows it.

• Sending only fits an agent that only sends, schedules, or cancels email. A leaked Sending only key cannot change the team's templates, domains, webhooks, audience, or campaigns.
• Full access fits an agent that manages templates, webhooks, or the audience, or that reports on and sends campaigns.

A Full access agent can list campaigns, read their stats and events, and send, schedule, or unschedule them. No MCP tool creates a campaign: campaigns are built in the dashboard or through the REST API, and the agent works with them from there.

Test the agent with a sandbox key

A sandbox key, whose value starts with lttr_sandbox_, lets an agent read the team's data and send, schedule, and cancel email. It cannot call any tool that writes data, so it cannot change templates, domains, webhooks, the audience, or campaigns, and it cannot send or schedule a campaign.

Lettr delivers every email sent with a sandbox key to the inbox of the key's creator, replaces the domain in the sender address with dev.uselettr.com, and drops CC and BCC recipients, so each email the agent writes during the test can be read before any customer sees one.

Sandbox keys have their own rate limits of 20 requests per second, 120 per minute, and 2,000 per day per key, outside the team's live budget. Once the agent behaves as expected, give it a live key at the same permission level. A live Full access key also unlocks the write tools a sandbox key never offered, so the test covers reading and sending, not changes to the team's data.

Where do one agent's calls show up?

The Logs page in Lettr's dashboard filters the API logs by key, and the API logs record MCP calls made with a key alongside its REST calls. With one key per agent, the filter shows a single agent's calls. Calls from a signed-in connection belong to a person rather than a key and don't appear there.

No API key can call browse_api_logs, so reading the logs from a chat requires an assistant connected by signing in.

Why else use Lettr?

An agent's key covers one job, and Lettr covers the rest of a team's email: transactional messages that an app triggers through the REST API or SMTP, and marketing campaigns sent to the team's audience, on one account.

The people who write the emails build them in Lettr's drag-and-drop editor, with synced sections that update every template using them, multilingual templates, and merge tags, so a copy change needs no developer. Webhooks tell an app when an email is delivered, opened, or clicked.

FAQ

Bottom line

One key per agent, at the narrowest level the job allows, limits each agent to the tools its job needs. Test the agent with a sandbox key, then follow its live calls in the API logs.

Create a free Lettr account to give your first agent its own API key. Once you're in, the API key guide covers the connection for each client.