Reading a Mailbox's History: Pagination and Message IDs Explained

Reading what's arrived in a DimeBox agent inbox is free, token-gated, and offered through exactly two endpoints: list everything, or fetch one specific message. Both require the inbox's read token (see Read Tokens Explained) and neither requires payment — reading has always been free, on both the list and the single-message routes.

Listing everything

curl https://dimebox.app/api/inboxes/acme-support/messages \
  -H 'X-Inbox-Token: inbox_...'

This returns every message in the inbox's current history — both directions (inbound and outbound), both receive channels, newest first, paginated. "Current history" matters here: an inbox retains only its newest N messages by default, with older ones pruned automatically — see The Rolling Message Window: How Inbox Pruning Works. What this endpoint returns reflects whatever's still inside that rolling window, not a permanent archive.

Fetching one message by ID

Every message carries a message_id — a UUID, returned as the first field in each entry from the list endpoint — which lets you fetch that one message's full details directly instead of paging through the whole list looking for it:

curl https://dimebox.app/api/inboxes/acme-support/messages/03d02b6a-30c4-43ba-877c-aefbe560d159 \
  -H 'X-Inbox-Token: inbox_...'

Why IDs are scoped to their own inbox

A message_id is looked up scoped to the inbox named in the URL. A real, valid message ID that belongs to a different inbox returns a 404 here, even with a valid read token for the inbox you're actually querying. Neither an inbox nor a message ever returns its internal database row number, only its UUID or slug — so there's no way to enumerate other inboxes' data by incrementing a number up or down. See How DimeBox Prevents Inbox Name Enumeration for the broader design pattern this is part of.

Building a sensible read pattern

For most agent workflows, the practical pattern is: list recent messages (or get pushed a webhook — see Polling vs Webhooks), identify the specific message that matters, then fetch it by ID if you need its full detail beyond what the list view already includes. For an inbox that's expected to receive a meaningful volume of mail over time, don't assume every message you've ever seen is still retrievable later — the rolling window means older entries eventually age out, so anything worth keeping long-term should be captured by the agent itself at read time, not re-fetched from DimeBox indefinitely.