MultiMail

Instructions

Implementation Reference

• src/index.ts:120-134 (handler)

  Main implementation of check_inbox tool: registration, schema definition (status and mailbox_id parameters), and the async handler function that queries the /v1/mailboxes/{id}/emails endpoint and returns email summaries

  // Tool 3: check_inbox
  server.tool(
    "check_inbox",
    "List emails in your inbox. Returns email summaries including id, from, to, subject, status, received_at, and has_attachments. Does NOT include the email body — call read_email with the email ID to get the full message content.",
    {
      status: z.enum(["unread", "read", "archived"]).optional().describe("Filter by email status (default: all)"),
      mailbox_id: z.string().optional().describe("Mailbox ID (uses MULTIMAIL_MAILBOX_ID env var if not provided)"),
    },
    async ({ status, mailbox_id }) => {
      const id = getMailboxId(mailbox_id);
      const query = status ? `?status=${status}` : "";
      const data = await apiCall("GET", `/v1/mailboxes/${encodeURIComponent(id)}/emails${query}`);
      return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
    }
  );

• src/index.ts:70-80 (helper)

  Helper function getMailboxId that resolves the mailbox ID from either the function argument or the MULTIMAIL_MAILBOX_ID environment variable, throwing an error if neither is provided

  function getMailboxId(argsMailboxId?: string): string {
    const id = argsMailboxId || DEFAULT_MAILBOX_ID;
    if (!id) {
      throw new Error(
        "No mailbox_id provided and MULTIMAIL_MAILBOX_ID is not set. " +
        "Either pass mailbox_id or set the MULTIMAIL_MAILBOX_ID environment variable. " +
        "Use list_mailboxes to discover available mailboxes."
      );
    }
    return id;
  }

• src/index.ts:28-58 (helper)

  Helper function apiCall that makes authenticated HTTP requests to the MultiMail API with proper error handling for various status codes (401, 403, 429, etc.)

  async function apiCall(method: string, path: string, body?: unknown): Promise<unknown> {
    const url = `${BASE_URL}${path}`;
    const headers: Record<string, string> = {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    };
  
    const res = await fetch(url, {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
    });
  
    const data = await parseResponse(res);
  
    if (!res.ok) {
      if (res.status === 401) {
        throw new Error("Invalid API key. Check MULTIMAIL_API_KEY environment variable.");
      }
      if (res.status === 403) {
        throw new Error(`API key lacks required scope for this operation. ${data.error || ""}`);
      }
      if (res.status === 429) {
        const retryAfter = res.headers.get("retry-after") || "unknown";
        throw new Error(`Rate limit exceeded. Retry after ${retryAfter} seconds.`);
      }
      throw new Error(`API error ${res.status}: ${data.error || JSON.stringify(data)}`);
    }
  
    return data;
  }