Holds and approval
How the gate decides, what a hold is, who can approve it, and what happens after.
concept~3 minVerified v0.216.0
An agent never decides whether mail goes out. Every send, reply and forward goes to a gate on the server, and nothing written in an email can change its answer.
The outcomes
A send comes back with a status.
- sent: the message went out.
- pending: delivery is in flight. Do not send it again.
- held: a person must approve the message first. The agent is told not to send it again.
- drafted: the agent saved it with
mail_draft. A draft is never sent by the agent and waits the same way a hold does.
A message the gate refuses outright comes back as an error that names the reason, such as a send limit. See Errors. A send that failed or was rejected is an error too, never a 200.
Why a message is held
A hold carries reasons. The usual ones are the mailbox's mode, a first contact with a new address, and a reply to machine mail. Gate modes lists what each mode holds, with the table of reasons.
Three cases are held in every mode:
- the first message to an address the workspace has never corresponded with, unless a person put it or its domain on the allow list
- a reply to machine mail
- a reply to a message whose sender failed DMARC alignment
First contact
An address counts as corresponded with once it wrote in, a person approved a message to it, or a person sent to it. Anything else is a first contact. This is why an agent cannot cold email a list: each new address waits for a person.
Approving
A held message waits in Review in the Mail dashboard. A person can edit it, approve it or reject it. The email that announces a hold has Approve and send and Decline buttons that open a page on Super Agent Mail, where pressing the button decides. Opening the link alone decides nothing, so a mail scanner cannot approve a send.
Anyone in the workspace who is not a viewer may decide. After an approval there are five seconds to press Undo before the message goes. An approval link works once and expires after 72 hours, and it stops working if your role no longer allows it.
What the agent should do
Tell the person the message is waiting and carry on. The reviewUrl in the answer is where they approve it. Retrying with the same idempotency_key does not create a second message: the answer is marked duplicate.