Usage controls
Track usage and set caps.
Measure inbox growth, workflow volume, approvals, files, and storage before applying flexible or enforced limits.
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
stats:read
billing:read
billing:write
Outcome
What this gives you.
Teams can keep delegated mail work inside expected operational and billing boundaries.
Use when
The operational shape.
- You need visibility into mailbox storage, Files storage, approvals, workflow runs, and sends.
- A lower-tier inbox needs pro controls without changing its inbox count.
- You want caps that prevent future growth without deleting existing records.
API sequence
The calls to make.
01
Read current usage
GET/v1/billing/usage/
Measure mailbox storage, Files storage, sends, workflows, and approval volume.
02
Review aggregate stats
GET/v1/stats/
Check workflow, approval, broadcast, and file activity over time.
03
Set caps
PUT/v1/billing/caps/mailbox/
Use an admin session for cap mutations and choose flexible billing or enforcement for each storage dimension.
Default example
Use flexible caps when growth should continue but billing and alerting should track overages.
{
"inbox_id": "inb_123",
"limit_gb": 10,
"mode": "allow_and_bill",
"alert_thresholds": [80, 95]
}
Hard enforcement
Use this when the inbox must stop future mailbox or file growth at the configured limit.
{
"inbox_id": "inb_123",
"limit_gb": 10,
"mode": "enforce",
"alert_thresholds": [80, 95]
}
Mailbox-only cap
Use this when message and attachment growth is the concern, but Files API storage should be managed separately.
{
"inbox_id": "inb_123",
"limit_gb": 10,
"mode": "enforce",
"alert_thresholds": [80, 95]
}
04
Audit limit changes
GET/v1/audit/
Use a signed-in user session to keep a record of who changed caps and when.
Controls
Review points.
- Enforced caps block future growth; they do not delete existing data.
- Files API storage and mailbox storage are separate dimensions.