List messages

GEThttps://myagentmail.com/v1/inboxes/{id}/messages

Lists messages in an inbox. Tracking fields (firstOpenedAt, openCount, firstClickedAt, clickCount, etc.) are returned on every row — no separate detail fetch needed for an engagement-aware view. Filters can be combined.

Path parameters

id

required

string

Inbox UUID

Query parameters

`limit` integer
`offset` integer
`direction` "inbound" \| "outbound"
`opened` boolean	When true, return only messages with open_count > 0.
`clicked` boolean	When true, return only messages with click_count > 0. Useful for cadence engines listing engaged leads who haven't yet replied.
`engagedSince` string	ISO-8601 timestamp. Returns only messages whose lastOpenedAt OR lastClickedAt is at or after this time. Use for incremental polling — pass the timestamp of your last successful sync.

Responses

200application/jsonOK

`messages` object[]
`id` string	format: uuid
`direction` "inbound" \| "outbound"	enum: "inbound" \| "outbound"
`from` string
`to` string
`subject` string
`plainBody` string
`htmlBody` string
`isRead` boolean
`threadId` string	format: uuid
`messageIdHeader` string
`inReplyTo` string
`receivedAt` string	format: date-time
`firstOpenedAt` string	Timestamp of the first recipient open event (outbound emails only). Populated by ZeptoMail tracking when track:true on send. NULL until the first open. Note: opens are noisy due to Apple Mail Privacy Protection — ~30-50% of opens are auto-fetches by Apple's image proxy, not real user opens. Gate business logic on click events instead when possible. format: date-time
`lastOpenedAt` string	Most recent open event. Updates on every open. format: date-time
`openCount` integer	Total opens. Subject to the same Apple-MPP noise as the timestamps. default: 0
`firstClickedAt` string	Timestamp of the first recipient link-click. Reliable signal of engagement (unlike opens, click events are not Apple-MPP-poisoned). NULL until the first click. format: date-time
`lastClickedAt` string	format: date-time
`clickCount` integer	default: 0
`attachments` object[]
`id` string	format: uuid
`filename` string
`contentType` string
`sizeBytes` integer
`pagination` object
`total` integer
`limit` integer
`offset` integer

Authentication

Send your API key in the X-API-Key header (or Authorization: Bearer <key>). Any prefix accepted by this endpoint — tk_, wk_, ak_, or sa_ — is documented in the key prefix table.

Request

import { MyAgentMail } from "myagentmail";

const client = new MyAgentMail({ apiKey: process.env.MYAGENTMAIL_API_KEY! });

// GET /v1/inboxes/{id}/messages
const result = await client.request("get", "/v1/inboxes/{id}/messages", { params: { id: "00000000-0000-0000-0000-000000000000" } });

Example response · 200

{
  "messages": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "direction": "inbound",
      "from": "string",
      "to": "string",
      "subject": "string",
      "plainBody": "string",
      "htmlBody": "string",
      "isRead": false,
      "threadId": "00000000-0000-0000-0000-000000000000",
      "messageIdHeader": "string",
      "inReplyTo": "string",
      "receivedAt": "2026-07-17T14:07:30.540Z",
      "firstOpenedAt": "2026-07-17T14:07:30.540Z",
      "lastOpenedAt": "2026-07-17T14:07:30.540Z",
      "openCount": 0,
      "firstClickedAt": "2026-07-17T14:07:30.540Z",
      "lastClickedAt": "2026-07-17T14:07:30.540Z",
      "clickCount": 0,
      "attachments": [
        {}
      ]
    }
  ],
  "pagination": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}