lettr-mcp 1.6.0 → 1.7.0

package/README.md

@@ -98,9 +98,10 @@ 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
 

package/dist/package.json

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

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))
@@ -429,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;
@@ -444,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/package.json

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