lettr-mcp 1.0.0 → 1.2.0

package/README.md

@@ -14,10 +14,13 @@ The official [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) se
 
 ## 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.
+- **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, scheduled delivery, and inspecting sent messages and events.
+- **Templates** — List, create, get, update, and delete email templates. Retrieve rendered HTML and [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.
+- **Webhooks** — List, create, get, update, and delete [webhook configurations](https://docs.lettr.com/learn/webhooks/introduction) 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
 
@@ -92,6 +95,12 @@ Environment variables:
 | 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
 
@@ -103,6 +112,7 @@ Environment variables:
 | `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
 
@@ -120,6 +130,60 @@ Environment variables:
 |------|-------------|
 | `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
 

package/dist/index.js

@@ -4,7 +4,7 @@ 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';
+import { addAudienceContactTools, addAudienceListTools, addAudienceMembershipTools, addAudiencePropertyTools, addAudienceSegmentTools, addAudienceTopicTools, addDomainTools, addEmailTools, addProjectTools, addSystemTools, 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;
@@ -24,6 +24,14 @@ addEmailTools(server, lettr, { senderEmailAddress, replierEmailAddress });
 addTemplateTools(server, lettr);
 addDomainTools(server, lettr);
 addWebhookTools(server, lettr);
+addProjectTools(server, lettr);
+addAudienceListTools(server, lettr);
+addAudienceContactTools(server, lettr);
+addAudienceMembershipTools(server, lettr);
+addAudienceTopicTools(server, lettr);
+addAudiencePropertyTools(server, lettr);
+addAudienceSegmentTools(server, lettr);
+addSystemTools(server, lettr);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/lettr.js

@@ -18,20 +18,25 @@ export class LettrClient {
             Accept: 'application/json',
         };
         const options = { method, headers };
-        if (body && (method === 'POST' || method === 'PUT' || method === 'PATCH')) {
+        if (body &&
+            (method === 'POST' ||
+                method === 'PUT' ||
+                method === 'PATCH' ||
+                method === 'DELETE')) {
             headers['Content-Type'] = 'application/json';
             options.body = JSON.stringify(body);
         }
         const response = await fetch(url.toString(), options);
-        const json = await response.json();
+        const hasBody = response.status !== 204 && response.headers.get('content-length') !== '0';
+        const json = hasBody ? await response.json() : undefined;
         if (!response.ok) {
-            const err = json;
+            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}`);
+            throw new Error(`Lettr API error (${response.status}): ${err.message ?? response.statusText}${detail}`);
         }
         return json;
     }
@@ -44,7 +49,10 @@ export class LettrClient {
     async put(path, body, query) {
         return this.request('PUT', path, body, query);
     }
-    async delete(path, query) {
-        return this.request('DELETE', path, undefined, query);
+    async patch(path, body, query) {
+        return this.request('PATCH', path, body, query);
+    }
+    async delete(path, body, query) {
+        return this.request('DELETE', path, body, query);
     }
 }

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lettr-mcp",
-    "version": "1.0.0",
+    "version": "1.2.0",
     "description": "MCP server for the Lettr email API — send transactional emails, manage templates, domains, and webhooks from any AI assistant",
     "keywords": [
         "lettr",
@@ -16,6 +16,13 @@
         "email-templates"
     ],
     "homepage": "https://lettr.com",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/lettr-com/lettr-mcp.git"
+    },
+    "bugs": {
+        "url": "https://github.com/lettr-com/lettr-mcp/issues"
+    },
     "license": "MIT",
     "type": "module",
     "bin": {

package/dist/tools/audience-contacts.js

@@ -0,0 +1,256 @@
+import { z } from 'zod';
+// The API stores every custom property value as a string (max 1000 chars).
+// On update, a null value removes the property from the contact.
+const createPropertyValue = z.string().max(1000);
+const updatePropertyValue = z.string().max(1000).nullable();
+function formatContact(c) {
+    const props = Object.entries(c.properties ?? {});
+    const lines = [
+        `ID: ${c.id}`,
+        `Email: ${c.email}`,
+        `Status: ${c.status}`,
+        `Created: ${c.created_at}`,
+        `Lists: ${c.lists.length > 0 ? c.lists.map((l) => `${l.name} (${l.id})`).join(', ') : 'none'}`,
+        `Topics: ${c.topics.length > 0 ? c.topics.map((t) => `${t.name} (${t.id})`).join(', ') : 'none'}`,
+    ];
+    if (props.length > 0) {
+        lines.push(`Properties:\n${props.map(([k, v]) => `  ${k}: ${JSON.stringify(v)}`).join('\n')}`);
+    }
+    return lines.join('\n');
+}
+export function addAudienceContactTools(server, lettr) {
+    server.registerTool('list-audience-contacts', {
+        title: 'List Audience Contacts',
+        description: 'List audience contacts with pagination and optional filters. Filter by free-text search (email or name), status, a specific list, or a specific segment.',
+        inputSchema: {
+            per_page: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe('Results per page (1-100, default 20)'),
+            page: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('Page number (default 1)'),
+            search: z
+                .string()
+                .max(255)
+                .optional()
+                .describe('Search by email address or contact name'),
+            status: z
+                .enum([
+                'subscribed',
+                'unsubscribed',
+                'bounced',
+                'complained',
+                'unverified',
+            ])
+                .optional()
+                .describe('Filter by contact status'),
+            list_id: z
+                .string()
+                .optional()
+                .describe('Filter to contacts in a specific list (must belong to your team)'),
+            segment_id: z
+                .string()
+                .optional()
+                .describe('Filter to contacts matching a specific segment (must belong to your team)'),
+        },
+    }, async ({ per_page, page, search, status, list_id, segment_id }) => {
+        const query = {};
+        if (per_page)
+            query.per_page = per_page;
+        if (page)
+            query.page = page;
+        if (search)
+            query.search = search;
+        if (status)
+            query.status = status;
+        if (list_id)
+            query.list_id = list_id;
+        if (segment_id)
+            query.segment_id = segment_id;
+        const response = await lettr.get('/audience/contacts', query);
+        const { contacts, pagination } = response.data;
+        if (contacts.length === 0) {
+            return { content: [{ type: 'text', text: 'No contacts found.' }] };
+        }
+        const lines = contacts
+            .map((c) => `- ${c.email} (id: ${c.id}, status: ${c.status})`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${pagination.total} contact(s) — page ${pagination.current_page}/${pagination.last_page}:\n\n${lines}`,
+                },
+            ],
+        };
+    });
+    server.registerTool('get-audience-contact', {
+        title: 'Get Audience Contact',
+        description: 'Retrieve a single contact by ID, including status, custom properties, and the lists and topics it belongs to.',
+        inputSchema: {
+            contactId: z.string().nonempty().describe('The contact ID'),
+        },
+    }, async ({ contactId }) => {
+        const response = await lettr.get(`/audience/contacts/${encodeURIComponent(contactId)}`);
+        return {
+            content: [
+                { type: 'text', text: 'Contact details:' },
+                { type: 'text', text: formatContact(response.data) },
+            ],
+        };
+    });
+    server.registerTool('create-audience-contact', {
+        title: 'Create Audience Contact',
+        description: `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.`,
+        inputSchema: {
+            email: z.email().max(255).describe('Contact email address'),
+            list_id: z
+                .string()
+                .optional()
+                .describe('Optional list ID to add the contact to'),
+            properties: z
+                .record(z.string(), createPropertyValue)
+                .optional()
+                .describe('Custom property values, each as a string (max 1000 chars). Each key must match a property defined for the team.'),
+            double_opt_in: z
+                .object({
+                from: z
+                    .email()
+                    .max(255)
+                    .describe('Sender email for the confirmation email'),
+                from_name: z
+                    .string()
+                    .max(255)
+                    .optional()
+                    .describe('Sender display name'),
+                subject: z
+                    .string()
+                    .max(998)
+                    .describe('Subject line of the confirmation email'),
+                template_slug: z
+                    .string()
+                    .max(255)
+                    .describe('Template slug used for the confirmation email'),
+                redirect_url: z
+                    .url()
+                    .max(2048)
+                    .describe('URL the contact is sent to after confirming'),
+            })
+                .optional()
+                .describe('Double opt-in configuration. When set, the contact is created unverified until they click the confirmation link.'),
+        },
+    }, async ({ email, list_id, properties, double_opt_in }) => {
+        const body = { email };
+        if (list_id)
+            body.list_id = list_id;
+        if (properties)
+            body.properties = properties;
+        if (double_opt_in)
+            body.double_opt_in = double_opt_in;
+        const response = await lettr.post('/audience/contacts', body);
+        return {
+            content: [
+                { type: 'text', text: 'Contact created successfully.' },
+                { type: 'text', text: formatContact(response.data) },
+            ],
+        };
+    });
+    server.registerTool('bulk-create-audience-contacts', {
+        title: 'Bulk Create Audience Contacts',
+        description: '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).',
+        inputSchema: {
+            emails: z
+                .array(z.email().max(255))
+                .min(1)
+                .max(1000)
+                .describe('Email addresses to create contacts for (max 1000)'),
+            list_id: z
+                .string()
+                .optional()
+                .describe('Optional list ID to add all contacts to'),
+            properties: z
+                .record(z.string(), createPropertyValue)
+                .optional()
+                .describe('Custom property values applied to every contact created in this batch, each as a string (max 1000 chars). Each key must match a property defined for the team.'),
+        },
+    }, async ({ emails, list_id, properties }) => {
+        const body = { emails };
+        if (list_id)
+            body.list_id = list_id;
+        if (properties)
+            body.properties = properties;
+        const response = await lettr.post('/audience/contacts/bulk', body);
+        const { created, already_existed } = response.data;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Created ${created} contact(s); ${already_existed} already existed.`,
+                },
+            ],
+        };
+    });
+    server.registerTool('update-audience-contact', {
+        title: 'Update Audience Contact',
+        description: `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.`,
+        inputSchema: {
+            contactId: z.string().nonempty().describe('The contact ID to update'),
+            email: z
+                .email()
+                .max(255)
+                .optional()
+                .describe('New email address (must remain unique within the team)'),
+            status: z
+                .enum(['subscribed', 'unsubscribed'])
+                .optional()
+                .describe('New subscription status'),
+            properties: z
+                .record(z.string(), updatePropertyValue)
+                .optional()
+                .describe('Partial property update; each value is a string (max 1000 chars). A property set to null is removed from the contact.'),
+        },
+    }, async ({ contactId, ...rest }) => {
+        const body = {};
+        for (const [key, value] of Object.entries(rest)) {
+            if (value !== undefined)
+                body[key] = value;
+        }
+        const response = await lettr.patch(`/audience/contacts/${encodeURIComponent(contactId)}`, body);
+        return {
+            content: [
+                { type: 'text', text: 'Contact updated successfully.' },
+                { type: 'text', text: formatContact(response.data) },
+            ],
+        };
+    });
+    server.registerTool('delete-audience-contact', {
+        title: 'Delete Audience Contact',
+        description: '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.',
+        inputSchema: {
+            contactId: z.string().nonempty().describe('The contact ID to delete'),
+        },
+    }, async ({ contactId }) => {
+        await lettr.delete(`/audience/contacts/${encodeURIComponent(contactId)}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Contact "${contactId}" deleted successfully.`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/audience-lists.js

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+function formatList(l) {
+    return `ID: ${l.id}\nName: ${l.name}\nContacts: ${l.contacts_count}`;
+}
+export function addAudienceListTools(server, lettr) {
+    server.registerTool('list-audience-lists', {
+        title: 'List Audience Lists',
+        description: 'List the audience (contact) lists for your team, with pagination. Use this to discover list IDs to pass to contact and segment tools.',
+        inputSchema: {
+            per_page: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe('Results per page (1-100, default 20)'),
+            page: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('Page number (default 1)'),
+        },
+    }, async ({ per_page, page }) => {
+        const query = {};
+        if (per_page)
+            query.per_page = per_page;
+        if (page)
+            query.page = page;
+        const response = await lettr.get('/audience/lists', query);
+        const { lists, pagination } = response.data;
+        if (lists.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No audience lists found.' }],
+            };
+        }
+        const lines = lists
+            .map((l) => `- ${l.name} (id: ${l.id}, contacts: ${l.contacts_count})`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${pagination.total} list(s) — page ${pagination.current_page}/${pagination.last_page}:\n\n${lines}`,
+                },
+            ],
+        };
+    });
+    server.registerTool('create-audience-list', {
+        title: 'Create Audience List',
+        description: 'Create a new audience list. The name must be unique within the team.',
+        inputSchema: {
+            name: z
+                .string()
+                .nonempty()
+                .max(255)
+                .describe('List name (must be unique within the team)'),
+        },
+    }, async ({ name }) => {
+        const response = await lettr.post('/audience/lists', { name });
+        return {
+            content: [
+                { type: 'text', text: 'Audience list created successfully.' },
+                { type: 'text', text: formatList(response.data) },
+            ],
+        };
+    });
+    server.registerTool('get-audience-list', {
+        title: 'Get Audience List',
+        description: 'Retrieve a single audience list by its ID, including its current contact count.',
+        inputSchema: {
+            listId: z.string().nonempty().describe('The list ID'),
+        },
+    }, async ({ listId }) => {
+        const response = await lettr.get(`/audience/lists/${encodeURIComponent(listId)}`);
+        return {
+            content: [
+                { type: 'text', text: 'Audience list details:' },
+                { type: 'text', text: formatList(response.data) },
+            ],
+        };
+    });
+    server.registerTool('update-audience-list', {
+        title: 'Update Audience List',
+        description: 'Rename an audience list. The new name must remain unique within the team.',
+        inputSchema: {
+            listId: z.string().nonempty().describe('The list ID to update'),
+            name: z
+                .string()
+                .nonempty()
+                .max(255)
+                .describe('New list name (must remain unique within the team)'),
+        },
+    }, async ({ listId, name }) => {
+        const response = await lettr.patch(`/audience/lists/${encodeURIComponent(listId)}`, { name });
+        return {
+            content: [
+                { type: 'text', text: 'Audience list updated successfully.' },
+                { type: 'text', text: formatList(response.data) },
+            ],
+        };
+    });
+    server.registerTool('delete-audience-list', {
+        title: 'Delete Audience List',
+        description: '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.',
+        inputSchema: {
+            listId: z.string().nonempty().describe('The list ID to delete'),
+        },
+    }, async ({ listId }) => {
+        await lettr.delete(`/audience/lists/${encodeURIComponent(listId)}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Audience list "${listId}" deleted successfully.`,
+                },
+            ],
+        };
+    });
+    server.registerTool('bulk-delete-audience-lists', {
+        title: 'Bulk Delete Audience Lists',
+        description: '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.',
+        inputSchema: {
+            list_ids: z
+                .array(z.string().nonempty())
+                .min(1)
+                .max(50)
+                .describe('1–50 list IDs to delete (all must belong to your team)'),
+        },
+    }, async ({ list_ids }) => {
+        const response = await lettr.delete('/audience/lists/bulk', { list_ids });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Deleted ${response.data.deleted} list(s).`,
+                },
+            ],
+        };
+    });
+}