lettr-mcp 1.4.0 → 1.5.0

package/README.md

@@ -153,7 +153,7 @@ Environment variables:
 | `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 |
+| `bulk-create-audience-contacts` | Create many contacts, either from a flat list of emails or one row per contact |
 | `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 |
@@ -162,6 +162,8 @@ Environment variables:
 | `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 |
+| `bulk-subscribe-contacts-to-topics` | Subscribe many contacts to many topics at once |
+| `bulk-unsubscribe-contacts-from-topics` | Unsubscribe many contacts from many topics at once |
 | `list-audience-topics` | List subscription topics with pagination |
 | `create-audience-topic` | Create a subscription topic |
 | `get-audience-topic` | Get a single topic |

package/dist/package.json

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

@@ -3,6 +3,13 @@ import { z } from 'zod';
 // On update, a null value removes the property from the contact.
 const createPropertyValue = z.string().max(1000);
 const updatePropertyValue = z.string().max(1000).nullable();
+const topicSubscription = z.object({
+    id: z.string().nonempty().describe('The topic ID'),
+    subscription: z
+        .enum(['opt_in', 'opt_out'])
+        .optional()
+        .describe('Defaults to opt_in. Use opt_out to keep the contact off a topic that would otherwise auto-subscribe them.'),
+});
 function formatContact(c) {
     const props = Object.entries(c.properties ?? {});
     const lines = [
@@ -111,7 +118,8 @@ export function addAudienceContactTools(server, lettr) {
         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.`,
+- 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.
+- If the email already exists for the team this fails with HTTP 409 (\`resource_already_exists\`). That is a client-correctable condition, not an outage — do NOT retry it. Update the existing contact with update-audience-contact, or use bulk-create-audience-contacts with \`update_existing\` set.`,
         inputSchema: {
             email: z.email().max(255).describe('Contact email address'),
             list_id: z
@@ -167,38 +175,130 @@ export function addAudienceContactTools(server, lettr) {
     });
     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).',
+        description: `Create many contacts in one request (max 1000).
+
+Provide exactly one of:
+- \`emails\` — a flat list of addresses, when every contact gets the same treatment.
+- \`contacts\` — one row per contact, when they differ. Each row takes its own \`properties\`, \`list_ids\` and \`topics\`, applied on top of the batch-wide \`list_ids\`, \`topics\` and \`properties\`.
+
+A row-level topic \`opt_out\` beats a batch-level \`opt_in\`. That is how you keep specific people off a topic that auto-subscribes new contacts, without a second cleanup call.
+
+\`update_existing\` (default false) controls only whether properties are merged into contacts that already exist — submitted keys overwrite, absent keys are preserved. Existing contacts are attached to the requested lists and topics either way.
+
+IMPORTANT — this call can partially succeed. Rows that fail validation are skipped and the rest of the batch still commits, so a successful response does NOT mean every row landed. Always read the reported error count back to the user rather than claiming the whole batch was imported.
+
+With \`contacts\`, pass rows through as the user gave them — a malformed address is reported back as a skipped row, so do not drop or "fix" entries yourself first. With \`emails\`, a single invalid address rejects the whole request, so check them before sending.`,
         inputSchema: {
             emails: z
                 .array(z.email().max(255))
                 .min(1)
                 .max(1000)
-                .describe('Email addresses to create contacts for (max 1000)'),
+                .optional()
+                .describe('Flat list of email addresses (max 1000). Mutually exclusive with `contacts`.'),
+            contacts: z
+                .array(z.object({
+                // Deliberately not z.email(): the API skips a malformed row and
+                // commits the rest, reporting it as `invalid_email` in `errors`.
+                // Validating the address here would reject the whole batch
+                // instead, so one bad row in a pasted list would import nothing.
+                // The flat `emails` field above stays strict because there the
+                // API does reject the whole request (422).
+                email: z
+                    .string()
+                    .nonempty()
+                    .max(255)
+                    .describe('Contact email address'),
+                properties: z
+                    .record(z.string(), createPropertyValue)
+                    .optional()
+                    .describe('Property values for this contact only, each a string (max 1000 chars). Each key must match a property defined for the team.'),
+                list_ids: z
+                    .array(z.string().nonempty())
+                    .max(50)
+                    .optional()
+                    .describe('Lists for this contact only (max 50), on top of the batch-wide list_ids'),
+                topics: z
+                    .array(topicSubscription)
+                    .max(50)
+                    .optional()
+                    .describe('Topic subscriptions for this contact only (max 50)'),
+            }))
+                .min(1)
+                .max(1000)
+                .optional()
+                .describe('One row per contact (max 1000), when contacts differ from each other. Mutually exclusive with `emails`.'),
             list_id: z
                 .string()
                 .optional()
-                .describe('Optional list ID to add all contacts to'),
+                .describe('Single list ID applied to the whole batch. Kept for convenience; `list_ids` is the general form.'),
+            list_ids: z
+                .array(z.string().nonempty())
+                .max(50)
+                .optional()
+                .describe('List IDs applied to every contact in the batch (max 50)'),
+            topics: z
+                .array(topicSubscription)
+                .max(50)
+                .optional()
+                .describe('Topic subscriptions applied to every contact in the batch (max 50)'),
             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.'),
+                .describe('Custom property values applied to every contact in this batch, each as a string (max 1000 chars). Each key must match a property defined for the team.'),
+            update_existing: z
+                .boolean()
+                .optional()
+                .describe('Whether to merge the submitted properties into contacts that already exist (default false)'),
         },
-    }, async ({ emails, list_id, properties }) => {
-        const body = { emails };
+    }, async ({ emails, contacts, list_id, list_ids, topics, properties, update_existing, }) => {
+        if (!emails && !contacts) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Provide either `emails` (a flat list of addresses) or `contacts` (one row per contact).',
+                    },
+                ],
+            };
+        }
+        const body = {};
+        if (emails)
+            body.emails = emails;
+        if (contacts)
+            body.contacts = contacts;
         if (list_id)
             body.list_id = list_id;
+        if (list_ids?.length)
+            body.list_ids = list_ids;
+        if (topics?.length)
+            body.topics = topics;
         if (properties)
             body.properties = properties;
+        if (update_existing !== undefined)
+            body.update_existing = update_existing;
         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.`,
-                },
-            ],
-        };
+        const data = response.data;
+        const errors = data.errors ?? [];
+        const errorCount = data.error_count ?? errors.length;
+        const lines = [
+            `Created ${data.created} contact(s); ${data.already_existed} already existed; ${data.updated ?? 0} updated.`,
+            // These two counters answer different questions ("was it already
+            // there?" vs "did we change it?") and overlap, so spelling that out
+            // stops the model reporting a total that does not add up.
+            'Note: `already existed` and `updated` overlap — a contact that existed and got a list or topic attached is counted in both, so they do not sum to the number of rows submitted.',
+        ];
+        if (errorCount > 0) {
+            lines.push(`${errorCount} row(s) were SKIPPED and not imported. The rest of the batch did commit:`);
+            for (const e of errors) {
+                lines.push(`  - row ${e.index} (${e.email ?? 'no email'}): [${e.error_code}] ${e.error}`);
+            }
+        }
+        const refs = data.contacts ?? [];
+        if (refs.length > 0) {
+            lines.push(`Contacts (${refs.length}):`, ...refs.map((c) => `  - ${c.email} (id: ${c.id}, ${c.created ? 'created' : 'existing'})`));
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     server.registerTool('update-audience-contact', {
         title: 'Update Audience Contact',

package/dist/tools/audience-memberships.js

@@ -126,4 +126,58 @@ export function addAudienceMembershipTools(server, lettr) {
             ],
         };
     });
+    server.registerTool('bulk-subscribe-contacts-to-topics', {
+        title: 'Bulk Subscribe Contacts to Topics',
+        description: 'Subscribe multiple contacts to multiple topics at once. Every contact is subscribed to every topic (a cartesian product of contact_ids × topic_ids). All IDs must belong to your team.',
+        inputSchema: {
+            contact_ids: z
+                .array(z.string().nonempty())
+                .min(1)
+                .max(1000)
+                .describe('Contact IDs to subscribe (max 1000)'),
+            topic_ids: z
+                .array(z.string().nonempty())
+                .min(1)
+                .max(50)
+                .describe('Topic IDs to subscribe the contacts to (max 50)'),
+        },
+    }, async ({ contact_ids, topic_ids }) => {
+        const response = await lettr.post('/audience/contacts/topics/bulk', { contact_ids, topic_ids });
+        const { subscribed, already_subscribed, total_pairs } = response.data;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Subscribed ${subscribed} of ${total_pairs} contact-topic pair(s); ${already_subscribed} were already subscribed.`,
+                },
+            ],
+        };
+    });
+    server.registerTool('bulk-unsubscribe-contacts-from-topics', {
+        title: 'Bulk Unsubscribe Contacts from Topics',
+        description: 'Unsubscribe multiple contacts from multiple topics at once (a cartesian product of contact_ids × topic_ids). Before using this tool, you MUST double-check with the user, as it drops many subscriptions at once.',
+        inputSchema: {
+            contact_ids: z
+                .array(z.string().nonempty())
+                .min(1)
+                .max(1000)
+                .describe('Contact IDs to unsubscribe (max 1000)'),
+            topic_ids: z
+                .array(z.string().nonempty())
+                .min(1)
+                .max(50)
+                .describe('Topic IDs to unsubscribe the contacts from (max 50)'),
+        },
+    }, async ({ contact_ids, topic_ids }) => {
+        const response = await lettr.delete('/audience/contacts/topics/bulk', { contact_ids, topic_ids });
+        const { unsubscribed, total_pairs } = response.data;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Unsubscribed ${unsubscribed} of ${total_pairs} contact-topic pair(s).`,
+                },
+            ],
+        };
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lettr-mcp",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "MCP server for the Lettr email API — send transactional emails, manage templates, domains, and webhooks from any AI assistant",
   "keywords": [
     "lettr",