A DimeBox inbox isn't an archive — it's a window. By default it holds the newest 500 messages, across both directions and both receive channels, newest first. Once an inbox has 500 messages in it, the arrival of a 501st doesn't grow the list; it pushes the oldest message out to make room. This is called out explicitly rather than left as a surprise, because it changes how you should build around it.
Everything in the inbox's single, flat, time-ordered list counts: messages you sent out, messages that arrived through the free ordinary-SMTP channel, and messages that arrived through the paid priority channel. There's no separate cap per direction or per channel — it's one list, one limit, pruned from the oldest end as new messages push it over the cap.
This is the direct consequence of an inbox being designed as a working buffer rather than a mail archive. There's no IMAP, no folders, no search — see why DimeBox inboxes aren't full mailboxes for the fuller argument — and an unbounded history doesn't fit that shape either. A fixed, rolling cap keeps the cost and complexity of storing and serving message history predictable regardless of how long an inbox has existed or how much mail has flowed through it.
If an agent's workflow depends on something that happened more than a few hundred messages ago, that information is gone by the time you'd go looking for it — there's no way to retrieve a pruned message, paid or not. A few implications worth building around:
Within the window, every message has a stable message_id — a UUID, not a row number — which you can use to fetch one message's full detail directly rather than paging through the whole list every time. Reading a mailbox's history covers pagination and message-ID lookups in full, including what happens when you request a message that's already been pruned (the same thing that happens for a message ID that never existed: a lookup scoped to this inbox simply doesn't find it).
The cap and the pruning behavior apply the same way whether the inbox came from the free provisioning route or a paid, custom-named one — see losing your read token for the other side of this coin: even while messages are sitting inside the window, they're only reachable with the one credential that was ever issued for reading them.
Say an inbox has been running for a while and sits at exactly 500 messages, the default cap. A new message arrives through the free SMTP channel. The inbox doesn't become 501 messages long — the oldest message in the list is dropped in the same operation that adds the new one, and the inbox stays at 500. This happens automatically, with no call required to trigger it and no way to opt out of it for a given inbox. The window rolls whether or not anyone is watching.
Once a message has aged out of the window, its message_id stops resolving. A request to GET /api/inboxes/{slug}/messages/{message_id} for a pruned message behaves the same as a request for a message ID that never existed in that inbox — it 404s. There's no distinction exposed between "never existed" and "existed once but aged out"; both look identical from the caller's side, consistent with there being no archive layer underneath the window at all.
For most short-lived agent tasks — send a message, get a reply, close out the exchange — 500 messages is more headroom than you'll ever use before the inbox itself is abandoned. The window becomes a real design constraint mainly for long-running, high-volume inboxes: something handling replies at scale, or an inbox that's been alive for months and accumulates incidental traffic. For those, the right pattern is to treat every webhook notification or poll result as the one chance to capture a message permanently if it matters, rather than assuming it will still be sitting in the inbox days later.