Lettr MCP Server

MCP for Lettr transactional email API

Documentation

Lettr MCP Server

The official Model Context Protocol (MCP) server for Lettr — the email API for developers. Send transactional emails, manage templates with merge tags, configure domains, and monitor webhooks — directly from any MCP client like Claude Desktop, Cursor, or Claude Code.

Why Lettr?

Lettr is a modern email sending platform built for developers. It offers a clean REST API, a powerful drag-and-drop template editor, merge tag personalization, open and click tracking, and best-in-class deliverability. Whether you're sending password resets, order confirmations, or onboarding sequences, Lettr makes it simple and reliable.

API Reference — Full REST API documentation
Templates — Visual email editor with merge tags
Domains — Domain verification and DNS setup
Webhooks — Real-time event notifications
Quickstart Guides — Node.js, PHP, Laravel, Python, Go, Rust, and more

Features

Send Emails — Send transactional emails with HTML, plain text, CC/BCC, attachments, tracking options, metadata, and tags. Supports template-based sending with merge tag substitution, scheduled delivery, and inspecting sent messages and events.
Templates — List, create, get, update, and delete email templates. Retrieve rendered HTML and merge tags to discover which variables a template expects before sending.
Domains — List, create, get, delete, and verify sending domains. View DNS records required for SPF, DKIM, and DMARC authentication.
Webhooks — List, create, get, update, and delete webhook configurations for real-time email event notifications.
Projects — List the projects available to your team so you can target template and email tools at a specific project.
Audience — Manage contacts, lists, subscription topics, custom properties, and segments. Create and update contacts (with double opt-in), attach contacts to lists and topics, bulk import, and build segments from match conditions.
System — Health check and API key validation for client setup and diagnostics.

Setup

Create a free Lettr account
Create an API key in your dashboard
Verify your domain to send emails to any recipient

Usage

Claude Code

claude mcp add lettr -e LETTR_API_KEY=lttr_xxxxxxxxx -- npx -y lettr-mcp

Cursor

Open the command palette and choose "Cursor Settings" > "MCP" > "Add new global MCP server".

{
  "mcpServers": {
    "lettr": {
      "command": "npx",
      "args": ["-y", "lettr-mcp"],
      "env": {
        "LETTR_API_KEY": "lttr_xxxxxxxxx"
      }
    }
  }
}

Claude Desktop

Open Claude Desktop settings > "Developer" tab > "Edit Config".

{
  "mcpServers": {
    "lettr": {
      "command": "npx",
      "args": ["-y", "lettr-mcp"],
      "env": {
        "LETTR_API_KEY": "lttr_xxxxxxxxx"
      }
    }
  }
}

Options

You can pass additional arguments to configure the server:

--key: Your Lettr API key (alternative to LETTR_API_KEY env var)
--sender: Default sender email address from a verified domain
--reply-to: Default reply-to email address

Environment variables:

LETTR_API_KEY: Your Lettr API key (required)
SENDER_EMAIL_ADDRESS: Default sender email address from a verified domain (optional)
REPLY_TO_EMAIL_ADDRESS: Default reply-to email address (optional)

Note: If you don't provide a sender email address, the MCP server will ask for one each time you send an email.

Available Tools

Emails

Tool	Description
`send-email`	Send a transactional email with HTML, plain text, templates, attachments, tracking, and personalization
`list-emails`	List recently sent emails (cursor-paginated, with recipient and date filters)
`list-email-events`	List email events (delivery, bounce, click, open, …) with filters by type, recipient, transmission, and date range
`get-email-detail`	Retrieve the full delivery timeline for a single transmission by request ID
`schedule-email`	Schedule a transactional email for future delivery (5+ minutes ahead, within 3 days)
`get-scheduled-email`	Get the state and events of a scheduled transmission
`cancel-scheduled-email`	Cancel a scheduled transmission before it is sent

Templates

Tool	Description
`list-templates`	List email templates with pagination
`get-template`	Get full template details including HTML content
`create-template`	Create a new template with HTML or visual editor JSON
`update-template`	Update template name and/or content (creates new version)
`delete-template`	Permanently delete a template and all versions
`get-merge-tags`	Discover merge tag variables a template expects
`get-template-html`	Retrieve a template's rendered HTML, subject, and merge tags by project ID and slug

Domains

Tool	Description
`list-domains`	List all sending domains and their verification status
`create-domain`	Register a new sending domain
`get-domain`	Get domain details with DNS records
`delete-domain`	Remove a sending domain
`verify-domain`	Trigger DNS verification for a domain

Webhooks

Tool	Description
`list-webhooks`	List all webhook configurations
`get-webhook`	Get webhook details and delivery status
`create-webhook`	Create a new webhook subscription with auth and event-type selection
`update-webhook`	Update an existing webhook (name, URL, auth, events, active flag)
`delete-webhook`	Delete a webhook subscription

Projects

Tool	Description
`list-projects`	List projects owned by the team — useful for discovering project IDs

Audience

Tool	Description
`list-audience-lists`	List audience (contact) lists with pagination
`create-audience-list`	Create a new audience list
`get-audience-list`	Get a single list and its contact count
`update-audience-list`	Rename an audience list
`delete-audience-list`	Delete an audience list
`bulk-delete-audience-lists`	Delete up to 50 lists in one call
`list-audience-contacts`	List contacts with search, status, list, and segment filters
`get-audience-contact`	Get a contact with its properties, lists, and topics
`create-audience-contact`	Create a contact, optionally with double opt-in
`bulk-create-audience-contacts`	Create many contacts from a list of emails
`update-audience-contact`	Update a contact's email, status, or properties
`delete-audience-contact`	Delete a contact
`attach-contact-to-list`	Add a contact to a list
`detach-contact-from-list`	Remove a contact from a list
`subscribe-contact-to-topic`	Subscribe a contact to a topic
`unsubscribe-contact-from-topic`	Unsubscribe a contact from a topic
`bulk-attach-contacts-to-lists`	Attach many contacts to many lists at once
`bulk-detach-contacts-from-lists`	Detach many contacts from many lists at once
`list-audience-topics`	List subscription topics with pagination
`create-audience-topic`	Create a subscription topic
`get-audience-topic`	Get a single topic
`update-audience-topic`	Update a topic's name, description, or visibility
`delete-audience-topic`	Delete a subscription topic
`list-audience-properties`	List custom contact properties
`create-audience-property`	Define a new custom property
`get-audience-property`	Get a single property
`update-audience-property`	Update a property's fallback value
`delete-audience-property`	Delete a custom property
`list-audience-segments`	List segments, optionally filtered by list
`create-audience-segment`	Create a segment from match conditions
`get-audience-segment`	Get a single segment and its conditions
`update-audience-segment`	Update a segment's name, list, or conditions
`delete-audience-segment`	Delete a segment

System

Tool	Description
`health-check`	Check the Lettr API health status
`auth-check`	Validate the configured API key and return the team ID

Local Development

Clone and build:

git clone https://github.com/nicholasgriffintn/lettr-mcp.git
cd lettr-mcp
pnpm install
pnpm run build

Use the local build in your MCP client:

{
  "mcpServers": {
    "lettr": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_PROJECT/dist/index.js"],
      "env": {
        "LETTR_API_KEY": "lttr_xxxxxxxxx"
      }
    }
  }
}

Testing with MCP Inspector

Make sure you've built the project first (see Local Development above).

Set your API key:

export LETTR_API_KEY=lttr_your_key_here

Start the inspector:
```
pnpm inspector
```
In the browser (Inspector UI):
- Choose stdio (launch a process).
- Command: node
- Args: dist/index.js
- Env: LETTR_API_KEY=lttr_your_key_here
- Click Connect, then use "List tools" to verify the server is working.

Resources

License

MIT