lettr-mcp 1.1.1 → 1.2.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, 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,12 @@ 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();

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

package/dist/tools/audience-properties.js

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+function formatProperty(p) {
+    return [
+        `ID: ${p.id}`,
+        `Name: ${p.name}`,
+        `Type: ${p.type}`,
+        `Fallback: ${p.fallback_value ?? '(none)'}`,
+    ].join('\n');
+}
+export function addAudiencePropertyTools(server, lettr) {
+    server.registerTool('list-audience-properties', {
+        title: 'List Audience Properties',
+        description: 'List the custom contact properties defined for your team, with pagination. Use this to discover which property keys are valid when creating or updating contacts.',
+        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/properties', query);
+        const { properties, pagination } = response.data;
+        if (properties.length === 0) {
+            return { content: [{ type: 'text', text: 'No properties found.' }] };
+        }
+        const lines = properties
+            .map((p) => `- ${p.name} (id: ${p.id}, type: ${p.type}${p.fallback_value !== null ? `, fallback: ${p.fallback_value}` : ''})`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${pagination.total} property(ies) — page ${pagination.current_page}/${pagination.last_page}:\n\n${lines}`,
+                },
+            ],
+        };
+    });
+    server.registerTool('create-audience-property', {
+        title: 'Create Audience Property',
+        description: 'Define a new custom contact property. The name must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. The type fixes how values are stored and cannot be changed later.',
+        inputSchema: {
+            name: z
+                .string()
+                .nonempty()
+                .max(255)
+                .regex(/^[a-z][a-z0-9_]*$/, 'Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores.')
+                .describe('Property name. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores.'),
+            type: z
+                .enum(['string', 'number', 'boolean', 'date', 'json'])
+                .describe('Value type for the property'),
+            fallback_value: z
+                .string()
+                .max(255)
+                .nullable()
+                .optional()
+                .describe('Optional default value used when a contact has no value set'),
+        },
+    }, async ({ name, type, fallback_value }) => {
+        const body = { name, type };
+        if (fallback_value !== undefined)
+            body.fallback_value = fallback_value;
+        const response = await lettr.post('/audience/properties', body);
+        return {
+            content: [
+                { type: 'text', text: 'Property created successfully.' },
+                { type: 'text', text: formatProperty(response.data) },
+            ],
+        };
+    });
+    server.registerTool('get-audience-property', {
+        title: 'Get Audience Property',
+        description: 'Retrieve a single custom contact property by its ID.',
+        inputSchema: {
+            propertyId: z.string().nonempty().describe('The property ID'),
+        },
+    }, async ({ propertyId }) => {
+        const response = await lettr.get(`/audience/properties/${encodeURIComponent(propertyId)}`);
+        return {
+            content: [
+                { type: 'text', text: 'Property details:' },
+                { type: 'text', text: formatProperty(response.data) },
+            ],
+        };
+    });
+    server.registerTool('update-audience-property', {
+        title: 'Update Audience Property',
+        description: "Update a property's fallback value. The name and type are fixed at creation and cannot be changed. Set fallback_value to null to clear it.",
+        inputSchema: {
+            propertyId: z.string().nonempty().describe('The property ID to update'),
+            fallback_value: z
+                .string()
+                .max(255)
+                .nullable()
+                .optional()
+                .describe('New fallback value. Set to null to clear it; omit to leave it unchanged.'),
+        },
+    }, async ({ propertyId, fallback_value }) => {
+        const body = {};
+        if (fallback_value !== undefined)
+            body.fallback_value = fallback_value;
+        const response = await lettr.patch(`/audience/properties/${encodeURIComponent(propertyId)}`, body);
+        return {
+            content: [
+                { type: 'text', text: 'Property updated successfully.' },
+                { type: 'text', text: formatProperty(response.data) },
+            ],
+        };
+    });
+    server.registerTool('delete-audience-property', {
+        title: 'Delete Audience Property',
+        description: 'Delete a custom contact property. Before using this tool, you MUST double-check with the user that they want to delete this property. Warn them that this action is irreversible and removes the property value from every contact.',
+        inputSchema: {
+            propertyId: z.string().nonempty().describe('The property ID to delete'),
+        },
+    }, async ({ propertyId }) => {
+        await lettr.delete(`/audience/properties/${encodeURIComponent(propertyId)}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Property "${propertyId}" deleted successfully.`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/audience-segments.js

@@ -0,0 +1,222 @@
+import { z } from 'zod';
+const SEGMENT_OPERATORS = [
+    'contains',
+    'not_contains',
+    'equals',
+    'not_equals',
+    'starts_with',
+    'not_starts_with',
+    'ends_with',
+    'not_ends_with',
+    'is_true',
+    'is_false',
+    'greater_than',
+    'greater_than_or_equal',
+    'less_than',
+    'less_than_or_equal',
+    'before',
+    'after',
+];
+// Request shape: groups are nested under `conditions.groups`. Each group's
+// `conditions` are ORed; groups are ANDed. `value` is omitted for the
+// is_true / is_false operators.
+const conditionsSchema = z
+    .object({
+    groups: z
+        .array(z.object({
+        conditions: z
+            .array(z.object({
+            field: z
+                .string()
+                .max(255)
+                .describe('Field to match against. Built-in fields: "email", "status", "created_at". For a custom property, use the "properties." prefix, e.g. "properties.age" (a bare property name will NOT work). You can also match "topics" or "lists" by name (equals/not_equals only). An unrecognized field is silently ignored, which makes the segment match every contact — double-check the field name.'),
+            operator: z
+                .enum(SEGMENT_OPERATORS)
+                .describe('Comparison operator'),
+            value: z
+                .string()
+                .max(1000)
+                .nullable()
+                .optional()
+                .describe('Value to compare against, as a string. Required for all operators except is_true and is_false, which take no value.'),
+        }))
+            .min(1)
+            .describe('Conditions within a group are ORed together'),
+    }))
+        .min(1)
+        .describe('Groups are ANDed together'),
+})
+    .describe('Segment match rules. `groups` are ANDed; conditions within a group are ORed.');
+// Mirror the API contract: every operator except is_true/is_false needs a value.
+// Surface a clear error before the request rather than a generic 422.
+function assertConditionValues(conditions) {
+    for (const group of conditions.groups) {
+        for (const c of group.conditions) {
+            const valueless = c.operator === 'is_true' || c.operator === 'is_false';
+            if (!valueless &&
+                (c.value === undefined || c.value === null || c.value === '')) {
+                throw new Error(`Operator "${c.operator}" on field "${c.field}" requires a value.`);
+            }
+        }
+    }
+}
+function formatSegment(s) {
+    const groups = s.condition_groups
+        .map((g, i) => {
+        const conds = g.conditions
+            .map((c) => `    ${c.field} ${c.operator}${c.value != null ? ` ${JSON.stringify(c.value)}` : ''}`)
+            .join('\n');
+        return `  Group ${i + 1} (any of):\n${conds}`;
+    })
+        .join('\n');
+    return [
+        `ID: ${s.id}`,
+        `Name: ${s.name}`,
+        `List: ${s.list_name ? `${s.list_name} (${s.list_id})` : 'all contacts'}`,
+        `Cached contacts: ${s.cached_contacts_count ?? 'not computed'}`,
+        s.condition_groups.length > 0
+            ? `Conditions:\n${groups}`
+            : 'Conditions: none',
+    ].join('\n');
+}
+export function addAudienceSegmentTools(server, lettr) {
+    server.registerTool('list-audience-segments', {
+        title: 'List Audience Segments',
+        description: 'List audience segments for your team, with pagination. Optionally filter to segments restricted to a specific list.',
+        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)'),
+            list_id: z
+                .string()
+                .optional()
+                .describe('Filter to segments restricted to a specific list (must belong to your team)'),
+        },
+    }, async ({ per_page, page, list_id }) => {
+        const query = {};
+        if (per_page)
+            query.per_page = per_page;
+        if (page)
+            query.page = page;
+        if (list_id)
+            query.list_id = list_id;
+        const response = await lettr.get('/audience/segments', query);
+        const { segments, pagination } = response.data;
+        if (segments.length === 0) {
+            return { content: [{ type: 'text', text: 'No segments found.' }] };
+        }
+        const lines = segments
+            .map((s) => `- ${s.name} (id: ${s.id}${s.list_name ? `, list: ${s.list_name}` : ''}, contacts: ${s.cached_contacts_count ?? 'n/a'})`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${pagination.total} segment(s) — page ${pagination.current_page}/${pagination.last_page}:\n\n${lines}`,
+                },
+            ],
+        };
+    });
+    server.registerTool('create-audience-segment', {
+        title: 'Create Audience Segment',
+        description: `Create an audience segment defined by match conditions.
+
+Conditions are grouped: conditions within a group are ORed together, and groups are ANDed together. The is_true and is_false operators take no value; all other operators require a value. Optionally restrict the segment to a single list with list_id.`,
+        inputSchema: {
+            name: z.string().nonempty().max(255).describe('Segment name'),
+            list_id: z
+                .string()
+                .optional()
+                .describe('Restrict the segment to a single list (must belong to your team)'),
+            conditions: conditionsSchema,
+        },
+    }, async ({ name, list_id, conditions }) => {
+        assertConditionValues(conditions);
+        const body = { name, conditions };
+        if (list_id)
+            body.list_id = list_id;
+        const response = await lettr.post('/audience/segments', body);
+        return {
+            content: [
+                { type: 'text', text: 'Segment created successfully.' },
+                { type: 'text', text: formatSegment(response.data) },
+            ],
+        };
+    });
+    server.registerTool('get-audience-segment', {
+        title: 'Get Audience Segment',
+        description: 'Retrieve a single audience segment by its ID, including its condition groups and cached contact count.',
+        inputSchema: {
+            segmentId: z.string().nonempty().describe('The segment ID'),
+        },
+    }, async ({ segmentId }) => {
+        const response = await lettr.get(`/audience/segments/${encodeURIComponent(segmentId)}`);
+        return {
+            content: [
+                { type: 'text', text: 'Segment details:' },
+                { type: 'text', text: formatSegment(response.data) },
+            ],
+        };
+    });
+    server.registerTool('update-audience-segment', {
+        title: 'Update Audience Segment',
+        description: 'Update an audience segment. All fields are optional — only provided fields change. Providing conditions replaces the entire condition set.',
+        inputSchema: {
+            segmentId: z.string().nonempty().describe('The segment ID to update'),
+            name: z
+                .string()
+                .nonempty()
+                .max(255)
+                .optional()
+                .describe('New segment name'),
+            list_id: z
+                .string()
+                .nullable()
+                .optional()
+                .describe('New list restriction (null removes the restriction)'),
+            conditions: conditionsSchema.optional(),
+        },
+    }, async ({ segmentId, ...rest }) => {
+        if (rest.conditions)
+            assertConditionValues(rest.conditions);
+        const body = {};
+        for (const [key, value] of Object.entries(rest)) {
+            if (value !== undefined)
+                body[key] = value;
+        }
+        const response = await lettr.patch(`/audience/segments/${encodeURIComponent(segmentId)}`, body);
+        return {
+            content: [
+                { type: 'text', text: 'Segment updated successfully.' },
+                { type: 'text', text: formatSegment(response.data) },
+            ],
+        };
+    });
+    server.registerTool('delete-audience-segment', {
+        title: 'Delete Audience Segment',
+        description: 'Delete an audience segment. Before using this tool, you MUST double-check with the user that they want to delete this segment. Warn them that this action is irreversible. (Contacts themselves are not deleted.)',
+        inputSchema: {
+            segmentId: z.string().nonempty().describe('The segment ID to delete'),
+        },
+    }, async ({ segmentId }) => {
+        await lettr.delete(`/audience/segments/${encodeURIComponent(segmentId)}`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Segment "${segmentId}" deleted successfully.`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/audience-topics.js

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+function formatTopic(t) {
+    return [
+        `ID: ${t.id}`,
+        `Name: ${t.name}`,
+        `Description: ${t.description || '(none)'}`,
+        `Default subscription: ${t.default_subscription}`,
+        `Visibility: ${t.visibility}`,
+        `Contacts: ${t.contacts_count}`,
+    ].join('\n');
+}
+export function addAudienceTopicTools(server, lettr) {
+    server.registerTool('list-audience-topics', {
+        title: 'List Audience Topics',
+        description: 'List subscription topics for your team, with pagination. Use this to discover topic IDs to subscribe contacts to.',
+        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/topics', query);
+        const { topics, pagination } = response.data;
+        if (topics.length === 0) {
+            return { content: [{ type: 'text', text: 'No topics found.' }] };
+        }
+        const lines = topics
+            .map((t) => `- ${t.name} (id: ${t.id}, ${t.visibility}, default ${t.default_subscription}, contacts: ${t.contacts_count})`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${pagination.total} topic(s) — page ${pagination.current_page}/${pagination.last_page}:\n\n${lines}`,
+                },
+            ],
+        };
+    });
+    server.registerTool('create-audience-topic', {
+        title: 'Create Audience Topic',
+        description: 'Create a subscription topic. default_subscription controls whether contacts are opted in or out by default (defaults to opt_in); visibility controls whether the topic is shown on public preference pages (defaults to private).',
+        inputSchema: {
+            name: z.string().nonempty().max(255).describe('Topic name'),
+            description: z
+                .string()
+                .max(1000)
+                .optional()
+                .describe('Optional description of the topic'),
+            default_subscription: z
+                .enum(['opt_in', 'opt_out'])
+                .optional()
+                .describe('Default subscription state for contacts (default opt_in)'),
+            visibility: z
+                .enum(['private', 'public'])
+                .optional()
+                .describe('Topic visibility (default private)'),
+        },
+    }, async ({ name, description, default_subscription, visibility }) => {
+        const body = { name };
+        if (description !== undefined)
+            body.description = description;
+        if (default_subscription)
+            body.default_subscription = default_subscription;
+        if (visibility)
+            body.visibility = visibility;
+        const response = await lettr.post('/audience/topics', body);
+        return {
+            content: [
+                { type: 'text', text: 'Topic created successfully.' },
+                { type: 'text', text: formatTopic(response.data) },
+            ],
+        };
+    });
+    server.registerTool('get-audience-topic', {
+        title: 'Get Audience Topic',
+        description: 'Retrieve a single subscription topic by its ID.',
+        inputSchema: {
+            topicId: z.string().nonempty().describe('The topic ID'),
+        },
+    }, async ({ topicId }) => {
+        const response = await lettr.get(`/audience/topics/${encodeURIComponent(topicId)}`);
+        return {
+            content: [
+                { type: 'text', text: 'Topic details:' },
+                { type: 'text', text: formatTopic(response.data) },
+            ],
+        };
+    });
+    server.registerTool('update-audience-topic', {
+        title: 'Update Audience Topic',
+        description: 'Update a subscription topic. All fields are optional — only provided fields change. Note that default_subscription cannot be changed after creation.',
+        inputSchema: {
+            topicId: z.string().nonempty().describe('The topic ID to update'),
+            name: z
+                .string()
+                .nonempty()
+                .max(255)
+                .optional()
+                .describe('New topic name'),
+            description: z
+                .string()
+                .max(1000)
+                .nullable()
+                .optional()
+                .describe('New description (null clears it)'),
+            visibility: z
+                .enum(['private', 'public'])
+                .optional()
+                .describe('New visibility'),
+        },
+    }, async ({ topicId, ...rest }) => {
+        const body = {};
+        for (const [key, value] of Object.entries(rest)) {
+            if (value !== undefined)
+                body[key] = value;
+        }
+        const response = await lettr.patch(`/audience/topics/${encodeURIComponent(topicId)}`, body);
+        return {
+            content: [
+                { type: 'text', text: 'Topic updated successfully.' },
+                { type: 'text', text: formatTopic(response.data) },
+            ],
+        };
+    });
+    server.registerTool('delete-audience-topic', {
+        title: 'Delete Audience Topic',
+        description: 'Delete a subscription topic. Before using this tool, you MUST double-check with the user that they want to delete this topic. Warn them that this action is irreversible and removes all contact subscriptions to it.',
+        inputSchema: {
+            topicId: z.string().nonempty().describe('The topic ID to delete'),
+        },
+    }, async ({ topicId }) => {
+        await lettr.delete(`/audience/topics/${encodeURIComponent(topicId)}`);
+        return {
+            content: [
+                { type: 'text', text: `Topic "${topicId}" deleted successfully.` },
+            ],
+        };
+    });
+}

package/dist/tools/index.js

@@ -1,3 +1,9 @@
+export * from './audience-contacts.js';
+export * from './audience-lists.js';
+export * from './audience-memberships.js';
+export * from './audience-properties.js';
+export * from './audience-segments.js';
+export * from './audience-topics.js';
 export * from './domains.js';
 export * from './emails.js';
 export * from './projects.js';

package/dist/tools/templates.js

@@ -217,7 +217,7 @@ export function addTemplateTools(server, lettr) {
         const query = {};
         if (project_id)
             query.project_id = project_id;
-        await lettr.delete(`/templates/${encodeURIComponent(slug)}`, query);
+        await lettr.delete(`/templates/${encodeURIComponent(slug)}`, undefined, query);
         return {
             content: [
                 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lettr-mcp",
-  "version": "1.1.1",
+  "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",