Losing Your Inbox Read Token: What Happens Next

The read token is shown exactly once, in the response body of the call that created the inbox. If that response is lost — a crash before it's persisted, a log that got truncated, a copy-paste that missed a character — there is, today, no recovery flow. No "forgot your token" link, no support ticket that gets you a replacement, no admin override that looks it up and resends it. This is worth understanding precisely, because what's actually lost is narrower than it sounds.

What still works without the token

The read token gates exactly one thing: the two read endpoints, GET /api/inboxes/{slug}/messages and GET /api/inboxes/{slug}/messages/{message_id}, both of which require it as X-Inbox-Token. Nothing else about the inbox depends on it:

• The address keeps receiving mail through both channels — the free third-party relay and the paid priority route — exactly as before. Nothing about losing the token stops mail from arriving.
• Sending from the inbox keeps working too. POST /api/inboxes/{slug}/send is gated by payment, not by the read token, so anyone able to pay can still send from the address.

What's gone is visibility. Mail keeps accumulating in the rolling window — see the rolling message window — but nothing can read it out, and it will eventually be pruned, unread, as newer messages push it out of the cap.

Why there's no reset

A password reset works because there's an account behind the password — something to verify the request against: a recovery email, a security question, a support agent who can confirm identity some other way. DimeBox inboxes don't have that layer. There's no account, and DimeBox never records which wallet paid to create a given inbox, so there's nothing to check a "prove you're the owner" request against even if a reset flow existed. Who owns an agent's inbox covers why that link was never built in the first place.

There's also a more direct technical reason: DimeBox doesn't store the token in a form it could resend even if it wanted to. What's kept is a hash, sufficient to verify a token presented later, not sufficient to reconstruct the original string. Hashing secrets instead of storing them covers that pattern across DimeBox's credential model generally — it isn't specific to read tokens, and it's the same reason there's no "resend my webhook secret" option either.

What to do instead

There's no path back to the old token, so the practical options are narrow:

• Prevent it up front. Persist the token to durable storage synchronously, as part of handling the provisioning response — not as a follow-up step, not held only in memory until some later checkpoint. Read tokens explained covers the handling pattern in more detail.
• Set a webhook at creation time. A webhook_url configured when the inbox is provisioned gives you a second, independent way to learn that mail arrived, which doesn't help you read the full message body without the token, but at least tells you something happened. See the webhook notifications guide.
• Provision a new inbox. If read access to a given address is permanently gone, the only way forward is a fresh POST /api/inboxes or claim call. That's a new slug and a new token — old mail under the old slug doesn't move over, and if you'd claimed a custom name before, claiming it again (if it's even still available) means paying the $1.00 a second time.

None of this is a flaw to work around so much as a direct consequence of the inbox having no owner record to recover against in the first place — the same property that keeps DimeBox from knowing which wallet paid for which inbox also means nobody, including DimeBox, can hand you back a token that's gone. Treat the moment right after provisioning an inbox as the one chance to get this right.

A checklist for the moment you provision

Because there's exactly one chance to capture the token, it's worth having a fixed routine rather than relying on remembering to do it:

• Persist read_token (and webhook_secret, if you set one) to durable storage before the provisioning function returns control to the rest of your program.
• Confirm the write succeeded before treating provisioning as done — a successful 201 followed by a failed write to your own storage is functionally the same as never having saved it.
• Avoid routing the raw response through general-purpose logging that might not be treated as sensitive, for the same reason you wouldn't log a password.

None of this is unique to DimeBox — it's the same discipline any one-time-secret system demands, the same way you'd treat a database credential shown once in a provisioning script's output. The difference here is that there's no safety net on the other end — no support queue, no identity check, no fallback — if the discipline slips even once.