Lettr MCP

Add a single contact to a single list. Both the contact and the list must belong to your team.

Validate the configured Lettr API key and return the associated team ID. Use this to verify that the API key is correctly set up before performing other operations.

Attach multiple contacts to multiple lists at once. Every contact is attached to every list (a cartesian product of contact_ids × list_ids). All IDs must belong to your team.

Create many contacts at once from a list of email addresses. Optionally add all of them to a list and/or apply the same custom properties to every contact in the batch. Already-existing emails are skipped (reported separately).

Delete between 1 and 50 audience lists in a single call. Before using this tool, you MUST double-check with the user. Warn them that this action is irreversible — every listed list is removed and its contacts detached. All IDs must belong to your team.

Detach multiple contacts from multiple lists at once (a cartesian product of contact_ids × list_ids). Before using this tool, you MUST double-check with the user, as it removes many memberships at once.

Cancel a scheduled email before it is sent. Before using this tool, you MUST confirm with the user that they really want to cancel this transmission — this action cannot be undone.

Create a single audience contact.

• properties keys must match properties already defined for the team (use list-audience-properties).
• When double_opt_in is provided, the contact is created in unverified status and receives a confirmation email; all four of its fields (from, subject, template_slug, redirect_url) are required.

Create a new audience list. The name must be unique within the team.

Define a new custom contact property. The name must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. The type fixes how values are stored and cannot be changed later.

Create an audience segment defined by match conditions.

Conditions are grouped: conditions within a group are ORed together, and groups are ANDed together. The is_true and is_false operators take no value; all other operators require a value. Optionally restrict the segment to a single list with list_id.

Create a subscription topic. default_subscription controls whether contacts are opted in or out by default (defaults to opt_in); visibility controls whether the topic is shown on public preference pages (defaults to private).

Register a new sending domain with Lettr. The domain starts in pending status until its DKIM record is set up and it is verified. After creation you MUST display the returned DKIM selector/public key to the user so they can configure their DNS.

Create a new email template with HTML or Topol editor JSON content. Provide either html or json — they are mutually exclusive. Merge tags are automatically extracted from the content.

Create a new webhook subscription.

Required: name, url, auth_type, events_mode.

• When auth_type is "basic", auth_username and auth_password are required.
• When auth_type is "oauth2", oauth_client_id, oauth_client_secret and oauth_token_url are required.
• When events_mode is "selected", the events array is required and must contain only valid event type strings.
• When events_mode is "all", the webhook receives every event.

Delete a contact. Before using this tool, you MUST double-check with the user that they want to delete this contact. Warn them that this action is irreversible and removes the contact from all lists and topics.

Delete an audience list. Before using this tool, you MUST double-check with the user that they want to delete this list. Warn them that this action is irreversible — the list is removed and its contacts are detached from it.

Delete a custom contact property. Before using this tool, you MUST double-check with the user that they want to delete this property. Warn them that this action is irreversible and removes the property value from every contact.

Delete an audience segment. Before using this tool, you MUST double-check with the user that they want to delete this segment. Warn them that this action is irreversible. (Contacts themselves are not deleted.)

Delete a subscription topic. Before using this tool, you MUST double-check with the user that they want to delete this topic. Warn them that this action is irreversible and removes all contact subscriptions to it.

Delete a sending domain from Lettr. Before using this tool, you MUST double-check with the user that they want to delete this domain. Warn them that this action is irreversible and will stop all email sending for that domain.

Permanently delete an email template and all its versions. Before using this tool, you MUST double-check with the user that they want to delete this template. Warn them that this action is irreversible and any emails referencing this template slug will fail.

Delete a webhook subscription. Before using this tool, you MUST double-check with the user. Warn them that this action is irreversible and event delivery to the configured URL will stop immediately.

Remove a single contact from a single list.

Retrieve a single contact by ID, including status, custom properties, and the lists and topics it belongs to.

Retrieve a single audience list by its ID, including its current contact count.

Retrieve a single custom contact property by its ID.

Retrieve a single audience segment by its ID, including its condition groups and cached contact count.

Retrieve a single subscription topic by its ID.

Retrieve a single campaign by its ID, including embedded engagement stats and a preview of its rendered HTML content.

Retrieve full details of a sending domain including CNAME, DKIM, DMARC and SPF status, tracking domain configuration, and any detected DNS provider.

Retrieve the full delivery timeline for a single transmission by request ID — returns derived state (scheduled/delivered/bounced/failed), recipients and all events.

Retrieve the merge tags (variables) for a template. Use this to discover which substitution_data keys a template expects when sending an email. By default returns merge tags for the active version.

Retrieve details of a scheduled (but not yet sent) email, including its state, scheduled_at timestamp, recipients and any events collected so far.

Retrieve full details of a template by its slug, including active version HTML/JSON content and version count.

Retrieve a rendered template by project_id and slug. Returns the HTML body, the subject (if set) and the list of merge tags (each with key, name and required flag). This endpoint uses a non-standard {success, data} response envelope.

Retrieve details of a specific webhook by its string ID (e.g. "webhook-abc123"). Includes enabled state, event types, auth type, and last delivery timestamps.

Check the Lettr API health status. Returns the current API status and a server timestamp. This endpoint does not require authentication.

List audience contacts with pagination and optional filters. Filter by free-text search (email or name), status, a specific list, or a specific segment.

List the audience (contact) lists for your team, with pagination. Use this to discover list IDs to pass to contact and segment tools.

List the custom contact properties defined for your team, with pagination. Use this to discover which property keys are valid when creating or updating contacts.

List audience segments for your team, with pagination. Optionally filter to segments restricted to a specific list.

List subscription topics for your team, with pagination. Use this to discover topic IDs to subscribe contacts to.

List engagement events (opens, clicks, bounces, etc.) for a campaign, with optional filters. Uses cursor-based pagination: this tool returns one page plus a next_cursor. Keep calling it with cursor set to the returned next_cursor until next_cursor is null. Note: when a filter is applied, a page can come back with no events but a non-null next_cursor — that means more pages remain, so keep paginating until next_cursor is null.

List campaigns for your team, with pagination and an optional status filter. Each campaign includes embedded engagement stats. Use this to discover campaign IDs for the other campaign tools.

List all sending domains registered with your Lettr account. Returns domain names, statuses, and CNAME/DKIM verification state.

List email events (delivery, bounce, click, open, …) across all sent messages, filtered by event type, recipient, date range, transmission ID or bounce class.

List recently sent emails with pagination and optional filters. Returns injection events for each email so you can inspect subject, recipient and timestamp.

List projects owned by the team, with pagination. Use this to discover project IDs to pass to template and email tools.

Purpose: List email templates with pagination. Returns template names, slugs, and project info.

Returns: Paginated list of templates with id, name, slug, project_id, folder_id, timestamps.

When to use:

• User asks "show my templates", "what templates do I have?"
• Before sending a template-based email, to find the template slug
• Use get-template for full details of a specific template

List all webhooks configured for your Lettr account. Returns webhook URLs, enabled status, subscribed event types, and last delivery result.

Schedule a draft campaign for future delivery, or reschedule an already-scheduled campaign to a new time. Before using this tool, you MUST confirm the time with the user and warn them that at the scheduled time this will dispatch real emails to recipients. The campaign must be a draft or already scheduled, with a subject, sender, and content.

Schedule an email for future delivery. Accepts the same fields as send-email plus a required scheduled_at (ISO 8601, UTC) that is at least 5 minutes in the future and at most 3 days out.

Returns: Same response as send-email (request_id + accepted/rejected counts).

Immediately send a draft campaign to its recipients. Before using this tool, you MUST double-check with the user that they want to send now. Warn them that this is irreversible and outward-facing — it dispatches real emails to recipients that cannot be recalled. The campaign must be a draft with a subject, sender, and content; on success it transitions to "preparing".

Purpose: Send a transactional email to one or more recipients. Supports HTML, plain text, AMP HTML, templates with merge tags, attachments, custom headers, tracking, and personalization.

Returns: Send confirmation with request ID and accepted/rejected counts.

When to use:

• User wants to "send an email" to specific people
• One-off messages: password reset, order confirmation, receipt, alert
• User says "email this to X", "notify them", "send a message to..."
• Sending with a template: use template_slug and substitution_data (subject is optional in this case)

Key trigger phrases: "Send an email", "Email this to", "Notify", "Send a message", "Reply to them"

Subscribe a single contact to a single topic. Both must belong to your team.

Cancel a scheduled send, returning the campaign to draft. The campaign must currently be scheduled.

Unsubscribe a single contact from a single topic.

Update a contact. All fields are optional — only provided fields change.

• status may only be set to subscribed or unsubscribed.
• properties is a partial update: include only the keys you want to change. Setting a property to null removes it from the contact.

Rename an audience list. The new name must remain unique within the team.

Update a property's fallback value. The name and type are fixed at creation and cannot be changed. Set fallback_value to null to clear it.

Update an audience segment. All fields are optional — only provided fields change. Providing conditions replaces the entire condition set.

Update a subscription topic. All fields are optional — only provided fields change. Note that default_subscription cannot be changed after creation.

Update an existing template's name and/or content. Providing new html or json content creates a new version automatically. The html and json fields are mutually exclusive.

Update an existing webhook. All fields are optional — only provided fields are changed.

Notes:

• The enabled flag is named active on update (the response field is enabled).
• The events array uses the canonical fully-prefixed event names (e.g. "message.delivery", "engagement.open").

Trigger DNS verification for a domain. Checks DKIM, CNAME (when applicable), DMARC and SPF records and returns the full validation report.