POST /api/inboxes/{slug}/send accepts two different request shapes, and which one applies depends on how the inbox was provisioned, not on anything in the request itself. Knowing the difference matters more than it looks, because it determines whether a model ever gets a say in the exact words that leave an inbox.
Raw mode is the simple case: exact wording, sent as-is.
{ "to": "[email protected]", "subject": "Hi", "body": "..." }Nothing interprets or rewrites subject or body. Whatever the calling code puts in those fields is exactly what goes out. Raw mode is always available, on every inbox, regardless of how it was provisioned.
Drafted mode replaces exact wording with a brief, and only works on an inbox that has AI drafting enabled — which is the default:
{ "to": "[email protected]", "purpose": "follow up", "tone": "...", "key_points": [...] }Send a purpose to an inbox that was provisioned with drafting turned off, and it fails validation with a 422 — the request never reaches a model. See disabling AI drafting for how to provision that kind of inbox on purpose, and the anatomy of a drafting call for what actually happens between the brief going in and a message landing in the send queue.
Both modes cost the same: $0.01 per send. Choosing drafted mode over raw mode isn't a cost decision, it's a control decision — whether the exact text is something your code already decided, or something you're asking DimeBox to work out from a brief.
A generic email API that only ever sends exact text puts the burden of writing good copy entirely on the caller — fine for a templated receipt, worse for an agent replying to something unpredictable it just read. See why a generic email API isn't built for autonomous agents for that gap in more detail. Drafted mode exists to close it, without forcing every caller through it: an inbox that only ever needs exact, pre-approved wording shouldn't have a model anywhere near its outbound path, and raw mode is how that stays true.
The choice isn't made per send — it's a property of the inbox, set at provisioning time with ai_drafting_enabled (default true), and it applies to every send against that inbox for its whole lifetime. There's no flag on an individual send call to force raw mode on a drafting-enabled inbox or vice versa. If an agent genuinely needs both modes — some sends drafted, some exact — that currently means either sending raw text through a drafting-enabled inbox (always allowed) or running two separate inboxes with different defaults.
Use drafted mode when the agent has a goal but not a script — a follow-up, a reply to something unpredictable, anything where the useful work is turning intent into words. Use raw mode, or an inbox with drafting disabled entirely, when the exact wording is already decided elsewhere: a template, a compliance-reviewed notice, anything where a model rewriting the text would be a liability rather than a convenience. Why outbound email should never be free covers the pricing side of that same tradeoff — both modes cost money precisely because both can do real damage if sent carelessly.
For the exact field-level validation rules on both shapes, see the send reference in the docs.
There's no per-call flag to force raw mode on a drafting-enabled inbox, or to request drafting on an inbox that was provisioned without it — the setting lives on the inbox, decided once with ai_drafting_enabled when it's created. If a fleet of agents needs both behaviors, the straightforward approach is two inboxes with different defaults rather than one inbox trying to serve both needs. See provisioning an inbox in one API call for setting that flag at creation time.
It's worth being precise about what raw mode actually guarantees: exact wording, not safe wording. Sending raw text still costs $0.01, still requires a valid to address, and still goes out under the inbox's address and whatever reputation that carries. Raw mode removes a model from the loop; it doesn't add any review step in its place. If an agent is generating the raw subject/body itself with its own model before calling send, that content deserves the same scrutiny a drafted brief would get — raw mode just moves where the drafting happens, from DimeBox's side of the call to yours.
Some agents already have their own model in the loop for other reasons — summarizing a conversation, deciding what to say next — and would rather generate the final email text themselves and send it exactly as written, without a second drafting pass on DimeBox's side. Raw mode is built for exactly that: hand over finished subject and body fields, and nothing rewrites them. This is also the natural choice when migrating from an existing SMTP-based pipeline that already produces finished email text and just needs a place to send it from — see DimeBox vs rolling your own SMTP + LLM stack for that comparison in more depth.