An agent that needs to send email usually needs two things: something to say, and a way to say it. Most stacks wire those together with a prompt template, a separate model call, and an SMTP client bolted on afterward. DimeBox collapses that into a single paid HTTP call — drafting and sending can happen in the same request, against the same inbox.
There are two ways to turn a brief into email, and they solve different problems:
POST /api/emails/generate — drafts an email and hands back { subject, body }. No inbox involved, nothing gets sent. Price: $0.02 per call. Useful when an agent wants the copy but is sending through its own channel, or just wants to preview wording before committing to anything.POST /api/inboxes/{slug}/send — sends from a real inbox. If that inbox has AI drafting enabled (the default), the same kind of brief drafts and sends in one paid call. Price: $0.01 per call.If an agent already has an inbox — see provisioning one in a single API call — the second route is almost always the one to use. The first is for cases where drafting and sending are genuinely separate concerns, or where there is no inbox at all.
Both routes accept the same shape of brief. At minimum, a recipient and a purpose:
{
"recipient": "[email protected]",
"purpose": "follow up after our demo call"
}Optionally add tone, a key_points array, and a sender name to steer the output without writing the email by hand. See tone, key points, and purpose for how those fields actually change what comes back, and designing prompts for reliable AI-drafted email for brief-writing patterns that hold up across many calls rather than working once and drifting.
Every call above is unpaid on the first attempt. The response is a 402 describing the price; an agent signs a USDC payment and retries with a PAYMENT-SIGNATURE header — the x402 protocol in one sentence. An agent that would rather skip that round trip can use a card-funded wallet instead: the same call, with an Authorization: Bearer header carrying a wallet secret in place of a signature. See the wallet page or the API quickstart for both paths end to end.
A drafting-only call to /api/emails/generate returns synchronously — the subject and body come back in the response body itself. A send call behaves differently: it returns 202 Accepted immediately, before the message has actually left. Delivery runs on a background queue rather than inline with the paid HTTP response. See queued delivery explained for why that distinction exists, and the anatomy of an email-drafting call for a field-by-field walkthrough of the full request/response cycle, draft through delivery.
# 1. Call unpaid, get a 402 describing the price
curl -X POST https://dimebox.app/api/inboxes/acme-support/send \
-H 'Content-Type: application/json' \
-d '{"to":"[email protected]","purpose":"follow up after our demo call","tone":"friendly but concise"}'
# 2. Sign the payment the 402 described, retry with it attached
curl -X POST https://dimebox.app/api/inboxes/acme-support/send \
-H 'Content-Type: application/json' \
-H 'PAYMENT-SIGNATURE: <signed payment>' \
-d '{"to":"[email protected]","purpose":"follow up after our demo call","tone":"friendly but concise"}'The second call is identical except for the header — same body, same brief. A card-funded wallet replaces both steps with a single call carrying a bearer token instead of a signature.
The alternative — call /api/emails/generate, read back the subject and body, then call send with to/subject/body as a raw message — works fine. The bundled version is just fewer round trips: one brief in, one queued message out. Keep the two calls separate if you need the drafted copy for something else first, such as logging it or routing it through a human approval step before anything goes out. Otherwise, send with a brief directly and skip the intermediate call.
Not every agent should be allowed to draft at all. For sends restricted to exact wording the calling code already wrote, see disabling AI drafting and drafted vs raw email for how to make that the enforced default rather than a convention someone forgets to follow.
The pattern is the same whether the agent is a sales tool sending a follow-up, a support bot answering a question, or a monitoring system notifying someone that a job finished: a brief goes in, a queued send comes out, one call, one price. See follow-up emails on autopilot and building an AI support agent that replies by email for two concrete versions of this loop with their own failure modes and guardrails.
Every call above works identically on Base Sepolia, DimeBox's test network, using test USDC that costs nothing real to sign and spend. That makes it possible to exercise the full draft-and-send path — including the 402, the signature, and the queued delivery — before pointing an agent at mainnet. See Base Sepolia vs Base mainnet and testing agent email flows end-to-end on Base Sepolia for how to set that up, and a Python quickstart for paying DimeBox with x402 or the Node.js equivalent for a working client to start from.
The $0.02 and $0.01 figures above are what this deployment charges today, read live from configuration — not a value worth hardcoding into a client if you want to stay correct if either number ever changes. How to discover DimeBox's live prices programmatically covers reading the authoritative current price straight from the API instead of a blog post or a cached constant.