Agency operations
Create a client project inbox.
Give a client, tenant, project, or workstream its own inbox, token boundary, labels, and operational record.
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
labels:write
email:read
workflows:write
Outcome
What this gives you.
Agency and consultant teams can separate client work without multiplying human inboxes.
Use when
The operational shape.
- Each client or project needs its own address and history.
- You want scoped tokens for agents or automations that should only see one client area.
- You need one place for intake, follow-up, documents, and approvals per client.
API sequence
The calls to make.
01
Create the project inbox
POST/v1/inboxes/
Use session auth to create one inbox per client, project, or service line.
Default example
Use this as the default shape for this step.
{
"address": "acme@mail.example.com"
}
02
Add context labels
POST/v1/labels/
Create labels for status, priority, client, and work type.
Default example
Use this as the default shape for this step.
{
"inbox_id": "inb_acme",
"name": "Acme onboarding",
"color": "#111111"
}
03
Issue scoped tokens
POST/v1/tokens/
Use session auth to give each agent or integration access to only this inbox.
Default example
Use this as the default shape for this step.
{
"inbox_id": "inb_acme",
"label": "acme-workflow-agent",
"scopes": ["email:read", "email:send", "files:write", "workflows:read"]
}
04
Route client mail
POST/v1/workflows/
Send matching mail to the right workflow, file area, or review queue.
Default example
Use a combined route when one client mailbox needs both context labeling and an operational next step.
{
"name": "Route Acme invoices",
"trigger": "email_received",
"conditions": [
{"field": "from_domain", "op": "eq", "value": "vendor.example"}
],
"writes": [
{"source": {"from": "event.payload"}, "target": {"type": "email.add_label", "label_id": "client/acme/onboarding"}},
{"source": {"from": "event.payload"}, "target": {"type": "task"}, "contract": {"required": ["summary"]}}
]
}
Route by recipient alias
Use this when one domain has aliases for different client functions or workstreams.
{
"name": "Route Acme support alias",
"trigger": "email_received",
"conditions": [
{"field": "to_address", "op": "eq", "value": "support-acme@mail.example.com"}
],
"writes": [
{"source": {"from": "event.payload"}, "target": {"type": "email.add_label", "label_id": "client/acme/support"}},
{"source": {"from": "event.payload"}, "target": {"type": "webhook", "url": "https://example.com/webhooks/acme-support", "event_type": "workflow.client_support"}}
]
}
Controls
Review points.
- Use labels and context groups to keep related messages, contacts, files, and tasks together.
- Tenant-level controls can manage many inboxes without weakening per-inbox token boundaries.
Related