lettr-mcp 1.4.0 → 1.6.0

package/README.md

@@ -15,7 +15,7 @@ The official [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) se
 ## Features
 
 - **Send Emails** — Send transactional emails with HTML, plain text, CC/BCC, attachments, tracking options, metadata, and tags. Supports [template-based sending](https://docs.lettr.com/learn/templates/introduction) with merge tag substitution, scheduled delivery, and inspecting sent messages and events.
-- **Templates** — List, create, get, update, and delete email templates. Retrieve rendered HTML and [merge tags](https://docs.lettr.com/learn/templates/template-language) to discover which variables a template expects before sending.
+- **Templates** — List, create, get, update, and delete email templates, transactional or campaign. Retrieve rendered HTML and [merge tags](https://docs.lettr.com/learn/templates/template-language) to discover which variables a template expects before sending.
 - **Domains** — List, create, get, delete, and [verify sending domains](https://docs.lettr.com/learn/domains/sending-domains). View DNS records required for SPF, DKIM, and DMARC authentication.
 - **Webhooks** — List, 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.
@@ -106,14 +106,26 @@ Environment variables:
 
 | Tool | Description |
 |------|-------------|
-| `list-templates` | List email templates with pagination |
+| `list-templates` | List email templates, filterable by purpose and folder |
 | `get-template` | Get full template details including HTML content |
-| `create-template` | Create a new template with HTML or visual editor JSON |
+| `create-template` | Create a new template with HTML or visual editor JSON, transactional or campaign |
 | `update-template` | Update template name and/or content (creates new version) |
 | `delete-template` | Permanently delete a template and all versions |
 | `get-merge-tags` | Discover merge tag variables a template expects |
 | `get-template-html` | Retrieve a template's rendered HTML, subject, and merge tags by project ID and slug |
 
+**Template purpose.** A template is either `transactional` (the default — receipts, password resets, alerts) or `campaign` (marketing sent to an audience list). A campaign can only send a template whose purpose is `campaign`, and the purpose cannot be changed after creation, so a newsletter created with the default has to be rebuilt. Pass `purpose` to `create-template` whenever the message is going to an audience rather than to one person.
+
+**Preparation status.** Imported templates render asynchronously, so a template can exist before it is sendable. `list-templates` and `get-template` report `pending`, `ready` or `failed`. After an *update* the previous render keeps serving until the new one settles, so a pending template still sends — just not yet the new content.
+
+### Folders
+
+| Tool | Description |
+|------|-------------|
+| `list-folders` | List the folders templates are filed into, with purpose and template count |
+
+Folders are the only way to discover a `folder_id`. Without this tool the choice is to omit `folder_id` and accept whichever folder the API picks, or to guess an integer read out of an app URL. A folder's purpose is independent of its templates' — filing a template in a campaign folder does not make it a campaign template.
+
 ### Domains
 
 | Tool | Description |
@@ -153,7 +165,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 +174,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/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 { addAudienceContactTools, addAudienceListTools, addAudienceMembershipTools, addAudiencePropertyTools, addAudienceSegmentTools, addAudienceTopicTools, addCampaignTools, addDomainTools, addEmailTools, addProjectTools, addSystemTools, addTemplateTools, addWebhookTools, } from './tools/index.js';
+import { addAudienceContactTools, addAudienceListTools, addAudienceMembershipTools, addAudiencePropertyTools, addAudienceSegmentTools, addAudienceTopicTools, addCampaignTools, addDomainTools, addEmailTools, addFolderTools, 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;
@@ -22,6 +22,7 @@ const server = new McpServer({
 });
 addEmailTools(server, lettr, { senderEmailAddress, replierEmailAddress });
 addTemplateTools(server, lettr);
+addFolderTools(server, lettr);
 addDomainTools(server, lettr);
 addWebhookTools(server, lettr);
 addProjectTools(server, lettr);

package/dist/lettr.js

@@ -6,7 +6,11 @@ export class LettrClient {
         this.apiKey = apiKey;
         this.version = version;
     }
-    async request(method, path, body, query) {
+    async request(method, path, body, query, extraHeaders) {
+        const { data } = await this.requestWithHeaders(method, path, body, query, extraHeaders);
+        return data;
+    }
+    async requestWithHeaders(method, path, body, query, extraHeaders) {
         const url = new URL(`${BASE_URL}${path}`);
         if (query) {
             for (const [key, value] of Object.entries(query)) {
@@ -19,6 +23,7 @@ export class LettrClient {
             Authorization: `Bearer ${this.apiKey}`,
             Accept: 'application/json',
             'User-Agent': `lettr-mcp/${this.version}`,
+            ...extraHeaders,
         };
         const options = { method, headers };
         if (body &&
@@ -39,15 +44,44 @@ export class LettrClient {
                     .map(([field, msgs]) => `  ${field}: ${msgs.join(', ')}`)
                     .join('\n')}`
                 : '';
+            // The two idempotency 409s look identical but call for opposite
+            // reactions, so say which one happened rather than leaving the agent to
+            // guess from the message.
+            if (response.status === 409) {
+                const retryAfter = response.headers.get('Retry-After');
+                if (err.error_code === 'idempotency_in_progress') {
+                    throw new Error(`Lettr API error (409): an earlier send with this idempotency key is still in flight. Retry with the SAME key${retryAfter ? ` after ${retryAfter}s` : ''}.`);
+                }
+                if (err.error_code === 'idempotency_key_conflict') {
+                    throw new Error('Lettr API error (409): this idempotency key was already used with a different payload. Do NOT retry — it will fail identically forever. Use a new key, or resend the original payload.');
+                }
+            }
             throw new Error(`Lettr API error (${response.status}): ${err.message ?? response.statusText}${detail}`);
         }
-        return json;
+        return { data: json, headers: response.headers };
     }
     async get(path, query) {
         return this.request('GET', path, undefined, query);
     }
-    async post(path, body, query) {
-        return this.request('POST', path, body, query);
+    async post(path, body, query, headers) {
+        return this.request('POST', path, body, query, headers);
+    }
+    /**
+     * POST an idempotent request.
+     *
+     * Reusing the key returns the original result instead of repeating the
+     * action; `replayed` says whether that is what happened.
+     */
+    async postIdempotent(path, body, idempotencyKey) {
+        const { data, headers } = await this.requestWithHeaders('POST', path, body, undefined, { 'Idempotency-Key': idempotencyKey });
+        return {
+            data,
+            // Case-insensitive to match every Lettr SDK. The spec pins the value to
+            // the literal 'true', but a strict compare here would silently report
+            // "not replayed" if that ever varied - and a missed replay reads as a
+            // second email having gone out.
+            replayed: headers.get('Idempotency-Replayed')?.toLowerCase() === 'true',
+        };
     }
     async put(path, body, query) {
         return this.request('PUT', path, body, query);

package/dist/package.json

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

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/dist/tools/emails.js

@@ -253,16 +253,42 @@ export function addEmailTools(server, lettr, defaults) {
 - User says "email this to X", "notify them", "send a message to..."
 - Sending with a template: use template_slug and substitution_data (subject is optional in this case)
 
-**Key trigger phrases:** "Send an email", "Email this to", "Notify", "Send a message", "Reply to them"`,
-        inputSchema: sendEmailShape(senderEmailAddress, replierEmailAddress),
+**Key trigger phrases:** "Send an email", "Email this to", "Notify", "Send a message", "Reply to them"
+
+**Retrying:** pass idempotency_key and reuse the same value on a retry. Without it, a retry after a timeout sends the email twice — the first attempt may well have succeeded and only the response was lost.`,
+        inputSchema: {
+            ...sendEmailShape(senderEmailAddress, replierEmailAddress),
+            idempotency_key: z
+                .string()
+                .min(1)
+                .max(255)
+                .optional()
+                .describe('Opaque key making this send safe to retry. Reuse the SAME value when retrying and the API returns the original result instead of delivering a second email. Derive it from what the send is about (e.g. "order-12345-receipt"), not from a timestamp or random value — a fresh key on a retry defeats the point. Keys are kept 24 hours and are scoped per team and API key.'),
+        },
     }, async (input) => {
         const body = await buildSendEmailBody(input, defaults);
-        const response = await lettr.post('/emails', body);
+        // Keyless sends keep the plain path: with no key there is nothing to
+        // replay, so there is no header worth reading back.
+        if (!input.idempotency_key) {
+            const response = await lettr.post('/emails', body);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Email sent successfully! Request ID: ${response.data.request_id}, Accepted: ${response.data.accepted}, Rejected: ${response.data.rejected}`,
+                    },
+                ],
+            };
+        }
+        const { data: response, replayed } = await lettr.postIdempotent('/emails', body, input.idempotency_key);
+        const outcome = replayed
+            ? 'Replayed an earlier send with this idempotency key — no second email went out.'
+            : 'Email sent successfully!';
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Email sent successfully! Request ID: ${response.data.request_id}, Accepted: ${response.data.accepted}, Rejected: ${response.data.rejected}`,
+                    text: `${outcome} Request ID: ${response.data.request_id}, Accepted: ${response.data.accepted}, Rejected: ${response.data.rejected}`,
                 },
             ],
         };

package/dist/tools/folders.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+export function addFolderTools(server, lettr) {
+    server.registerTool('list-folders', {
+        title: 'List Folders',
+        description: `**Purpose:** List the folders templates are filed into, with each folder's purpose and template count.
+
+**Returns:** Folder id, name, project, purpose (transactional or campaign) and how many templates are inside.
+
+**When to use:**
+- Before creating a template, to pick a folder id — nothing else in the API returns one, so without this you either omit folder_id and accept whichever folder the API picks, or guess an integer
+- To find the campaign folder when the user asks for a marketing template
+- To answer "where are my templates organised", "what folders do I have"
+
+**Note:** A folder's purpose and a template's purpose are separate. Filing a template in a campaign folder does not make the template a campaign template — set purpose on the template itself.`,
+        inputSchema: {
+            project_id: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("Project ID to list folders from. If not provided, uses the team's default project."),
+            purpose: z
+                .enum(['transactional', 'campaign'])
+                .optional()
+                .describe('Only return folders of this purpose. Omit to return both.'),
+            per_page: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe('Results per page (1-100, default 25)'),
+            page: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('Page number (default 1)'),
+        },
+    }, async ({ project_id, purpose, per_page, page }) => {
+        const query = {};
+        if (project_id)
+            query.project_id = project_id;
+        if (purpose)
+            query.purpose = purpose;
+        if (per_page)
+            query.per_page = per_page;
+        if (page)
+            query.page = page;
+        const response = await lettr.get('/folders', query);
+        const folders = response.data.folders;
+        const pagination = response.data.pagination;
+        if (folders.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No folders found.' }],
+            };
+        }
+        const folderList = folders
+            .map((f) => `- ${f.name} (id: ${f.id}) | Purpose: ${f.purpose} | Templates: ${f.templates_count} | Project: ${f.project_id}`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${pagination.total} folder(s) (page ${pagination.current_page}/${pagination.last_page}):\n\n${folderList}`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/index.js

@@ -7,6 +7,7 @@ export * from './audience-topics.js';
 export * from './campaigns.js';
 export * from './domains.js';
 export * from './emails.js';
+export * from './folders.js';
 export * from './projects.js';
 export * from './system.js';
 export * from './templates.js';

package/dist/tools/templates.js

@@ -4,11 +4,13 @@ export function addTemplateTools(server, lettr) {
         title: 'List Templates',
         description: `**Purpose:** List email templates with pagination. Returns template names, slugs, and project info.
 
-**Returns:** Paginated list of templates with id, name, slug, project_id, folder_id, timestamps.
+**Returns:** Paginated list of templates with id, name, slug, project_id, folder_id, purpose, preparation status and timestamps.
 
 **When to use:**
 - User asks "show my templates", "what templates do I have?"
 - Before sending a template-based email, to find the template slug
+- Filter by purpose=campaign to find templates a campaign can actually use
+- Filter by folder_id to reconcile a bulk import in one call instead of one get-template per template
 - Use get-template for full details of a specific template`,
         inputSchema: {
             project_id: z
@@ -24,6 +26,16 @@ export function addTemplateTools(server, lettr) {
                 .max(100)
                 .optional()
                 .describe('Number of results per page (1-100). Default: 25'),
+            purpose: z
+                .enum(['transactional', 'campaign'])
+                .optional()
+                .describe('Only return templates of this purpose. Use campaign to find templates that a campaign can send.'),
+            folder_id: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('Only return templates in this folder. A folder outside the resolved project is an error, not an empty list, so a wrong id cannot be misread as "nothing there yet". Use list-folders to find one.'),
             page: z
                 .number()
                 .int()
@@ -31,10 +43,14 @@ export function addTemplateTools(server, lettr) {
                 .optional()
                 .describe('Page number. Default: 1'),
         },
-    }, async ({ project_id, per_page, page }) => {
+    }, async ({ project_id, purpose, folder_id, per_page, page }) => {
         const query = {};
         if (project_id)
             query.project_id = project_id;
+        if (purpose)
+            query.purpose = purpose;
+        if (folder_id)
+            query.folder_id = folder_id;
         if (per_page)
             query.per_page = per_page;
         if (page)
@@ -48,7 +64,15 @@ export function addTemplateTools(server, lettr) {
             };
         }
         const templateList = templates
-            .map((t) => `- ${t.name} (slug: ${t.slug}) | Project: ${t.project_id} | Updated: ${t.updated_at}`)
+            .map((t) => {
+            const purpose = t.purpose ? ` | ${t.purpose}` : '';
+            // Only worth surfacing when it is not ready - a settled template is
+            // the uninteresting case and would just add noise to every row.
+            const preparing = t.preparation_status && t.preparation_status !== 'ready'
+                ? ` | preparation: ${t.preparation_status}`
+                : '';
+            return `- ${t.name} (slug: ${t.slug}) | Project: ${t.project_id}${purpose}${preparing} | Updated: ${t.updated_at}`;
+        })
             .join('\n');
         return {
             content: [
@@ -83,6 +107,18 @@ export function addTemplateTools(server, lettr) {
         details += `- Slug: ${t.slug}\n`;
         details += `- Project ID: ${t.project_id}\n`;
         details += `- Folder ID: ${t.folder_id}\n`;
+        details += `- Purpose: ${t.purpose ?? 'transactional'}\n`;
+        if (t.preparation_status) {
+            details += `- Preparation: ${t.preparation_status}\n`;
+            if (t.preparation_status === 'pending') {
+                details +=
+                    '  (still rendering — an update keeps serving the previous HTML until this settles)\n';
+            }
+            if (t.preparation_status === 'failed') {
+                details +=
+                    '  (rendering failed — this template will not send the content you imported)\n';
+            }
+        }
         details += `- Active Version: ${t.active_version ?? 'none'}\n`;
         details += `- Total Versions: ${t.versions_count}\n`;
         details += `- Created: ${t.created_at}\n`;
@@ -96,7 +132,9 @@ export function addTemplateTools(server, lettr) {
     });
     server.registerTool('create-template', {
         title: 'Create Template',
-        description: 'Create a new email template with HTML or Topol editor JSON content. Provide either html or json — they are mutually exclusive. Merge tags are automatically extracted from the content.',
+        description: `Create a new email template with HTML or Topol editor JSON content. Provide either html or json — they are mutually exclusive. Merge tags are automatically extracted from the content.
+
+**Set purpose deliberately.** It defaults to transactional, and it cannot be changed after creation. A campaign can only send a template whose purpose is campaign, so a newsletter or promotion created with the default has to be recreated from scratch. If the user is writing anything that goes to an audience list, pass purpose: "campaign".`,
         inputSchema: {
             name: z
                 .string()
@@ -122,9 +160,13 @@ export function addTemplateTools(server, lettr) {
                 .int()
                 .min(1)
                 .optional()
-                .describe('Folder ID within the project. If not provided, uses the first folder.'),
+                .describe('Folder ID within the project. If not provided, uses the first folder. Use list-folders to find one.'),
+            purpose: z
+                .enum(['transactional', 'campaign'])
+                .optional()
+                .describe("What the template is for. **transactional** (default) is triggered by one user's action — a receipt, password reset, alert. **campaign** is marketing sent to an audience list, and is the ONLY kind a campaign can send. This cannot be changed later: a newsletter created as transactional must be recreated."),
         },
-    }, async ({ name, html, json, project_id, folder_id }) => {
+    }, async ({ name, html, json, project_id, folder_id, purpose }) => {
         if (html && json) {
             throw new Error('html and json are mutually exclusive — provide only one.');
         }
@@ -137,6 +179,8 @@ export function addTemplateTools(server, lettr) {
             body.project_id = project_id;
         if (folder_id)
             body.folder_id = folder_id;
+        if (purpose)
+            body.purpose = purpose;
         const response = await lettr.post('/templates', body);
         const t = response.data;
         const mergeTags = t.merge_tags.length > 0
@@ -146,7 +190,7 @@ export function addTemplateTools(server, lettr) {
             content: [
                 {
                     type: 'text',
-                    text: `Template created successfully!\nName: ${t.name}\nSlug: ${t.slug}\nVersion: ${t.active_version}${mergeTags}`,
+                    text: `Template created successfully!\nName: ${t.name}\nSlug: ${t.slug}\nPurpose: ${t.purpose ?? 'transactional'}\nVersion: ${t.active_version}${mergeTags}`,
                 },
             ],
         };

package/package.json

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