list_messages

Instructions

Implementation Reference

• mcp/index.js:201-220 (handler)

  The MCP tool handler for 'list_messages'. Registers the tool with schema (inbox_id, limit, unread), resolves the default inbox if needed, and makes a GET request to /v1/inboxes/{inbox_id}/messages

  server.tool(
    'list_messages',
    'List messages. If inbox_id is omitted, uses the default inbox.',
    {
      inbox_id: idSchema.optional().describe('Inbox ID (optional, uses default inbox)'),
      limit: z.number().optional().describe('Max messages to return (default 20)'),
      unread: z.boolean().optional().describe('Only show unread messages')
    },
    async ({ inbox_id, limit = 20, unread }) => {
      if (!inbox_id) {
        const inbox = await getOrCreateDefaultInbox();
        if (inbox.error) return { content: [{ type: 'text', text: JSON.stringify(inbox, null, 2) }] };
        inbox_id = inboxId(inbox);
      }
      const params = new URLSearchParams({ limit: String(limit) });
      if (unread) params.set('unread', 'true');
      const result = await api('GET', `/v1/inboxes/${inbox_id}/messages?${params}`);
      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
    }
  );

• mcp/index.js:201-220 (registration)

  Registration of the 'list_messages' tool via server.tool() with its schema and handler function

  server.tool(
    'list_messages',
    'List messages. If inbox_id is omitted, uses the default inbox.',
    {
      inbox_id: idSchema.optional().describe('Inbox ID (optional, uses default inbox)'),
      limit: z.number().optional().describe('Max messages to return (default 20)'),
      unread: z.boolean().optional().describe('Only show unread messages')
    },
    async ({ inbox_id, limit = 20, unread }) => {
      if (!inbox_id) {
        const inbox = await getOrCreateDefaultInbox();
        if (inbox.error) return { content: [{ type: 'text', text: JSON.stringify(inbox, null, 2) }] };
        inbox_id = inboxId(inbox);
      }
      const params = new URLSearchParams({ limit: String(limit) });
      if (unread) params.set('unread', 'true');
      const result = await api('GET', `/v1/inboxes/${inbox_id}/messages?${params}`);
      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
    }
  );

• mcp/index.js:204-208 (schema)

  Zod schema for the list_messages tool: inbox_id (optional number/string), limit (optional number, default 20), unread (optional boolean)

  {
    inbox_id: idSchema.optional().describe('Inbox ID (optional, uses default inbox)'),
    limit: z.number().optional().describe('Max messages to return (default 20)'),
    unread: z.boolean().optional().describe('Only show unread messages')
  },

• sdk/node/src/index.js:54-58 (helper)

  Node.js SDK helper method listMessages(inboxId, {limit, offset, unread}) that calls the API

  listMessages(inboxId, { limit = 50, offset = 0, unread } = {}) {
    const params = new URLSearchParams({ limit, offset });
    if (unread) params.set('unread', 'true');
    return this._request('GET', `/v1/inboxes/${inboxId}/messages?${params}`);
  }

• sdk/python/clawaimail/client.py:51-53 (helper)

  Python SDK helper method list_messages(inbox_id, limit, offset, unread) that calls the API

  def list_messages(self, inbox_id: int, limit: int = 50, offset: int = 0, unread: bool = False):
      params = urlencode({"limit": limit, "offset": offset, **({"unread": "true"} if unread else {})})
      return self._request("GET", f"/v1/inboxes/{inbox_id}/messages?{params}")