lettr-mcp 1.5.0 → 1.7.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.
@@ -98,22 +98,35 @@ Environment variables:
 | `list-emails` | List recently sent emails (cursor-paginated, with recipient and date filters) |
 | `list-email-events` | List email events (delivery, bounce, click, open, …) with filters by type, recipient, transmission, and date range |
 | `get-email-detail` | Retrieve the full delivery timeline for a single transmission by request ID |
-| `schedule-email` | Schedule a transactional email for future delivery (5+ minutes ahead, within 3 days) |
-| `get-scheduled-email` | Get the state and events of a scheduled transmission |
-| `cancel-scheduled-email` | Cancel a scheduled transmission before it is sent |
+| `schedule-email` | Schedule a transactional email for future delivery (5+ minutes ahead, within 30 days) |
+| `list-scheduled-emails` | List emails waiting to be sent, with a state filter |
+| `get-scheduled-email` | Get the state and events of a scheduled email |
+| `cancel-scheduled-email` | Cancel a scheduled email before it is sent |
 
 ### Templates
 
 | 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 |

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.5.0",
-    "description": "MCP server for the Lettr email API — send transactional emails, manage templates, domains, and webhooks from any AI assistant",
+    "version": "1.7.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/emails.js

@@ -19,6 +19,24 @@ const EMAIL_EVENT_TYPES = [
     'list_unsubscribe',
     'link_unsubscribe',
 ];
+function formatScheduledEmail(d) {
+    return [
+        `Scheduled email: ${d.request_id}`,
+        `State: ${d.state}`,
+        d.scheduled_at ? `Scheduled for: ${d.scheduled_at}` : null,
+        `From: ${d.from_name ? `${d.from_name} <${d.from}>` : d.from}`,
+        d.subject ? `Subject: ${d.subject}` : null,
+        `Recipients (${d.num_recipients}): ${d.recipients.join(', ')}`,
+        d.tag ? `Tag: ${d.tag}` : null,
+        // Only meaningful once sent — this is the id webhook events carry.
+        d.transmission_id
+            ? `Transmission: ${d.transmission_id}`
+            : 'Transmission: not sent yet',
+        d.failure_reason ? `Failure reason: ${d.failure_reason}` : null,
+    ]
+        .filter((x) => x !== null)
+        .join('\n');
+}
 const sendEmailShape = (senderEmailAddress, replierEmailAddress) => ({
     to: z
         .array(z.email().max(255))
@@ -253,16 +271,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}`,
                 },
             ],
         };
@@ -403,14 +447,14 @@ export function addEmailTools(server, lettr, defaults) {
     });
     server.registerTool('schedule-email', {
         title: 'Schedule Email',
-        description: `Schedule an email for future delivery. Accepts the same fields as send-email plus a required scheduled_at (ISO 8601, UTC) that is at least 5 minutes in the future and at most 3 days out.
+        description: `Schedule an email for future delivery. Accepts the same fields as send-email plus a required scheduled_at (ISO 8601, UTC) that is at least 5 minutes in the future and at most 30 days out.
 
-**Returns:** Same response as send-email (request_id + accepted/rejected counts).`,
+**Returns:** The scheduled email, including the \`sch_\` request ID that get-scheduled-email and cancel-scheduled-email take.`,
         inputSchema: {
             ...sendEmailShape(senderEmailAddress, replierEmailAddress),
             scheduled_at: z
                 .string()
-                .describe('ISO 8601 UTC datetime (e.g. 2024-01-16T10:00:00Z). Must be 5+ minutes in the future and within 3 days.'),
+                .describe('ISO 8601 UTC datetime (e.g. 2024-01-16T10:00:00Z). Must be 5+ minutes in the future and within 30 days.'),
         },
     }, async (input) => {
         const { scheduled_at, ...sendInput } = input;
@@ -418,64 +462,80 @@ export function addEmailTools(server, lettr, defaults) {
         body.scheduled_at = scheduled_at;
         const response = await lettr.post('/emails/scheduled', body);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Email scheduled for ${scheduled_at}. Request ID: ${response.data.request_id}, Accepted: ${response.data.accepted}, Rejected: ${response.data.rejected}`,
-                },
-            ],
+            content: [{ type: 'text', text: formatScheduledEmail(response.data) }],
         };
     });
     server.registerTool('get-scheduled-email', {
         title: 'Get Scheduled Email',
-        description: 'Retrieve details of a scheduled (but not yet sent) email, including its state, scheduled_at timestamp, recipients and any events collected so far.',
+        description: 'Retrieve details of a scheduled email, including its state, scheduled_at timestamp, recipients and any events collected so far. Works for every state, not only pending ones — a cancelled or sent email is still readable.',
         inputSchema: {
-            transmission_id: z
+            request_id: z
                 .string()
                 .nonempty()
-                .describe('Transmission ID returned by schedule-email'),
+                .describe('The `sch_` request ID returned by schedule-email'),
         },
-    }, async ({ transmission_id }) => {
-        const response = await lettr.get(`/emails/scheduled/${encodeURIComponent(transmission_id)}`);
+    }, async ({ request_id }) => {
+        const response = await lettr.get(`/emails/scheduled/${encodeURIComponent(request_id)}`);
         const d = response.data;
         const eventLines = d.events.length === 0
             ? '(no events yet)'
             : d.events.map(formatEvent).join('\n');
         return {
             content: [
-                {
-                    type: 'text',
-                    text: [
-                        `Transmission: ${d.transmission_id}`,
-                        `State: ${d.state}`,
-                        d.scheduled_at ? `Scheduled for: ${d.scheduled_at}` : null,
-                        `From: ${d.from_name ? `${d.from_name} <${d.from}>` : d.from}`,
-                        `Subject: ${d.subject}`,
-                        `Recipients (${d.num_recipients}): ${d.recipients.join(', ')}`,
-                    ]
-                        .filter((x) => x !== null)
-                        .join('\n'),
-                },
+                { type: 'text', text: formatScheduledEmail(d) },
                 { type: 'text', text: `Events:\n${eventLines}` },
             ],
         };
     });
     server.registerTool('cancel-scheduled-email', {
         title: 'Cancel Scheduled Email',
-        description: 'Cancel a scheduled email before it is sent. Before using this tool, you MUST confirm with the user that they really want to cancel this transmission — this action cannot be undone.',
+        description: 'Cancel a scheduled email before it is sent. Before using this tool, you MUST confirm with the user that they really want to cancel this email — this action cannot be undone. Only an email still in the `scheduled` state can be cancelled.',
         inputSchema: {
-            transmission_id: z
+            request_id: z
                 .string()
                 .nonempty()
-                .describe('Transmission ID to cancel'),
+                .describe('The `sch_` request ID to cancel'),
         },
-    }, async ({ transmission_id }) => {
-        await lettr.delete(`/emails/scheduled/${encodeURIComponent(transmission_id)}`);
+    }, async ({ request_id }) => {
+        // Cancelling answers with the cancelled email, so report its real state
+        // rather than asserting success.
+        const response = await lettr.delete(`/emails/scheduled/${encodeURIComponent(request_id)}`);
+        return {
+            content: [{ type: 'text', text: formatScheduledEmail(response.data) }],
+        };
+    });
+    server.registerTool('list-scheduled-emails', {
+        title: 'List Scheduled Emails',
+        description: 'List emails waiting to be sent, soonest delivery time first. Use this to find the `sch_` request ID of an email the user describes but cannot name, before getting or cancelling it.',
+        inputSchema: {
+            status: z
+                .enum(['scheduled', 'sending', 'sent', 'cancelled', 'failed'])
+                .optional()
+                .describe('Only return emails in this state. Omit to see every state.'),
+            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'),
+        },
+    }, async (input) => {
+        const response = await lettr.get('/emails/scheduled', input);
+        const { scheduled_emails, pagination } = response.data;
+        if (scheduled_emails.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No scheduled emails found.' }],
+            };
+        }
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Scheduled transmission "${transmission_id}" cancelled.`,
+                    text: `Scheduled emails (total ${pagination.total}, page ${pagination.current_page} of ${pagination.last_page}, page size ${pagination.per_page}):\n\n${scheduled_emails
+                        .map(formatScheduledEmail)
+                        .join('\n\n')}`,
                 },
             ],
         };

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.5.0",
-  "description": "MCP server for the Lettr email API — send transactional emails, manage templates, domains, and webhooks from any AI assistant",
+  "version": "1.7.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",