list_emails
Retrieve and filter emails by status (draft, scheduled, sent) to manage and organize your Buttondown newsletter content efficiently.
Instructions
List all emails, optionally filtered by status (draft, scheduled, sent)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Optional status to filter emails by |
Implementation Reference
- src/mcp/index.ts:62-113 (handler)Handler function for the 'list_emails' tool. Ensures API key, fetches emails based on optional status filter (draft, scheduled, sent), formats the results, and returns a JSON string in MCP content format.async ({ status }) => { await this.ensureApiKey(); let response; switch (status) { case "draft": response = await this.api.listDrafts(); break; case "scheduled": response = await this.api.listScheduledEmails(); break; case "sent": response = await this.api.listSentEmails(); break; default: // If no status specified, list all drafts by default response = await this.api.listDrafts(); } // Format the response to be more readable const formattedEmails = response.results.map((email) => ({ id: email.id, subject: email.subject || "Untitled", status: email.status, created: email.creation_date, scheduled_for: email.scheduled_for || null, publish_date: email.publish_date || null, analytics: email.analytics ? { recipients: email.analytics.recipients, opens: email.analytics.opens, clicks: email.analytics.clicks, } : null, })); return { content: [ { type: "text", text: JSON.stringify( { total: response.count, emails: formattedEmails, }, null, 2 ), }, ], }; }
- src/mcp/index.ts:56-61 (schema)Input schema using Zod for the 'list_emails' tool, defining optional 'status' parameter.{ status: z .enum(["draft", "scheduled", "sent"]) .optional() .describe("Optional status to filter emails by"), },
- src/mcp/index.ts:54-114 (registration)Registration of the 'list_emails' tool on the MCP server using server.tool(), including description, schema, and inline handler."list_emails", "List all emails, optionally filtered by status (draft, scheduled, sent)", { status: z .enum(["draft", "scheduled", "sent"]) .optional() .describe("Optional status to filter emails by"), }, async ({ status }) => { await this.ensureApiKey(); let response; switch (status) { case "draft": response = await this.api.listDrafts(); break; case "scheduled": response = await this.api.listScheduledEmails(); break; case "sent": response = await this.api.listSentEmails(); break; default: // If no status specified, list all drafts by default response = await this.api.listDrafts(); } // Format the response to be more readable const formattedEmails = response.results.map((email) => ({ id: email.id, subject: email.subject || "Untitled", status: email.status, created: email.creation_date, scheduled_for: email.scheduled_for || null, publish_date: email.publish_date || null, analytics: email.analytics ? { recipients: email.analytics.recipients, opens: email.analytics.opens, clicks: email.analytics.clicks, } : null, })); return { content: [ { type: "text", text: JSON.stringify( { total: response.count, emails: formattedEmails, }, null, 2 ), }, ], }; } );
- src/api/client.ts:64-66 (helper)Helper method in ButtondownAPI client to fetch draft emails, called by the tool handler.async listDrafts(): Promise<ButtondownEmailsResponse> { return this.request<ButtondownEmailsResponse>("/emails?status=draft"); }
- src/api/client.ts:68-70 (helper)Helper method in ButtondownAPI client to fetch scheduled emails, called by the tool handler.async listScheduledEmails(): Promise<ButtondownEmailsResponse> { return this.request<ButtondownEmailsResponse>("/emails?status=scheduled"); }