lettr-mcp 1.2.0 → 1.4.0

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, addDomainTools, addEmailTools, addProjectTools, addSystemTools, addTemplateTools, addWebhookTools, } from './tools/index.js';
+import { addAudienceContactTools, addAudienceListTools, addAudienceMembershipTools, addAudiencePropertyTools, addAudienceSegmentTools, addAudienceTopicTools, addCampaignTools, addDomainTools, addEmailTools, addProjectTools, addSystemTools, addTemplateTools, addWebhookTools, } from './tools/index.js';
 const argv = minimist(process.argv.slice(2));
 const apiKey = argv.key || process.env.LETTR_API_KEY;
 const senderEmailAddress = argv.sender || process.env.SENDER_EMAIL_ADDRESS;
@@ -15,7 +15,7 @@ if (!apiKey) {
     console.error('No API key provided. Please set LETTR_API_KEY environment variable or use --key argument');
     process.exit(1);
 }
-const lettr = new LettrClient(apiKey);
+const lettr = new LettrClient(apiKey, packageJson.version);
 const server = new McpServer({
     name: 'lettr',
     version: packageJson.version,
@@ -31,6 +31,7 @@ addAudienceMembershipTools(server, lettr);
 addAudienceTopicTools(server, lettr);
 addAudiencePropertyTools(server, lettr);
 addAudienceSegmentTools(server, lettr);
+addCampaignTools(server, lettr);
 addSystemTools(server, lettr);
 async function main() {
     const transport = new StdioServerTransport();

package/dist/lettr.js

@@ -1,8 +1,10 @@
 const BASE_URL = 'https://app.lettr.com/api';
 export class LettrClient {
     apiKey;
-    constructor(apiKey) {
+    version;
+    constructor(apiKey, version) {
         this.apiKey = apiKey;
+        this.version = version;
     }
     async request(method, path, body, query) {
         const url = new URL(`${BASE_URL}${path}`);
@@ -16,6 +18,7 @@ export class LettrClient {
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
             Accept: 'application/json',
+            'User-Agent': `lettr-mcp/${this.version}`,
         };
         const options = { method, headers };
         if (body &&

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lettr-mcp",
-    "version": "1.2.0",
+    "version": "1.4.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/campaigns.js

@@ -0,0 +1,270 @@
+import { z } from 'zod';
+const CAMPAIGN_STATUSES = [
+    'draft',
+    'scheduled',
+    'preparing',
+    'in_review',
+    'sending',
+    'sent',
+    'failed',
+];
+const EVENT_TYPES = [
+    'injection',
+    'delivery',
+    'bounce',
+    'spam_complaint',
+    'open',
+    'click',
+    'list_unsubscribe',
+];
+const HTML_PREVIEW_CHARS = 500;
+function formatStats(s) {
+    return `opens ${s.opens} (unique ${s.unique_opens}), clicks ${s.clicks} (unique ${s.unique_clicks}), deliveries ${s.deliveries}, bounces ${s.bounces}, spam ${s.spam_complaints}, unsubscribes ${s.unsubscribes}`;
+}
+function formatCampaign(c) {
+    const sender = c.from_email
+        ? c.from_name
+            ? `${c.from_name} <${c.from_email}>`
+            : c.from_email
+        : 'none';
+    const lines = [
+        `ID: ${c.id}`,
+        `Name: ${c.name}`,
+        `Status: ${c.status}`,
+        `Subject: ${c.subject ?? 'none'}`,
+        `From: ${sender}`,
+        `Reply-to: ${c.reply_to ?? 'none'}`,
+        `Recipients: ${c.total_recipients ?? 'not yet resolved'}`,
+        `Sent count: ${c.sent_count}`,
+        `Scheduled at: ${c.scheduled_at ?? 'not scheduled'}`,
+        `Sent at: ${c.sent_at ?? 'not sent'}`,
+        `Created: ${c.created_at}`,
+        `Stats: ${formatStats(c.stats)}`,
+    ];
+    return lines.join('\n');
+}
+function formatEvent(e) {
+    const extras = [];
+    if (e.reason)
+        extras.push(`reason: ${e.reason}`);
+    if (e.bounce_class)
+        extras.push(`bounce_class: ${e.bounce_class}`);
+    if (e.target_link_url)
+        extras.push(`url: ${e.target_link_url}`);
+    const suffix = extras.length > 0 ? ` — ${extras.join(', ')}` : '';
+    return `- ${e.timestamp} ${e.event_type} ${e.email} (id: ${e.event_id})${suffix}`;
+}
+export function addCampaignTools(server, lettr) {
+    server.registerTool('list-campaigns', {
+        title: 'List Campaigns',
+        description: 'List campaigns for your team, with pagination and an optional status filter. Each campaign includes embedded engagement stats. Use this to discover campaign IDs for the other campaign 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)
+                .max(10000)
+                .optional()
+                .describe('Page number (default 1)'),
+            status: z
+                .enum(CAMPAIGN_STATUSES)
+                .optional()
+                .describe('Filter by campaign status'),
+        },
+    }, async ({ per_page, page, status }) => {
+        const query = {};
+        if (per_page)
+            query.per_page = per_page;
+        if (page)
+            query.page = page;
+        if (status)
+            query.status = status;
+        const response = await lettr.get('/campaigns', query);
+        const { campaigns, pagination } = response.data;
+        if (campaigns.length === 0) {
+            return { content: [{ type: 'text', text: 'No campaigns found.' }] };
+        }
+        const lines = campaigns
+            .map((c) => `- ${c.name} (id: ${c.id}, status: ${c.status}, sent: ${c.sent_count})`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${pagination.total} campaign(s) — page ${pagination.current_page}/${pagination.last_page}:\n\n${lines}`,
+                },
+            ],
+        };
+    });
+    server.registerTool('get-campaign', {
+        title: 'Get Campaign',
+        description: 'Retrieve a single campaign by its ID, including embedded engagement stats and a preview of its rendered HTML content.',
+        inputSchema: {
+            campaignId: z.string().nonempty().describe('The campaign ID'),
+        },
+    }, async ({ campaignId }) => {
+        const response = await lettr.get(`/campaigns/${encodeURIComponent(campaignId)}`);
+        const campaign = response.data;
+        const html = campaign.html_content;
+        const htmlText = html == null
+            ? 'HTML content: none'
+            : `HTML content: ${html.length} chars\nPreview:\n${html.slice(0, HTML_PREVIEW_CHARS)}${html.length > HTML_PREVIEW_CHARS ? '…' : ''}`;
+        return {
+            content: [
+                { type: 'text', text: 'Campaign details:' },
+                { type: 'text', text: formatCampaign(campaign) },
+                { type: 'text', text: htmlText },
+            ],
+        };
+    });
+    server.registerTool('list-campaign-events', {
+        title: 'List Campaign Events',
+        description: `List engagement events (opens, clicks, bounces, etc.) for a campaign, with optional filters. Uses cursor-based pagination: this tool returns one page plus a \`next_cursor\`. Keep calling it with \`cursor\` set to the returned \`next_cursor\` until \`next_cursor\` is null. Note: when a filter is applied, a page can come back with no events but a non-null \`next_cursor\` — that means more pages remain, so keep paginating until \`next_cursor\` is null.`,
+        inputSchema: {
+            campaignId: z.string().nonempty().describe('The campaign ID'),
+            event_type: z
+                .enum(EVENT_TYPES)
+                .optional()
+                .describe('Filter by event type'),
+            email: z
+                .string()
+                .optional()
+                .describe('Filter by recipient email address'),
+            start_date: z
+                .string()
+                .optional()
+                .describe('Only events at or after this time (ISO 8601). A date-only value (e.g. 2026-05-01) is treated as start of day in UTC.'),
+            end_date: z
+                .string()
+                .optional()
+                .describe('Only events at or before this time (ISO 8601, inclusive). A date-only value covers the whole day in UTC.'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe('Max events per page (1-100, default 25)'),
+            cursor: z
+                .string()
+                .optional()
+                .describe('Pagination cursor from a previous response'),
+        },
+    }, async ({ campaignId, event_type, email, start_date, end_date, limit, cursor, }) => {
+        const query = {};
+        if (event_type)
+            query.event_type = event_type;
+        if (email)
+            query.email = email;
+        if (start_date)
+            query.start_date = start_date;
+        if (end_date)
+            query.end_date = end_date;
+        if (limit)
+            query.limit = limit;
+        if (cursor)
+            query.cursor = cursor;
+        const response = await lettr.get(`/campaigns/${encodeURIComponent(campaignId)}/events`, query);
+        const { events, next_cursor } = response.data;
+        const cursorNote = next_cursor == null
+            ? 'No more pages (next_cursor is null).'
+            : `More pages remain — call again with cursor: ${next_cursor}`;
+        if (events.length === 0) {
+            return {
+                content: [
+                    { type: 'text', text: `No events on this page. ${cursorNote}` },
+                ],
+            };
+        }
+        const lines = events.map(formatEvent).join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${events.length} event(s) on this page:\n\n${lines}\n\n${cursorNote}`,
+                },
+            ],
+        };
+    });
+    server.registerTool('send-campaign', {
+        title: 'Send Campaign',
+        description: 'Immediately send a draft campaign to its recipients. Before using this tool, you MUST double-check with the user that they want to send now. Warn them that this is irreversible and outward-facing — it dispatches real emails to recipients that cannot be recalled. The campaign must be a draft with a subject, sender, and content; on success it transitions to "preparing".',
+        inputSchema: {
+            campaignId: z.string().nonempty().describe('The campaign ID to send'),
+        },
+    }, async ({ campaignId }) => {
+        const response = await lettr.post(`/campaigns/${encodeURIComponent(campaignId)}/send`);
+        const status = response.data?.status;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: response.message ?? 'Campaign queued for sending.',
+                },
+                ...(status
+                    ? [{ type: 'text', text: `Status is now: ${status}` }]
+                    : []),
+            ],
+        };
+    });
+    server.registerTool('schedule-campaign', {
+        title: 'Schedule Campaign',
+        description: 'Schedule a draft campaign for future delivery, or reschedule an already-scheduled campaign to a new time. Before using this tool, you MUST confirm the time with the user and warn them that at the scheduled time this will dispatch real emails to recipients. The campaign must be a draft or already scheduled, with a subject, sender, and content.',
+        inputSchema: {
+            campaignId: z
+                .string()
+                .nonempty()
+                .describe('The campaign ID to schedule'),
+            scheduled_at: z
+                .string()
+                .nonempty()
+                .describe('Future delivery time (ISO 8601, e.g. 2026-06-01T09:00:00+02:00). Include a timezone offset or "Z"; a value without an offset is interpreted as UTC. Must be in the future.'),
+        },
+    }, async ({ campaignId, scheduled_at }) => {
+        const response = await lettr.post(`/campaigns/${encodeURIComponent(campaignId)}/schedule`, { scheduled_at });
+        const scheduledAt = response.data?.scheduled_at;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: response.message ?? 'Campaign scheduled for delivery.',
+                },
+                ...(scheduledAt
+                    ? [
+                        {
+                            type: 'text',
+                            text: `Scheduled at: ${scheduledAt}`,
+                        },
+                    ]
+                    : []),
+            ],
+        };
+    });
+    server.registerTool('unschedule-campaign', {
+        title: 'Unschedule Campaign',
+        description: 'Cancel a scheduled send, returning the campaign to draft. The campaign must currently be scheduled.',
+        inputSchema: {
+            campaignId: z
+                .string()
+                .nonempty()
+                .describe('The campaign ID to unschedule'),
+        },
+    }, async ({ campaignId }) => {
+        const response = await lettr.post(`/campaigns/${encodeURIComponent(campaignId)}/unschedule`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: response.message ?? 'Campaign unscheduled; returned to draft.',
+                },
+            ],
+        };
+    });
+}

package/dist/tools/index.js

@@ -4,6 +4,7 @@ export * from './audience-memberships.js';
 export * from './audience-properties.js';
 export * from './audience-segments.js';
 export * from './audience-topics.js';
+export * from './campaigns.js';
 export * from './domains.js';
 export * from './emails.js';
 export * from './projects.js';

package/package.json

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