lettr-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Plus Five Five, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# Lettr MCP Server
+
+The official [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for [Lettr](https://lettr.com) — 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](https://claude.ai/download), [Cursor](https://cursor.com), or [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+
+## Why Lettr?
+
+[Lettr](https://lettr.com) 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](https://docs.lettr.com/api-reference/introduction)** — Full REST API documentation
+- **[Templates](https://docs.lettr.com/learn/templates/introduction)** — Visual email editor with merge tags
+- **[Domains](https://docs.lettr.com/learn/domains/introduction)** — Domain verification and DNS setup
+- **[Webhooks](https://docs.lettr.com/learn/webhooks/introduction)** — Real-time event notifications
+- **[Quickstart Guides](https://docs.lettr.com/quickstart/nodejs/introduction)** — 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](https://docs.lettr.com/learn/templates/introduction) with merge tag substitution.
+- **Templates** — List, create, get, update, and delete email templates. Retrieve [merge tags](https://docs.lettr.com/learn/templates/template-language) to discover which variables a template expects before sending.
+- **Domains** — List, create, get, delete, and [verify sending domains](https://docs.lettr.com/learn/domains/sending-domains). View DNS records required for SPF, DKIM, and DMARC authentication.
+- **Webhooks** — List and inspect [webhook configurations](https://docs.lettr.com/learn/webhooks/introduction) for real-time email event notifications.
+
+## Setup
+
+1. Create a free [Lettr account](https://app.lettr.com/register)
+2. [Create an API key](https://docs.lettr.com/learn/api-keys/introduction) in your dashboard
+3. [Verify your domain](https://docs.lettr.com/learn/domains/sending-domains) to send emails to any recipient
+
+## Usage
+
+### Claude Code
+
+```bash
+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".
+
+```json
+{
+  "mcpServers": {
+    "lettr": {
+      "command": "npx",
+      "args": ["-y", "lettr-mcp"],
+      "env": {
+        "LETTR_API_KEY": "lttr_xxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Open Claude Desktop settings > "Developer" tab > "Edit Config".
+
+```json
+{
+  "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](https://docs.lettr.com/learn/domains/sending-domains)
+- `--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 |
+
+### 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 |
+
+### 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 |
+
+## Local Development
+
+1. Clone and build:
+
+```bash
+git clone https://github.com/nicholasgriffintn/lettr-mcp.git
+cd lettr-mcp
+pnpm install
+pnpm run build
+```
+
+2. Use the local build in your MCP client:
+
+```json
+{
+  "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](#local-development) above).
+
+1. Set your API key:
+
+   ```bash
+   export LETTR_API_KEY=lttr_your_key_here
+   ```
+
+2. Start the inspector:
+
+   ```bash
+   pnpm inspector
+   ```
+
+3. 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
+
+- [Lettr Website](https://lettr.com)
+- [API Documentation](https://docs.lettr.com/api-reference/introduction)
+- [MCP Setup Guide](https://docs.lettr.com/learn/mcp/setup)
+- [MCP Tools Reference](https://docs.lettr.com/learn/mcp/tools-reference)
+- [Template Language](https://docs.lettr.com/learn/templates/template-language)
+- [DNS Setup Guides](https://docs.lettr.com/knowledge-base/dns-guides/cloudflare)
+- [Knowledge Base](https://docs.lettr.com/knowledge-base/introduction)
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import minimist from 'minimist';
+import { LettrClient } from './lettr.js';
+import packageJson from './package.json' with { type: 'json' };
+import { addDomainTools, addEmailTools, addTemplateTools, addWebhookTools, } from './tools/index.js';
+const argv = minimist(process.argv.slice(2));
+const apiKey = argv.key || process.env.LETTR_API_KEY;
+const senderEmailAddress = argv.sender || process.env.SENDER_EMAIL_ADDRESS;
+const replierEmailAddress = typeof argv['reply-to'] === 'string'
+    ? argv['reply-to']
+    : process.env.REPLY_TO_EMAIL_ADDRESS || undefined;
+if (!apiKey) {
+    console.error('No API key provided. Please set LETTR_API_KEY environment variable or use --key argument');
+    process.exit(1);
+}
+const lettr = new LettrClient(apiKey);
+const server = new McpServer({
+    name: 'lettr',
+    version: packageJson.version,
+});
+addEmailTools(server, lettr, { senderEmailAddress, replierEmailAddress });
+addTemplateTools(server, lettr);
+addDomainTools(server, lettr);
+addWebhookTools(server, lettr);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Lettr MCP Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+});

package/dist/lettr.js

@@ -0,0 +1,50 @@
+const BASE_URL = 'https://app.lettr.com/api';
+export class LettrClient {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async request(method, path, body, query) {
+        const url = new URL(`${BASE_URL}${path}`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json',
+        };
+        const options = { method, headers };
+        if (body && (method === 'POST' || method === 'PUT' || method === 'PATCH')) {
+            headers['Content-Type'] = 'application/json';
+            options.body = JSON.stringify(body);
+        }
+        const response = await fetch(url.toString(), options);
+        const json = await response.json();
+        if (!response.ok) {
+            const err = json;
+            const detail = err.errors
+                ? `\n${Object.entries(err.errors)
+                    .map(([field, msgs]) => `  ${field}: ${msgs.join(', ')}`)
+                    .join('\n')}`
+                : '';
+            throw new Error(`Lettr API error (${response.status}): ${err.message}${detail}`);
+        }
+        return json;
+    }
+    async get(path, query) {
+        return this.request('GET', path, undefined, query);
+    }
+    async post(path, body, query) {
+        return this.request('POST', path, body, query);
+    }
+    async put(path, body, query) {
+        return this.request('PUT', path, body, query);
+    }
+    async delete(path, query) {
+        return this.request('DELETE', path, undefined, query);
+    }
+}

package/dist/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "lettr-mcp",
+    "version": "1.0.0",
+    "description": "MCP server for the Lettr email API — send transactional emails, manage templates, domains, and webhooks from any AI assistant",
+    "keywords": [
+        "lettr",
+        "email",
+        "email-api",
+        "transactional-email",
+        "mcp",
+        "model-context-protocol",
+        "ai",
+        "claude",
+        "cursor",
+        "templates",
+        "email-templates"
+    ],
+    "homepage": "https://lettr.com",
+    "license": "MIT",
+    "type": "module",
+    "bin": {
+        "lettr-mcp": "dist/index.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', '755')\"",
+        "prepare": "npm run build",
+        "inspector": "npx @modelcontextprotocol/inspector@latest",
+        "lint": "biome check .",
+        "lint:fix": "biome check . --write"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "1.26.0",
+        "minimist": "1.2.8",
+        "zod": "4.3.6"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.4.2",
+        "@types/minimist": "1.2.5",
+        "@types/node": "25.0.3",
+        "typescript": "5.9.3"
+    },
+    "packageManager": "pnpm@10.30.0"
+}

package/dist/scripts/check-dependency-versions.js

@@ -0,0 +1,37 @@
+import fs from 'node:fs/promises';
+(async () => {
+    const pkg = JSON.parse(await fs.readFile('package.json', 'utf8'));
+    const errors = [];
+    function isPinned(version) {
+        if (version.startsWith('workspace:')) {
+            return true;
+        }
+        if (version.startsWith('npm:')) {
+            return true;
+        }
+        if (/^\d+\.\d+\.\d+(-\S+)?$/.test(version)) {
+            return true;
+        }
+        if (/^[a-z]+:[a-z]+@\d+$/.test(version)) {
+            return true;
+        }
+        return false;
+    }
+    for (const [dep, version] of Object.entries(pkg.dependencies || {})) {
+        if (!isPinned(version)) {
+            errors.push(`Dependency "${dep}" is not pinned: "${version}"`);
+        }
+    }
+    for (const [dep, version] of Object.entries(pkg.devDependencies || {})) {
+        if (!isPinned(version)) {
+            errors.push(`Dev dependency "${dep}" is not pinned: "${version}"`);
+        }
+    }
+    if (errors.length > 0) {
+        console.error(`\n${errors.join('\n')}\n`);
+        process.exit(1);
+    }
+    else {
+        console.log('All dependencies are pinned.');
+    }
+})();

package/dist/scripts/pull-request-title-check.js

@@ -0,0 +1,17 @@
+import fs from 'node:fs';
+const eventPath = process.env.GITHUB_EVENT_PATH;
+if (!eventPath) {
+    throw new Error('GITHUB_EVENT_PATH environment variable is not set. This script is only meant to run in during a Github workflow.');
+}
+const eventJson = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
+const { title } = eventJson.pull_request;
+const validTypeRegex = /^(feat|fix|chore|refactor)(\([a-zA-Z0-9-]+\))?:\s[a-z].*$/;
+if (!validTypeRegex.test(title)) {
+    console.error(`pull request title does not follow the required format.
+example: "type: description of the change"
+
+- type: "feat", "fix", "chore", or "refactor"
+- first letter of the title after the 'type' needs to be lowercased`);
+    process.exit(1);
+}
+console.info('pull request title is valid');

package/dist/tools/domains.js

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+function formatDnsRecords(records) {
+    if (!records || records.length === 0)
+        return 'No DNS records.';
+    return records
+        .map((r) => `${r.type}:\n  Name: ${r.name}\n  Value: ${r.value}\n  Status: ${r.status}${r.priority !== undefined ? `\n  Priority: ${r.priority}` : ''}`)
+        .join('\n\n');
+}
+export function addDomainTools(server, lettr) {
+    server.registerTool('list-domains', {
+        title: 'List Domains',
+        description: 'List all sending domains registered with your Lettr account. Returns domain names, statuses, and verification state.',
+        inputSchema: {},
+    }, async () => {
+        console.error('Debug - Listing domains');
+        const response = await lettr.get('/domains');
+        const domains = response.data.domains;
+        if (domains.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No domains found.' }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${domains.length} domain${domains.length === 1 ? '' : 's'}:`,
+                },
+                ...domains.map((d) => ({
+                    type: 'text',
+                    text: `Domain: ${d.domain}\nStatus: ${d.status_label}\nCan Send: ${d.can_send}\nCNAME: ${d.cname_status ?? 'not set'}\nDKIM: ${d.dkim_status ?? 'not set'}`,
+                })),
+            ],
+        };
+    });
+    server.registerTool('create-domain', {
+        title: 'Create Domain',
+        description: 'Register a new sending domain with Lettr. The domain will be in a pending state until DNS records are verified and the domain is approved. You MUST display the DNS records to the user so they can set them up.',
+        inputSchema: {
+            domain: z
+                .string()
+                .nonempty()
+                .describe('The domain name to register (e.g., example.com)'),
+        },
+    }, async ({ domain }) => {
+        console.error(`Debug - Creating domain: ${domain}`);
+        const response = await lettr.post('/domains', { domain });
+        const created = response.data;
+        return {
+            content: [
+                { type: 'text', text: 'Domain created successfully.' },
+                {
+                    type: 'text',
+                    text: `Domain: ${created.domain}\nStatus: ${created.status_label}`,
+                },
+                {
+                    type: 'text',
+                    text: `DNS Records to configure:\n\n${formatDnsRecords(created.dns_records)}`,
+                },
+                {
+                    type: 'text',
+                    text: 'IMPORTANT: Display the DNS records above to the user so they can configure them with their DNS provider. After configuration, use verify-domain to start verification.',
+                },
+            ],
+        };
+    });
+    server.registerTool('get-domain', {
+        title: 'Get Domain',
+        description: 'Retrieve details of a sending domain including DNS records, verification status, and tracking domain configuration.',
+        inputSchema: {
+            domain: z
+                .string()
+                .nonempty()
+                .describe('The domain name (e.g., example.com)'),
+        },
+    }, async ({ domain }) => {
+        console.error(`Debug - Getting domain: ${domain}`);
+        const response = await lettr.get(`/domains/${encodeURIComponent(domain)}`);
+        const d = response.data;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Domain: ${d.domain}\nStatus: ${d.status_label}\nCan Send: ${d.can_send}\nCNAME: ${d.cname_status ?? 'not set'}\nDKIM: ${d.dkim_status ?? 'not set'}${d.tracking_domain ? `\nTracking Domain: ${d.tracking_domain}` : ''}`,
+                },
+                {
+                    type: 'text',
+                    text: `DNS Records:\n\n${formatDnsRecords(d.dns_records)}`,
+                },
+            ],
+        };
+    });
+    server.registerTool('delete-domain', {
+        title: 'Delete Domain',
+        description: '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.',
+        inputSchema: {
+            domain: z.string().nonempty().describe('The domain name to delete'),
+        },
+    }, async ({ domain }) => {
+        console.error(`Debug - Deleting domain: ${domain}`);
+        await lettr.delete(`/domains/${encodeURIComponent(domain)}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Domain "${domain}" deleted successfully.`,
+                },
+            ],
+        };
+    });
+    server.registerTool('verify-domain', {
+        title: 'Verify Domain',
+        description: 'Trigger DNS verification for a domain. This checks if the DKIM and CNAME records are correctly configured. The domain status will update once records are verified.',
+        inputSchema: {
+            domain: z.string().nonempty().describe('The domain name to verify'),
+        },
+    }, async ({ domain }) => {
+        console.error(`Debug - Verifying domain: ${domain}`);
+        const response = await lettr.post(`/domains/${encodeURIComponent(domain)}/verify`);
+        const result = response.data;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Domain verification triggered.\nDomain: ${result.domain}\nStatus: ${result.status_label}\nCNAME: ${result.cname_status ?? 'not set'}\nDKIM: ${result.dkim_status ?? 'not set'}`,
+                },
+                {
+                    type: 'text',
+                    text: `DNS Records:\n\n${formatDnsRecords(result.dns_records)}`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/emails.js

@@ -0,0 +1,191 @@
+import fs from 'node:fs/promises';
+import { z } from 'zod';
+export function addEmailTools(server, lettr, { senderEmailAddress, replierEmailAddress, }) {
+    server.registerTool('send-email', {
+        title: 'Send Email',
+        description: `**Purpose:** Send a transactional email to one or more recipients. Supports HTML, plain text, templates with merge tags, attachments, 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
+
+**Key trigger phrases:** "Send an email", "Email this to", "Notify", "Send a message", "Reply to them"`,
+        inputSchema: {
+            to: z
+                .array(z.email())
+                .min(1)
+                .max(50)
+                .describe('Array of recipient email addresses (1-50 recipients)'),
+            subject: z.string().describe('Email subject line'),
+            text: z
+                .string()
+                .optional()
+                .describe('Plain text email content. At least one of html, text, or template_slug is required.'),
+            html: z
+                .string()
+                .optional()
+                .describe('HTML email content. At least one of html, text, or template_slug is required.'),
+            template_slug: z
+                .string()
+                .optional()
+                .describe("Template slug to use for email content. When provided, the template's HTML will be used. Use get-merge-tags to discover required substitution_data keys."),
+            template_version: z
+                .number()
+                .optional()
+                .describe('Specific template version to use. If not provided, the active version is used.'),
+            project_id: z
+                .number()
+                .optional()
+                .describe("Project ID containing the template. If not provided, the team's default project is used."),
+            substitution_data: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('Variables for template substitution (e.g. { "first_name": "John", "company": "Acme" }). Use with template_slug or inline {{variables}} in html/text.'),
+            cc: z
+                .array(z.email())
+                .optional()
+                .describe('Optional array of CC email addresses. You MUST ask the user for this parameter. Under no circumstance provide it yourself'),
+            bcc: z
+                .array(z.email())
+                .optional()
+                .describe('Optional array of BCC email addresses. You MUST ask the user for this parameter. Under no circumstance provide it yourself'),
+            from_name: z
+                .string()
+                .optional()
+                .describe('Sender display name (e.g. "Acme Support")'),
+            reply_to_name: z.string().optional().describe('Reply-To display name'),
+            tag: z
+                .string()
+                .optional()
+                .describe('Tag for tracking and analytics (max 64 characters)'),
+            metadata: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('Custom metadata for tracking (e.g. { "user_id": "123", "campaign": "onboarding" })'),
+            options: z
+                .object({
+                click_tracking: z
+                    .boolean()
+                    .optional()
+                    .describe('Enable click tracking for links'),
+                open_tracking: z
+                    .boolean()
+                    .optional()
+                    .describe('Enable open tracking via pixel'),
+                transactional: z
+                    .boolean()
+                    .optional()
+                    .describe('Mark as transactional (not marketing)'),
+                inline_css: z
+                    .boolean()
+                    .optional()
+                    .describe('Inline CSS styles in HTML'),
+                perform_substitutions: z
+                    .boolean()
+                    .optional()
+                    .describe('Perform variable substitutions in content'),
+            })
+                .optional()
+                .describe('Email delivery options'),
+            attachments: z
+                .array(z.object({
+                name: z
+                    .string()
+                    .describe('Filename with extension (e.g. "report.pdf")'),
+                type: z.string().describe('MIME type (e.g. "application/pdf")'),
+                data: z
+                    .string()
+                    .optional()
+                    .describe('Base64-encoded file content'),
+                filePath: z
+                    .string()
+                    .optional()
+                    .describe('Local file path to read and attach (will be base64 encoded automatically)'),
+            }))
+                .optional()
+                .describe('Array of file attachments. Each needs name, type, and either data (base64) or filePath.'),
+            ...(!senderEmailAddress
+                ? {
+                    from: z
+                        .email()
+                        .nonempty()
+                        .describe('Sender email address. You MUST ask the user for this parameter. Under no circumstance provide it yourself'),
+                }
+                : {}),
+            ...(!replierEmailAddress
+                ? {
+                    reply_to: z
+                        .email()
+                        .optional()
+                        .describe('Optional reply-to email address. You MUST ask the user for this parameter. Under no circumstance provide it yourself'),
+                }
+                : {}),
+        },
+    }, async ({ from, to, subject, text, html, template_slug, template_version, project_id, substitution_data, cc, bcc, reply_to, from_name, reply_to_name, tag, metadata, options, attachments, }) => {
+        const fromAddress = from ?? senderEmailAddress;
+        const replyToAddress = reply_to ?? replierEmailAddress;
+        if (typeof fromAddress !== 'string') {
+            throw new Error('from argument must be provided.');
+        }
+        console.error(`Debug - Sending email with from: ${fromAddress}`);
+        const body = {
+            from: fromAddress,
+            to,
+            subject,
+        };
+        if (from_name)
+            body.from_name = from_name;
+        if (text)
+            body.text = text;
+        if (html)
+            body.html = html;
+        if (template_slug)
+            body.template_slug = template_slug;
+        if (template_version)
+            body.template_version = template_version;
+        if (project_id)
+            body.project_id = project_id;
+        if (substitution_data)
+            body.substitution_data = substitution_data;
+        if (cc)
+            body.cc = cc;
+        if (bcc)
+            body.bcc = bcc;
+        if (replyToAddress)
+            body.reply_to = replyToAddress;
+        if (reply_to_name)
+            body.reply_to_name = reply_to_name;
+        if (tag)
+            body.tag = tag;
+        if (metadata)
+            body.metadata = metadata;
+        if (options)
+            body.options = options;
+        if (attachments && attachments.length > 0) {
+            body.attachments = await Promise.all(attachments.map(async (att) => {
+                let data = att.data;
+                if (!data && att.filePath) {
+                    const fileBuffer = await fs.readFile(att.filePath);
+                    data = fileBuffer.toString('base64');
+                }
+                if (!data) {
+                    throw new Error(`Attachment "${att.name}" requires either data (base64) or filePath.`);
+                }
+                return { name: att.name, type: att.type, data };
+            }));
+        }
+        const response = await lettr.post('/emails', body);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Email sent successfully! Request ID: ${response.data.request_id}, Accepted: ${response.data.accepted}, Rejected: ${response.data.rejected}`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+export * from './domains.js';
+export * from './emails.js';
+export * from './templates.js';
+export * from './webhooks.js';

package/dist/tools/templates.js

@@ -0,0 +1,265 @@
+import { z } from 'zod';
+export function addTemplateTools(server, lettr) {
+    server.registerTool('list-templates', {
+        title: 'List Templates',
+        description: `**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`,
+        inputSchema: {
+            project_id: z
+                .number()
+                .optional()
+                .describe("Project ID to filter templates. If not provided, uses the team's default project."),
+            per_page: z
+                .number()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe('Number of results per page (1-100). Default: 25'),
+            page: z.number().min(1).optional().describe('Page number. Default: 1'),
+        },
+    }, async ({ project_id, per_page, page }) => {
+        console.error('Debug - Listing templates');
+        const query = {};
+        if (project_id)
+            query.project_id = project_id;
+        if (per_page)
+            query.per_page = per_page;
+        if (page)
+            query.page = page;
+        const response = await lettr.get('/templates', query);
+        const templates = response.data.templates;
+        const pagination = response.data.pagination;
+        if (templates.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No templates found.' }],
+            };
+        }
+        const templateList = templates
+            .map((t) => `- ${t.name} (slug: ${t.slug}) | Project: ${t.project_id} | Updated: ${t.updated_at}`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${pagination.total} template(s) (page ${pagination.current_page}/${pagination.last_page}):\n\n${templateList}`,
+                },
+            ],
+        };
+    });
+    server.registerTool('get-template', {
+        title: 'Get Template',
+        description: 'Retrieve full details of a template by its slug, including active version HTML/JSON content and version count.',
+        inputSchema: {
+            slug: z
+                .string()
+                .nonempty()
+                .describe('The template slug (URL-friendly identifier)'),
+            project_id: z
+                .number()
+                .optional()
+                .describe("Project ID to find the template in. If not provided, uses the team's default project."),
+        },
+    }, async ({ slug, project_id }) => {
+        console.error(`Debug - Getting template: ${slug}`);
+        const query = {};
+        if (project_id)
+            query.project_id = project_id;
+        const response = await lettr.get(`/templates/${encodeURIComponent(slug)}`, query);
+        const t = response.data;
+        let details = 'Template Details:\n';
+        details += `- Name: ${t.name}\n`;
+        details += `- Slug: ${t.slug}\n`;
+        details += `- Project ID: ${t.project_id}\n`;
+        details += `- Folder ID: ${t.folder_id}\n`;
+        details += `- Active Version: ${t.active_version ?? 'none'}\n`;
+        details += `- Total Versions: ${t.versions_count}\n`;
+        details += `- Created: ${t.created_at}\n`;
+        details += `- Updated: ${t.updated_at}\n`;
+        if (t.html) {
+            details += `\n--- HTML Content ---\n${t.html}\n`;
+        }
+        return {
+            content: [{ type: 'text', text: details }],
+        };
+    });
+    server.registerTool('create-template', {
+        title: 'Create Template',
+        description: '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.',
+        inputSchema: {
+            name: z
+                .string()
+                .nonempty()
+                .describe('Name of the template (max 255 characters)'),
+            html: z
+                .string()
+                .optional()
+                .describe('HTML content for the template. Mutually exclusive with json. Use {{VARIABLE}} syntax for merge tags.'),
+            json: z
+                .string()
+                .optional()
+                .describe('JSON content for Topol visual editor templates. Mutually exclusive with html.'),
+            project_id: z
+                .number()
+                .optional()
+                .describe("Project ID to create the template in. If not provided, uses the team's default project."),
+            folder_id: z
+                .number()
+                .optional()
+                .describe('Folder ID within the project. If not provided, uses the first folder.'),
+        },
+    }, async ({ name, html, json, project_id, folder_id }) => {
+        console.error(`Debug - Creating template: ${name}`);
+        const body = { name };
+        if (html)
+            body.html = html;
+        if (json)
+            body.json = json;
+        if (project_id)
+            body.project_id = project_id;
+        if (folder_id)
+            body.folder_id = folder_id;
+        const response = await lettr.post('/templates', body);
+        const t = response.data;
+        const mergeTags = t.merge_tags.length > 0
+            ? `\nMerge Tags: ${t.merge_tags.map((m) => `${m.key}${m.required ? ' (required)' : ''}`).join(', ')}`
+            : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Template created successfully!\nName: ${t.name}\nSlug: ${t.slug}\nVersion: ${t.active_version}${mergeTags}`,
+                },
+            ],
+        };
+    });
+    server.registerTool('update-template', {
+        title: 'Update Template',
+        description: "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.",
+        inputSchema: {
+            slug: z.string().nonempty().describe('The template slug to update'),
+            name: z.string().optional().describe('New name for the template'),
+            html: z
+                .string()
+                .optional()
+                .describe('New HTML content. Creates a new active version. Mutually exclusive with json.'),
+            json: z
+                .string()
+                .optional()
+                .describe('New JSON content for visual editor. Creates a new active version. Mutually exclusive with html.'),
+            project_id: z
+                .number()
+                .optional()
+                .describe("Project ID to find the template in. If not provided, uses the team's default project."),
+        },
+    }, async ({ slug, name, html, json, project_id }) => {
+        console.error(`Debug - Updating template: ${slug}`);
+        const body = {};
+        if (name)
+            body.name = name;
+        if (html)
+            body.html = html;
+        if (json)
+            body.json = json;
+        if (project_id)
+            body.project_id = project_id;
+        const response = await lettr.put(`/templates/${encodeURIComponent(slug)}`, body);
+        const t = response.data;
+        const mergeTags = t.merge_tags.length > 0
+            ? `\nMerge Tags: ${t.merge_tags.map((m) => `${m.key}${m.required ? ' (required)' : ''}`).join(', ')}`
+            : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Template updated successfully!\nName: ${t.name}\nSlug: ${t.slug}\nActive Version: ${t.active_version}${mergeTags}`,
+                },
+            ],
+        };
+    });
+    server.registerTool('delete-template', {
+        title: 'Delete Template',
+        description: '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.',
+        inputSchema: {
+            slug: z.string().nonempty().describe('The template slug to delete'),
+            project_id: z
+                .number()
+                .optional()
+                .describe("Project ID to find the template in. If not provided, uses the team's default project."),
+        },
+    }, async ({ slug, project_id }) => {
+        console.error(`Debug - Deleting template: ${slug}`);
+        const query = {};
+        if (project_id)
+            query.project_id = project_id;
+        await lettr.delete(`/templates/${encodeURIComponent(slug)}`, query);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Template "${slug}" deleted successfully.`,
+                },
+            ],
+        };
+    });
+    server.registerTool('get-merge-tags', {
+        title: 'Get Template Merge Tags',
+        description: '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.',
+        inputSchema: {
+            slug: z.string().nonempty().describe('The template slug'),
+            project_id: z
+                .number()
+                .optional()
+                .describe("Project ID to find the template in. If not provided, uses the team's default project."),
+            version: z
+                .number()
+                .optional()
+                .describe('Template version number. If not provided, uses the active version.'),
+        },
+    }, async ({ slug, project_id, version }) => {
+        console.error(`Debug - Getting merge tags for template: ${slug}`);
+        const query = {};
+        if (project_id)
+            query.project_id = project_id;
+        if (version)
+            query.version = version;
+        const response = await lettr.get(`/templates/${encodeURIComponent(slug)}/merge-tags`, query);
+        const { template_slug, version: ver, merge_tags } = response.data;
+        if (merge_tags.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Template "${template_slug}" (version ${ver}) has no merge tags.`,
+                    },
+                ],
+            };
+        }
+        const formatTag = (tag) => {
+            let line = `- ${tag.key}${tag.required ? ' (required)' : ' (optional)'}`;
+            if (tag.type)
+                line += ` [${tag.type}]`;
+            if (tag.children && tag.children.length > 0) {
+                line += ' (loop):';
+                for (const child of tag.children) {
+                    line += `\n    - ${child.key}${child.type ? ` [${child.type}]` : ''}`;
+                }
+            }
+            return line;
+        };
+        const tagList = merge_tags.map(formatTag).join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Merge tags for "${template_slug}" (version ${ver}):\n\n${tagList}`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/webhooks.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+export function addWebhookTools(server, lettr) {
+    server.registerTool('list-webhooks', {
+        title: 'List Webhooks',
+        description: 'List all webhooks configured for your Lettr account. Returns webhook URLs, statuses, and subscribed event types.',
+        inputSchema: {},
+    }, async () => {
+        console.error('Debug - Listing webhooks');
+        const response = await lettr.get('/webhooks');
+        const webhooks = response.data.webhooks;
+        if (webhooks.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No webhooks found.' }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${webhooks.length} webhook${webhooks.length === 1 ? '' : 's'}:`,
+                },
+                ...webhooks.map((w) => ({
+                    type: 'text',
+                    text: `URL: ${w.url}\nStatus: ${w.status}\nEvents: ${w.event_types.join(', ')}\nID: ${w.id}`,
+                })),
+            ],
+        };
+    });
+    server.registerTool('get-webhook', {
+        title: 'Get Webhook',
+        description: 'Retrieve details of a specific webhook including its status, event types, and delivery information.',
+        inputSchema: {
+            id: z.number().describe('The webhook ID'),
+        },
+    }, async ({ id }) => {
+        console.error(`Debug - Getting webhook: ${id}`);
+        const response = await lettr.get(`/webhooks/${id}`);
+        const w = response.data;
+        let details = 'Webhook Details:\n';
+        details += `- ID: ${w.id}\n`;
+        details += `- URL: ${w.url}\n`;
+        details += `- Status: ${w.status}\n`;
+        details += `- Events: ${w.event_types.join(', ')}\n`;
+        details += `- Created: ${w.created_at}\n`;
+        details += `- Updated: ${w.updated_at}\n`;
+        if (w.last_delivery_at) {
+            details += `- Last Delivery: ${w.last_delivery_at} (${w.last_delivery_status})\n`;
+        }
+        return {
+            content: [{ type: 'text', text: details }],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "lettr-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the Lettr email API — send transactional emails, manage templates, domains, and webhooks from any AI assistant",
+  "keywords": [
+    "lettr",
+    "email",
+    "email-api",
+    "transactional-email",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "claude",
+    "cursor",
+    "templates",
+    "email-templates"
+  ],
+  "homepage": "https://lettr.com",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "lettr-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', '755')\"",
+    "prepare": "npm run build",
+    "inspector": "npx @modelcontextprotocol/inspector@latest",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.26.0",
+    "minimist": "1.2.8",
+    "zod": "4.3.6"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.2",
+    "@types/minimist": "1.2.5",
+    "@types/node": "25.0.3",
+    "typescript": "5.9.3"
+  },
+  "packageManager": "pnpm@10.30.0"
+}