Human review
Hold agent replies for approval.
Let an agent draft or request a send action while a human approves sensitive mail before it leaves.
Token first
Make sure the agent has these scopes.
Create a new token or update the agent's current token before trying the calls below.
Required token scopes
email:read
email:send
approvals:read
approvals:write
Outcome
What this gives you.
The agent can prepare work, but risky or high-impact actions wait for a human decision.
Use when
The operational shape.
- You want an agent to answer mail without giving it blanket send authority.
- Certain actions, recipients, or generated replies need sign-off.
- You need a record of who approved, rejected, or changed the action.
API sequence
The calls to make.
01
Create a restricted token
POST/v1/tokens/
Add send actions to the token's approval-required list.
Default example
Use this when the agent may prepare a reply, but every send must wait for review.
{
"inbox_id": "inb_123",
"label": "reply-agent",
"scopes": ["email:read", "email:send"],
"requires_approval": ["email:send"]
}
02
Draft or request the send
POST/v1/messages/
The agent submits the message with recipient and body context.
Default example
Use this as the default shape for this step.
{
"to": [{"email": "client@example.com"}],
"reply_to_message_id": "msg_123",
"text_body": "Thanks for the context. Here is the proposed next step."
}
03
Review the held action
GET/v1/approvals/
Show the queued send action, generated content, and message history.
04
Approve held action
POST/v1/approvals/{approval_id}/approve/
Release the held action as-is when review is complete.
05
Reject held action
POST/v1/approvals/{approval_id}/reject/
Discard the held action without executing it.
Controls
Review points.
- Approval requirements belong on the token, so different agents can have different authority.
- Rejected actions should feed back to the agent as state, not disappear from the record.