Human on call: alerts when agents need you

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.

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 },
    "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` or `ai:injection-risk`.	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
`emergency_stop`	The workspace was stopped.	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.

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).

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

#Per-inbox override

On an inbox’s On call tab, 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.