Drafting a request against /api/emails/generate or a drafted send call gives you four fields to work with: recipient, purpose, tone, and key_points, plus an optional sender name. Three of them — purpose, tone, and key_points — do the actual work of shaping what comes back, and each controls something different.
purpose is required, capped at 2000 characters, and answers one question: why is this email being sent? It's the field that determines the overall shape and intent of the draft — a follow-up reads differently from an apology, which reads differently from a status update, even before tone or key points are applied. Keep it to the goal, not the supporting detail:
"purpose": "ask for a short extension on the project deadline"is doing its job better than a purpose that also tries to list every reason, every date, and every caveat in the same string — that detail belongs in key_points instead.
tone is optional and freeform, and it shouldn't be asked to do purpose's job. It governs register and style — formal versus casual, terse versus warm — without changing what the email is actually about. Short, specific descriptions produce more consistent results than broad ones: "direct, no small talk" or "warm but professional, one short paragraph" land more predictably across repeated calls than a single word like "professional" on its own.
key_points is an array, and each item should be one concrete fact, instruction, or detail the draft needs to include — not a paragraph of narrative:
"key_points": ["new deadline request is two weeks", "deliverable scope is unchanged", "happy to discuss on a call"]This is the field to lean on when something absolutely has to appear in the output — a date, a number, a specific commitment — rather than trusting that it'll come through implicitly from a well-written purpose.
Loosely: purpose sets the what, tone sets the how-it-sounds, and key_points sets the must-include facts. Overlap between them is where drafts get inconsistent — a purpose that also tries to specify tone, or key_points that restate the purpose instead of adding new facts, give the draft conflicting signals about what matters most. Keeping each field doing only its own job is the single biggest lever for getting predictable output across many calls. See designing prompts for reliable AI-drafted email for more on brief construction as a discipline, and the anatomy of a drafting call for where these fields sit in the full request lifecycle.
An agent that triages its own inbox, for instance, can pull key_points directly from structured facts it already extracted — a ticket number, a status, a deadline — rather than re-deriving them from scratch for every reply. See building an agent that triages its own inbox for that pattern. The field works just as well fed by code as fed by a human writing a one-off brief.
sender is just an optional name used in the draft's signoff or framing — it doesn't change the authenticated From address, which is tied to the inbox's own address regardless of what's passed here.
Full field constraints — character limits, required versus optional — are listed in the drafting reference.
A weak version of a brief often looks like this — everything crammed into purpose, nothing split out:
{ "purpose": "politely let jane know the shipment is delayed by a week and we are sorry, keep it brief and friendly" }Split across the three fields it does better across repeated calls:
{
"purpose": "notify about a shipment delay",
"tone": "warm, brief, apologetic but not overdone",
"key_points": ["new delivery estimate is one week later", "no action needed from the customer"]
}Both produce a plausible email. The second is far more likely to produce the same plausible email on the next call, which matters once a brief template is being reused across many recipients rather than written once by hand.
If tone says "formal" and purpose is phrased casually, or key_points includes something that contradicts purpose, the draft has to resolve that tension somehow — and which way it resolves isn't something a caller can predict or control field by field. The practical fix isn't a special escape hatch, it's simply keeping the three fields consistent with each other before the call goes out, the same discipline covered in designing prompts for reliable AI-drafted email.
If the goal is to send text that must appear exactly as written — a disclosure, a quote, anything where even a well-tuned brief is the wrong level of control — that's what raw mode is for, covered in drafted vs raw email. These three fields are for cases where the goal, not the exact wording, is what's fixed.