Calling POST /api/inboxes/{slug}/send doesn't mean the email has gone out by the time the response comes back. It means the request was accepted and queued — the response is 202 Accepted, not 200, and that distinction is the whole topic.
A 202 means the paid action — validating the request, drafting if needed, settling payment — completed successfully, and the actual email delivery was handed to a background queue rather than attempted synchronously inside the HTTP request. The send itself then moves through states: queued first, then sent or failed once delivery to the outbound mail relay actually resolves.
An SMTP handoff to an outbound mail relay can take anywhere from milliseconds to several seconds, and occasionally longer if the relay itself is under load. Holding a paid HTTP connection open for that entire window ties up a request thread for no benefit to the caller — the payment has already settled by the time delivery is attempted, so there's nothing left for the caller to usefully wait on except the delivery outcome itself, which is better checked separately anyway.
Poll GET /api/inboxes/{slug}/messages (or the single-message variant) with the inbox's read token to see a sent message's status move from queued to its final state. There's currently no webhook for outbound status changes — only inbound messages trigger a webhook push, as covered in the webhook guide — so confirming a send's outcome today means checking the message list, not waiting for a push.
Worth being explicit about: the $0.01 charge for a send settles based on the 202 response to the send call itself, not on whether the message is later marked sent or failed. This is consistent with the rule across every paid route — payment settles on a response under 400, and 202 is one. A downstream delivery failure at the mail-relay stage, after the request already succeeded, doesn't retroactively refund the call.
Anything that depends on a message actually reaching its recipient — confirming a time-sensitive notice went out, for instance — needs its own check against the message status, not an assumption that 202 equals delivered. For an agent sending at any real frequency, that usually means a short follow-up check rather than a single fire-and-forget call. The anatomy of an email-drafting call walks through where this fits in the full request lifecycle, and what "priority" delivery actually means covers the equivalent question on the receiving side, where a similar distinction exists between accepted and guaranteed.
Full status transitions and polling details are in the send reference.
It's worth noticing that this is the mirror image of how priority receiving works. The paid priority receive channel writes a message directly into an inbox's history in the same request that settles payment — no queue, no delay, immediate. Sending goes the other way: the paid part (validation, drafting, payment) happens synchronously, but the actual delivery to the outbound mail relay is deliberately deferred. What "priority" delivery actually means covers the receiving side of that asymmetry in detail — the short version is that writing into DimeBox's own database can be instant and guaranteed, while handing a message to an external SMTP relay cannot, so the two paths are built differently on purpose.
Checking status immediately after a send call almost always shows queued — delivery to the outbound relay hasn't resolved yet in the time it takes to make a second HTTP call. A short backoff before the first check, rather than polling in a tight loop right after the send, avoids wasting calls on a status that's virtually guaranteed not to have changed yet:
// after the 202 response, wait briefly before the first status check
await sleep(2000);
const messages = await fetch(`/api/inboxes/${slug}/messages`, {
headers: { "X-Inbox-Token": readToken },
});Reading the message list is free regardless of how often it's called, so there's no cost pressure pushing toward fewer checks — the only cost of over-polling is wasted compute on your own side, not a charge from DimeBox.
A 202 and a queued status mean the request was accepted into DimeBox's own pipeline — they say nothing about whether the recipient's mail server will ultimately accept the message once it leaves the outbound relay. That last leg is outside DimeBox's control the same way it would be for any sender: a recipient's spam filtering, a full mailbox, or a bounced address can all still produce a final failed status, or in some cases no visible failure at all if the recipient's server silently drops it after accepting it. A sent status means delivery to the outbound relay succeeded, not that a human definitely read the message.
For a notification where timing matters — an alert that something needs attention now — the gap between "accepted" and "actually delivered" is worth building around explicitly, rather than treating the 202 as the finish line. Checking status after a short delay, and having a fallback action if a send doesn't reach sent within a reasonable window, closes that gap better than assuming queued always resolves quickly.