lettr-mcp 1.1.1 → 1.3.0

package/README.md

@@ -19,6 +19,7 @@ The official [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) se
 - **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, 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
@@ -139,6 +140,44 @@ Environment variables:
 |------|-------------|
 | `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 |

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, addProjectTools, addSystemTools, addTemplateTools, addWebhookTools, } from './tools/index.js';
+import { addAudienceContactTools, addAudienceListTools, addAudienceMembershipTools, addAudiencePropertyTools, addAudienceSegmentTools, addAudienceTopicTools, addCampaignTools, 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;
@@ -25,6 +25,13 @@ 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);
+addCampaignTools(server, lettr);
 addSystemTools(server, lettr);
 async function main() {
     const transport = new StdioServerTransport();

package/dist/lettr.js

@@ -18,7 +18,11 @@ 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);
         }
@@ -45,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.1.1",
+    "version": "1.3.0",
     "description": "MCP server for the Lettr email API — send transactional emails, manage templates, domains, and webhooks from any AI assistant",
     "keywords": [
         "lettr",

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).`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/audience-memberships.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+export function addAudienceMembershipTools(server, lettr) {
+    server.registerTool('attach-contact-to-list', {
+        title: 'Attach Contact to List',
+        description: 'Add a single contact to a single list. Both the contact and the list must belong to your team.',
+        inputSchema: {
+            contactId: z.string().nonempty().describe('The contact ID'),
+            listId: z.string().nonempty().describe('The list ID'),
+        },
+    }, async ({ contactId, listId }) => {
+        await lettr.post(`/audience/contacts/${encodeURIComponent(contactId)}/lists/${encodeURIComponent(listId)}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Contact "${contactId}" attached to list "${listId}".`,
+                },
+            ],
+        };
+    });
+    server.registerTool('detach-contact-from-list', {
+        title: 'Detach Contact from List',
+        description: 'Remove a single contact from a single list.',
+        inputSchema: {
+            contactId: z.string().nonempty().describe('The contact ID'),
+            listId: z.string().nonempty().describe('The list ID'),
+        },
+    }, async ({ contactId, listId }) => {
+        await lettr.delete(`/audience/contacts/${encodeURIComponent(contactId)}/lists/${encodeURIComponent(listId)}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Contact "${contactId}" detached from list "${listId}".`,
+                },
+            ],
+        };
+    });
+    server.registerTool('subscribe-contact-to-topic', {
+        title: 'Subscribe Contact to Topic',
+        description: 'Subscribe a single contact to a single topic. Both must belong to your team.',
+        inputSchema: {
+            contactId: z.string().nonempty().describe('The contact ID'),
+            topicId: z.string().nonempty().describe('The topic ID'),
+        },
+    }, async ({ contactId, topicId }) => {
+        await lettr.post(`/audience/contacts/${encodeURIComponent(contactId)}/topics/${encodeURIComponent(topicId)}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Contact "${contactId}" subscribed to topic "${topicId}".`,
+                },
+            ],
+        };
+    });
+    server.registerTool('unsubscribe-contact-from-topic', {
+        title: 'Unsubscribe Contact from Topic',
+        description: 'Unsubscribe a single contact from a single topic.',
+        inputSchema: {
+            contactId: z.string().nonempty().describe('The contact ID'),
+            topicId: z.string().nonempty().describe('The topic ID'),
+        },
+    }, async ({ contactId, topicId }) => {
+        await lettr.delete(`/audience/contacts/${encodeURIComponent(contactId)}/topics/${encodeURIComponent(topicId)}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Contact "${contactId}" unsubscribed from topic "${topicId}".`,
+                },
+            ],
+        };
+    });
+    server.registerTool('bulk-attach-contacts-to-lists', {
+        title: 'Bulk Attach Contacts to Lists',
+        description: '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.',
+        inputSchema: {
+            contact_ids: z
+                .array(z.string().nonempty())
+                .min(1)
+                .max(1000)
+                .describe('Contact IDs to attach (max 1000)'),
+            list_ids: z
+                .array(z.string().nonempty())
+                .min(1)
+                .max(50)
+                .describe('List IDs to attach the contacts to (max 50)'),
+        },
+    }, async ({ contact_ids, list_ids }) => {
+        const response = await lettr.post('/audience/contacts/lists/bulk', { contact_ids, list_ids });
+        const { attached, already_attached, total_pairs } = response.data;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Attached ${attached} of ${total_pairs} contact-list pair(s); ${already_attached} were already attached.`,
+                },
+            ],
+        };
+    });
+    server.registerTool('bulk-detach-contacts-from-lists', {
+        title: 'Bulk Detach Contacts from Lists',
+        description: '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.',
+        inputSchema: {
+            contact_ids: z
+                .array(z.string().nonempty())
+                .min(1)
+                .max(1000)
+                .describe('Contact IDs to detach (max 1000)'),
+            list_ids: z
+                .array(z.string().nonempty())
+                .min(1)
+                .max(50)
+                .describe('List IDs to detach the contacts from (max 50)'),
+        },
+    }, async ({ contact_ids, list_ids }) => {
+        const response = await lettr.delete('/audience/contacts/lists/bulk', { contact_ids, list_ids });
+        const { detached, not_present, total_pairs } = response.data;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Detached ${detached} of ${total_pairs} contact-list pair(s); ${not_present} were not attached.`,
+                },
+            ],
+        };
+    });
+}