MultiMail

Instructions

Implementation Reference

• src/index.ts:89-98 (registration)

  Tool registration for list_mailboxes. Defines the tool name, description, empty input schema (no parameters), and the async handler function that calls the API.

  // Tool 1: list_mailboxes
  server.tool(
    "list_mailboxes",
    "List all mailboxes available to this API key. Returns each mailbox's ID, email address, oversight mode, and display name. Use this to discover your mailbox ID if MULTIMAIL_MAILBOX_ID is not set.",
    {},
    async () => {
      const data = await apiCall("GET", "/v1/mailboxes");
      return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
    }
  );

• src/index.ts:94-97 (handler)

  Handler implementation that executes the tool logic. Makes a GET request to /v1/mailboxes endpoint and returns the JSON-formatted response.

  async () => {
    const data = await apiCall("GET", "/v1/mailboxes");
    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
  }

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

  apiCall helper function used by the list_mailboxes handler. Makes authenticated HTTP requests to the MultiMail API with proper error handling for various status codes.

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

• src/index.ts:19-26 (helper)

  parseResponse helper function used by apiCall. Parses API responses from text to JSON with error handling for non-JSON responses.

  async function parseResponse(res: Response): Promise<Record<string, unknown>> {
    const text = await res.text();
    try {
      return JSON.parse(text) as Record<string, unknown>;
    } catch {
      throw new Error(`API returned non-JSON response (${res.status}): ${text.slice(0, 200)}`);
    }
  }

• src/index.ts:93-93 (schema)

  Input schema definition for list_mailboxes tool. Empty object indicates the tool accepts no input parameters.

  {},