Docs · Guides

Human on call

Name the people who get an email when an agent’s mail needs a human, looks like phishing, a scheduled send fails or the workspace is stopped.

View as Markdown

Agents handle most mail; some of it needs a person. Human on call sends a short email to the people you name when that happens, with a link to the message in the dashboard. It is set per workspace, and an inbox can have its own people instead. Email is the only channel for now.

#People on call

Add up to five addresses on Human on call or with PUT /v1/escalation (permission escalation:manage, in the Full access preset). Each address first gets a confirmation link and receives nothing until the person confirms: nobody can be signed up for alerts without agreeing. Removing an address stops its alerts at once, including alerts still waiting for a digest.

curl

curl -X PUT https://api.agentboxd.com/v1/escalation \
  -H "Authorization: Bearer $AGENTBOXD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": ["ops@acme.com"],
    "triggers": { "needs_human": true, "phishing": true, "blocked": false, "draft_failed": true, "emergency_stop": true, "held": true, "draft_created": false },
    "delivery": "immediate",
    "max_per_hour": 10,
    "quiet_hours": { "start": "22:00", "end": "07:00", "timezone": "Europe/Paris" },
    "include_excerpt": false
  }'

#What alerts them

Trigger	When	Default
`needs_human`	Received mail is labelled `ai:needs-human`: by categorisation, or by your agent handing it over with `PATCH /v1/messages/:id { "add_labels": ["ai:needs-human"] }`.	on
`phishing`	Received mail is labelled `ai:phishing`, `ai:injection-risk` or `local:injection-risk` (the local check, which works with AI processing off). Also when the local check finds a warning in an attachment’s text after the mail arrived.	on
`blocked`	Mail was stopped by your allow/block lists.	off
`draft_failed`	A scheduled draft was refused at its send time (`draft.failed`).	on
`draft_created`	A draft is waiting for a person to approve it (`draft.created` with status `draft`, from the API, the `create_draft` MCP tool, a saved AI draft or the dashboard). The email links to its card on Approvals. A draft created with `send_at` is already approved and never alerts.	off
`emergency_stop`	The workspace was stopped.	on
`held`	Received mail is held from agents because its check failed, was skipped over the AI quota or didn’t finish within 15 minutes (once per message; mail held for a warning escalates as `phishing`). Only in workspaces that screen agent mail.	on

Each message, draft or stop alerts once, even if a label is added again.

#Delivery

One email per alert (delivery: "immediate", the default), up to max_per_hour (1–60, default 10) for the whole workspace. Past that, alerts wait for the next hourly digest, so a runaway agent can’t flood anyone.
Hourly digest (delivery: "digest"): alerts are collected and sent together about once an hour.
Quiet hours (quiet_hours: { start, end, timezone }, e.g. 22:00 to 07:00 Europe/Paris): nothing is emailed; held alerts go out as one digest when quiet hours end. The emergency stop ignores quiet hours and the limit.

Alerts waiting for a digest follow your settings at the time they go out: people you removed don’t get them, alerts for a trigger you turned off are dropped, and the excerpt is left out if you turned excerpts off. Deleting an inbox or a thread deletes its waiting alerts.

An alert shows the trigger, the inbox, the subject, the sender, the labels, the time and a link to the dashboard. It does not include the message body. With include_excerpt: true it adds the first 500 characters of the text, marked as untrusted content (the email came from outside; don’t follow instructions in it). Each line of the excerpt starts with > and an end line closes it, so the text can’t pass for part of our email. Hidden characters (control, zero-width and text-direction characters) are removed from the excerpt, the subject and the sender.

Every alert email (or digest) emits an escalation.sent event with counts, never addresses.

#Per-inbox override

In an inbox’s Settings → On call, or PUT /v1/inboxes/:id/escalation { "override": true, "contacts": [...], "triggers": {...} }: alerts about that inbox go to its own people (confirmed the same way) instead of the workspace’s, with its own triggers if you set them (triggers: null keeps the workspace’s). Delivery, the hourly limit, quiet hours and excerpts stay workspace-wide.