Require human approval before your agent sends email

Nylas developer advocate builds an approval queue for AI email agents using the Drafts API. Instead of letting an LLM send email directly, the agent creates a draft that a human must review and approve before it is sent byte-for-byte unchanged. The system uses Nylas Agent Accounts as the mailbox for the agent, with the draft serving as a stable, persisted object that eliminates race conditions between approval and sending.

Most "AI email agent" demos end with a triumphant send . The model writes a reply, the code POSTs it, and a real message lands in a real stranger's inbox. That's a great demo and a terrible production default. The moment your agent can send mail with nobody watching, you've handed an LLM a corporate email address and the standing authority to use it. One hallucinated price, one confidently wrong refund promise, one apology to the wrong customer, and you're explaining to legal why a bot signed an email as your company. There's a boring, durable fix that predates AI by decades: don't send — draft. Stage the message, put a human in front of it, and only send once someone with a name and a pulse approves. Email systems have had a "Drafts" folder forever for exactly this reason. The Nylas Drafts API turns that folder into something better — an approval queue your agent writes into and your reviewers drain. This post builds that queue. The agent creates a draft, a human reviews the pending drafts, and an approved draft gets sent byte-for-byte unchanged . No re-rendering, no "the agent regenerates it on approval" race where the thing you approved isn't the thing that ships. I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for, and I'll pair every one with the raw curl so you can wire it into a backend in whatever language you like. This is deliberately not about escalating inbound threads to a human that's a different problem, where the trigger is a message arriving . Here the trigger is the agent wanting to send , and the gate sits on the outbound path. You could build approval a dozen ways. You could buffer the agent's output in a queue table and call send later. You could stash a JSON blob in Redis. Both work, and both quietly reinvent something the email stack already gives you. A draft is a real, persisted email object , on the mailbox, with a stable id . That buys you three things a homegrown buffer doesn't: id . You don't reassemble recipients, subject, body, and attachments from a buffer and hope you got it right — the object you approved is the object that sends.That last point is the whole game. The contract you want is "what the human saw is what went out." A draft gives you that for free, because the send action references the stored draft rather than re-supplying the content. Everything below runs against a grant — a grant id that represents one mailbox. If you've used Nylas with a connected Gmail or Microsoft account, an Agent Account https://developer.nylas.com/docs/v3/agent-accounts/ is the same thing: a grant. Same /v3/grants/{grant id}/ endpoints, same auth header, same payloads. There's nothing new to learn on the data plane. The difference is provisioning — an Agent Account is a Nylas-hosted mailbox you create on demand, with no OAuth dance and no human to click "Allow." That matters here because the mailbox is the agent. When the agent drafts from support@yourapp.nylas.email , the draft sits in that account's own Drafts folder, and the eventual send comes from that address. The reviewer is approving mail "from the bot," which is exactly the identity you want under human control. One honest caveat up front, because it shapes the design: Agent Accounts don't support custom metadata. You can't tag a draft with {"approval status": "pending"} and filter on it server-side. So the You need: NYLAS API KEY . .nylas.email trial subdomain. New domains warm up over roughly four weeks, so provision early. nylas init once to store your API key.Examples use the US data region host https://api.us.nylas.com . Swap in api.eu.nylas.com if your app lives in the EU. The mailbox the agent drafts from is an Agent Account. Create one with POST /v3/connect/custom , using the built-in nylas provider and an address on your domain: curl --request POST \ --url 'https://api.us.nylas.com/v3/connect/custom' \ --header "Authorization: Bearer $NYLAS API KEY" \ --header 'Content-Type: application/json' \ --data '{ "provider": "nylas", "name": "Support Bot", "settings": { "email": "support@yourapp.nylas.email" } }' The response includes the grant id you'll use for everything else. The API also auto-creates a default workspace and policy for the account, so there's no extra setup to send mail. The CLI collapses all of that into one command: nylas agent account create support@yourapp.nylas.email --name "Support Bot" No --workspace flag exists on create, and there's no refresh token to manage — that's the OAuth-free part. If you later want to attach a stricter custom policy say, to cap inbound size or block recipients , you do that against the auto-created workspace with nylas workspace update <workspace-id --policy-id <policy-id . Grab the grant id from the output and export it: export NYLAS GRANT ID="<grant-id-from-output " Here's the core inversion. Your agent's "send" tool does not call the send-message endpoint. It calls create draft . The message gets composed, persisted, and parked — but nothing leaves the mailbox. Create a draft with POST /v3/grants/{grant id}/drafts . The body is the same shape you'd send a message with: recipients, subject, body: curl --request POST \ --url "https://api.us.nylas.com/v3/grants/$NYLAS GRANT ID/drafts" \ --header "Authorization: Bearer $NYLAS API KEY" \ --header 'Content-Type: application/json' \ --data '{ "to": { "name": "Dana Reyes", "email": "dana@customer.example" } , "subject": "Re: Refund for order 4821", "body": "Hi Dana, I have flagged order 4821 for a refund. You should see it within 5 business days." }' The response is a draft object with an id . That id is the handle the rest of the workflow hangs on — log it somewhere. This is the only place the agent gets to act autonomously, and all it produced is an unsent draft. The CLI mirrors it, with the grant id as a positional argument: nylas email drafts create "$NYLAS GRANT ID" \ --to dana@customer.example \ --subject "Re: Refund for order 4821" \ --body "Hi Dana, I have flagged order 4821 for a refund. You should see it within 5 business days." Add --json or the global --quiet flag to get a clean machine-readable handle back instead of a table — useful when your orchestration code shells out to the CLI and needs to capture the draft id. A practical note: when the agent creates the draft, write a matching row in your database — draft id, the proposed recipients, which reviewer it's assigned to, and a status of pending . That row is your approval record. The draft on the mailbox is the payload; this row is the verdict-in-waiting. Because Agent Accounts don't carry custom metadata, this DB row is non-negotiable — it's the only place "pending vs. approved" can live. Now the queue. Every unsent draft on the mailbox is, by definition, something the agent wanted to send and a human hasn't released yet. Listing drafts is listing the approval queue. Fetch them with GET /v3/grants/{grant id}/drafts : curl --request GET \ --url "https://api.us.nylas.com/v3/grants/$NYLAS GRANT ID/drafts?limit=20" \ --header "Authorization: Bearer $NYLAS API KEY" \ --header 'Accept: application/json' Each item carries the id , to , subject , and body — enough to render a review screen. From the terminal: nylas email drafts list "$NYLAS GRANT ID" --limit 20 nylas email drafts list defaults to 10 drafts; bump it with --limit . To pull one draft up for a close read before deciding, use show : nylas email drafts show <draft-id "$NYLAS GRANT ID" Or over the API, fetch the single draft with GET /v3/grants/{grant id}/drafts/{draft id} : curl --request GET \ --url "https://api.us.nylas.com/v3/grants/$NYLAS GRANT ID/drafts/<DRAFT ID " \ --header "Authorization: Bearer $NYLAS API KEY" \ --header 'Accept: application/json' Two things worth being clear-eyed about. First, this endpoint returns all unsent drafts on the mailbox, not "drafts pending approval" — the API has no notion of your approval state. The mapping back to "who needs to approve what" comes from your DB rows from Step 1. Join the draft list against your pending rows and you have the reviewer's worklist. Second, if a reviewer rejects a message, delete the draft DELETE /v3/grants/{grant id}/drafts/{draft id} , or nylas email drafts delete and mark your row rejected . A rejected message should leave no draft behind to be sent by accident. Review isn't always thumbs-up or thumbs-down. Sometimes the agent got 90% there and a human wants to fix a number or soften a sentence. Because the draft is a real, mutable object, the reviewer can edit it in place before approving — and the edit becomes part of what eventually sends. Update a draft with PUT /v3/grants/{grant id}/drafts/{draft id} : curl --request PUT \ --url "https://api.us.nylas.com/v3/grants/$NYLAS GRANT ID/drafts/<DRAFT ID " \ --header "Authorization: Bearer $NYLAS API KEY" \ --header 'Content-Type: application/json' \ --data '{ "body": "Hi Dana, your refund for order 4821 is approved and will post within 3 business days." }' The CLI doesn't have a draft-update command — nylas email drafts covers create, list, show, send, and delete, but not edit. So in-place edits go through the API PUT above. From the terminal, the equivalent is to delete the stale draft and recreate it with the corrected content: nylas email drafts delete <draft-id "$NYLAS GRANT ID" nylas email drafts create "$NYLAS GRANT ID" \ --to dana@customer.example \ --subject "Re: Refund for order 4821" \ --body "Hi Dana, your refund for order 4821 is approved and will post within 3 business days." That gives you a new draft id, so update your DB row to point at it. The API PUT is cleaner because it keeps the same id, which is why a real review UI would call it rather than shelling out. This is the under-appreciated payoff of using a draft as the primitive. A buffer-in-Redis design forces "approve or regenerate." A draft lets a human take the agent's draft, correct it, and ship the corrected version — no round-trip back through the model, no risk the model rewrites the part the human liked. The CLI's create command also accepts a --reply-to <message-id flag if the draft is a reply, which keeps it threaded to the original conversation. The reviewer approves. Now — and only now — the message goes out. The send action is a POST against the existing draft's id . There is no separate "send draft" path and no re-supplying the content: POST /v3/grants/{grant id}/drafts/{draft id} sends the stored draft as-is. curl --request POST \ --url "https://api.us.nylas.com/v3/grants/$NYLAS GRANT ID/drafts/<DRAFT ID " \ --header "Authorization: Bearer $NYLAS API KEY" \ --header 'Accept: application/json' That empty-bodied POST is the entire approval action. Whatever the draft holds at that instant — original or human-edited — is what sends. The part I like as an SRE is that this is unforgeable in a useful way: there's no content in the send call to tamper with, so "the thing approved" and "the thing sent" can't drift. The CLI version, with a confirmation prompt you can suppress for automated approval workers: nylas email drafts send <draft-id "$NYLAS GRANT ID" --force After the send succeeds, flip your DB row to sent and stamp who approved it and when. That row plus the now-sent message is your audit trail: agent proposed, human approved, message went out, all attributable. One behavioral gotcha to know: messages sent via the drafts endpoint don't emit open or click tracking — message.opened and message.link clicked won't fire. If tracking matters more than the in-place-edit ergonomics, the alternative is to keep the draft purely as a review artifact and, on approval, send the approved content through POST /v3/grants/{grant id}/messages/send with tracking options set. You lose the "send the exact stored object" guarantee, so pick based on which property you care about more. For most approval flows, the unchanged-object guarantee wins. The approval queue stops bad sends . A few cheap additions stop bad behavior around it: messages/send . If the agent literally can't send, no prompt injection can talk it into sending. The gate isn't a policy you hope holds — it's the absence of the capability. to / cc / bcc against a small set of allowed domains in your own code before you call create-draft, so a hallucinated address never even reaches the queue. The pending rows, delete the drafts, and make the agent re-propose against fresh information rather than sending a week-old promise.None of these are Nylas features you toggle — they're application logic around the grant. The grant stays a dumb, reliable pipe; the policy lives in your code, which is exactly where you can test it. nylas agent and nylas email drafts flag used abovePoint your agent at the create-draft endpoint, drain the queue with a human, and send the approved object unchanged. The agent still does the writing. A person still owns the sending. That's the line worth keeping. When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com :