list_emails
Retrieve all newsletter emails from Buttondown, with optional filtering by draft, scheduled, or sent status.
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)The handler function that implements the logic for the 'list_emails' tool. It handles the optional status parameter, calls appropriate API methods, formats the email list, and returns a structured text response.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)Zod schema defining the input parameters for the list_emails tool, specifically the optional 'status' field.{ status: z .enum(["draft", "scheduled", "sent"]) .optional() .describe("Optional status to filter emails by"), },
- src/mcp/index.ts:53-114 (registration)Registration of the 'list_emails' tool on the MCP server, including name, description, schema, and handler reference.this.server.tool( "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 to list draft emails, used when status is 'draft' or default.async listDrafts(): Promise<ButtondownEmailsResponse> { return this.request<ButtondownEmailsResponse>("/emails?status=draft"); }
- src/api/client.ts:68-70 (helper)Helper method to list scheduled emails, used when status is 'scheduled'.async listScheduledEmails(): Promise<ButtondownEmailsResponse> { return this.request<ButtondownEmailsResponse>("/emails?status=scheduled"); }
- src/api/client.ts:72-74 (helper)Helper method to list sent emails, used when status is 'sent'.async listSentEmails(): Promise<ButtondownEmailsResponse> { return this.request<ButtondownEmailsResponse>("/emails?status=sent"); }