list_emails

Instructions

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");
  }