Work routing
Route an email request for sign-off.
Send an email-based approval, acknowledgement, or text-response request to several people and record their replies.
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
work_routes:read
work_routes:write
email:read
sequences:write
Outcome
What this gives you.
A quote, invoice, decision, or email request gets routed to the right recipients with status, reminders, and reply evidence attached.
Use when
The operational shape.
- An email request needs approval, acknowledgement, or written input from more than one person.
- Recipients should respond by email instead of logging into another system.
- You need ordered or parallel sign-off with a route record and route events.
API sequence
The calls to make.
01
Read route options
GET/v1/work-routes/reference/
Load supported request types, routing modes, completion rules, and failure modes.
02
Create and start the route
POST/v1/work-routes/
Create a parallel or ordered email route tied to the source message.
Default example
Use parallel approval when every recipient should be active at once and all required responses must arrive.
{
"creator_inbox_id": "inb_123",
"title": "Approve vendor quote",
"description": "Reply APPROVE, REJECT, or CHANGES with notes.",
"request_type": "approval",
"routing_mode": "parallel",
"completion": "required",
"failure_mode": "block",
"due_at": "2026-06-18T12:00:00Z",
"start": true,
"source": {
"type": "email",
"message_id": "msg_123",
"thread_id": "thr_123",
"subject": "Vendor quote"
},
"response_detection": {
"phrases": {
"approve": ["approve", "approved", "ship it"],
"reject": ["reject", "hold"],
"request_changes": ["changes", "revise"]
}
},
"recipients": [
{"kind": "contact", "contact_id": "ctc_finance", "reminder_sequence_id": "seq_remind"},
{"kind": "email", "email": "legal@example.com"}
]
}
Ordered legal then finance route
Use ordered routing when later recipients should wait until earlier sign-offs are complete.
{
"creator_inbox_id": "inb_123",
"title": "Approve contract addendum",
"request_type": "approval",
"routing_mode": "ordered",
"completion": "required",
"failure_mode": "block",
"due_at": "2026-06-18T12:00:00Z",
"start": true,
"source": {
"type": "email",
"message_id": "msg_contract_addendum",
"thread_id": "thr_contract_addendum",
"subject": "Contract addendum"
},
"recipients": [
{"kind": "email", "email": "legal@example.com", "order": 1},
{"kind": "email", "email": "finance@example.com", "order": 2}
]
}
Acknowledgement route
Use acknowledgement when you need recipients to confirm they received or reviewed something, not approve it.
{
"creator_inbox_id": "inb_123",
"title": "Acknowledge updated vendor instructions",
"request_type": "acknowledgement",
"routing_mode": "parallel",
"completion": "required",
"failure_mode": "cancel",
"due_at": "2026-06-18T12:00:00Z",
"start": true,
"recipients": [
{"kind": "email", "email": "ops@example.com"},
{"kind": "email", "email": "ap@example.com"}
]
}
03
Record recipient replies
POST/v1/work-routes/{route_id}/responses/
Store approve, reject, request-changes, acknowledgement, or text responses detected from email replies.
Default example
Use this shape when your parser or operator has confirmed what the recipient's email reply means.
{
"recipient_id": "rr_123",
"action": "approve",
"evidence": {
"source": "email_reply",
"message_id": "msg_reply_123",
"confidence": 0.96,
"matched_text": "approved"
}
}
04
Review route events
GET/v1/work-routes/{route_id}/events/
Inspect who responded, when, and what evidence was attached.
Controls
Review points.
- Use Work Routes for people replying by email; use webhooks when software should receive an event.
- Email-only recipients can be routed, but contact recipients can also receive reminder sequences.
Related