Skip to content
nofeb

Require human approval before an agent sends

Create or update the inbox with autonomy send_with_approval. Every send from that inbox returns status awaiting_approval, joins the approval queue at GET /v1/sends?status=held and emits approval.requested. A person approves or rejects with POST /v1/sends/{send_id}/decision using a key that holds send:approve, a scope agent keys never get, or from Slack, a signed email link or the webmail. Approved mail goes out exactly as held.

Checked against the engine on .

What do you need?

  • An org-level key to create inboxes and an approver key with send:approve
  • A webhook endpoint, the event feed, or a Slack workspace, to notice held sends

Steps

  1. 1. Put the inbox on send_with_approval

    The tier lives on the inbox and is enforced on the server for every surface, including mail clients that submit over SMTP.

    Create the inbox
    const inbox = await nf.inboxes.create({ local_part: "quotes", autonomy: "send_with_approval" });
  2. 2. Give the agent a key without approval rights

    Bind the agent's key to the inbox with message:send but not send:approve. Keys from agent self-signup never hold send:approve.

    Agent key
    await nf.keys.create({ inbox_id: inbox.id, scopes: ["inbox:read", "message:read", "message:send"] });
  3. 3. Notice held sends

    Subscribe to approval.requested for the inbox, or pull the event feed. The event carries the inbox, the thread and the reasons the send was held.

    Webhook
    await nf.webhooks.create({ url: "https://example.com/approvals", scope: "inbox", inbox_id: inbox.id, events: ["approval.requested", "approval.decided"] });
  4. 4. Read the approval queue

    The queue lists every held send the key can see, newest first: subject, a preview, who submitted it, why it was held, and each recipient with new_to_conversation, true when nobody earlier in the thread wrote from, to or copied that address. That flag is what a reviewer most needs: a reply to the customer who asked is routine; a new address added by the agent is not.

    The queue
    curl "https://api.nofeb.com/v1/sends?status=held&inbox_id=inb_…" -H "Authorization: Bearer $APPROVER_KEY"
  5. 5. Decide

    Your approval tool, a person's CLI or an internal admin page shows the held message and calls the decision endpoint with the approver key. To approve from Slack or an email link instead, register an external approver.

    Approve or reject
    await approver.sends.decide(sendId, { approve: true });  // or { approve: false }
Autonomy tiers and the approval flow A ladder of the 6 autonomy tiers from autonomous at the top to read_only at the bottom, each with the status of what it depends on. Beside it, a send from any surface is checked against the inbox's tier, its recipient lists and its caps; a held send is stored as awaiting_approval, emits approval.requested, and is approved or rejected by a person holding the send:approve scope, which emits approval.decided. The ladder, per inbox autonomous Sends are queued immediately, subject to sponsor gating. Shipped send_when_confident Each send is checked by outbound safety questions and goes o… Shipped send_with_approval Every send is held until a human approves or rejects it. Shipped send_to_allowlist Sends to allowlisted recipients go out; any other recipient … Shipped draft_only Sending is refused; the agent writes drafts that a person se… Shipped read_only Sending is refused. Shipped A send from any surface send · reply · forward REST, MCP, JMAP or SMTP Server checks the tier lists, caps, sponsor gating Queued and sent message.sent Held: awaiting_approval approval.requested A person decides queue, Slack or email link agents cannot approve approval.decided approved: sent as held rejected: never sent Refused read_only, draft_only, blocked
Each inbox sits on one rung. Every surface that sends (REST, SDK, MCP, JMAP, SMTP submission) goes through the same check of tier, lists and caps, and a held send waits for a person whose key has the send:approve scope, in the approval queue, Slack or a signed email link.

Why not just remove the send tool from the prompt?

If the agent's key can send, any interface can send with it, and a prompt injection can ask it to. The tier is enforced where mail is submitted, so switching from MCP to the API, or being talked into it, changes nothing.

Which tier fits, if not every send needs a person?

draft_only refuses sends outright. The agent writes drafts instead, and a person edits and sends them; sending a draft with an approver's credential is the approval.

send_to_allowlist sends at once to addresses or domains on the inbox's recipient allowlist and holds (or, if you prefer, refuses) everything else. Recipient blocklists apply on every tier.

send_when_confident asks outbound safety questions of each draft (commitments, prices, legal or personal data, new recipients, echoed injection, staying on topic) and sends only when every answer clears the inbox's threshold, holding the rest with the failing questions as the reasons.

A person can also take one thread over: until they hand it back, the agent's sends on that thread are held or refused, whatever the tier.

Frequently asked questions

Can the agent approve its own send?

No. Approving needs the send:approve scope, which is separate from message:send and never granted to keys created by agent self-signup. Submitting over SMTP with a credential that holds send:approve does not count as approving either.

What happens to a scheduled send that needs approval?

It waits for the decision, then goes out at its send_at time if that is still in the future.

Which tiers exist?

read_only, draft_only, send_to_allowlist, send_with_approval, send_when_confident and autonomous. The governance page shows what each does.

Can people approve without writing an approval tool?

Yes. Held sends can be posted to Slack with Approve and Reject buttons or emailed as a signed, single-use link, and the webmail shows the queue beside the thread.

Status of everything on this page

Every capability named above, with its status as reconciled against the engine.

CapabilityWhat it doesStatus
Autonomy tiers enforced by the server Every inbox carries a sending policy, from read-only to autonomous, enforced on the server for every surface that sends, so switching from the API to MCP cannot bypass it. Shipped
Human approval of held sends A held send waits with status awaiting_approval until a human approves or rejects it; both steps emit events. The approval queue lists every held send with its recipients (each marked if new to the conversation), the reasons it was held and who submitted it. Approving needs the separate send:approve scope, which keys from agent self-signup never hold, so an agent cannot approve its own send. Shipped
Scoped API keys Keys bound to the organization, one pod or one inbox, holding only the scopes they are given. A key cannot mint a key wider than itself. Shipped
Signed webhooks with required scope Standard Webhooks signatures, retries and a delivery log. Scope (organization, pod or inbox) is required, so a subscription never silently widens to everything. Shipped
Durable event feed A pull feed of every event, oldest first after a cursor, for consumers that cannot receive webhooks. Shipped
Drafts Agents write drafts that a person edits and sends, over the API, MCP, JMAP, IMAP and the webmail. It is the documented path for draft-only inboxes: sending a draft needs the approval permission agents do not hold. Shipped
Recipient and sender allowlists and blocklists Lists of addresses, domains or wildcards per organization, pod or inbox: who an agent may write to, and whose mail it reads. A blocked recipient is refused on every autonomy tier, a blocked sender's mail is rejected or quarantined, and you choose whether a send outside the allowlist is held for approval or refused. A check call predicts what a send or an inbound message would meet before it happens. Shipped
Decisions on every message A default set of typed decisions on every inbound email (intent, urgency, needs-reply, automated, verification email, phishing, injection risk, requires-human and language) with a probability each, your own decision schemas beside them, human relabels that correct and retrain it, per-question accuracy and calibration stats, and confidence-gated sending for the send_when_confident tier. Decisions run without leaving nofeb by default; a third-party model sees mail only if you opt in. Shipped
Take a thread over from the agent A person takes a thread over; until they hand it back, the agent's sends on that thread are held for approval or refused, and an event records who is driving. Works over the API, MCP, JMAP and the webmail. Shipped
Webmail for the humans in the loop A full webmail and calendar on the same mailboxes the agents use, with an agent-activity timeline, the approval queue, a per-thread driver lock and a metadata panel, signed in through the same accounts as the console. It opens with hosted access. Shipped
Approvals in Slack and by email link Approve or reject a held send from a Slack message with Approve and Reject buttons, or from a signed, single-use, expiring link in an email. Slack requests are verified with your app's signing secret and can be limited to named people; the email link decides only on an explicit click, so link scanners cannot approve. Shipped