Spending caps and human control
Mailroom lets an AI agent spend money under four constraints at once: it draws from a prepaid balance rather than a card, it cannot exceed per-shipment and per-day caps, it can only buy at a price it was quoted first, and a human can require approval before any label is bought.
Last updated
Prepaid balance, not a card
An agent never holds a payment method. Live shipping draws from a prepaid organization balance, which means the worst case is bounded by what is already in the account rather than by a credit limit. Adding a card and signing the billing authorization is a human-only step — card details never pass through the API, and an agent cannot complete it.
What a self-serve key starts with
A key created through self-serve signup begins deliberately tight. An org admin can issue keys with different limits; these are the defaults an autonomous signup gets.
| Limit | Default | Effect |
|---|---|---|
| Per shipment | $100 | A single label cannot exceed this, whatever the quote says. |
| Per day | $300 | Rolling daily ceiling across every shipment the key buys. |
| Shipments per day | 10 | Caps volume independently of spend. |
| Quotes per day | 100 | Rate-limits the free operation too, so a loop cannot run away. |
| Countries | US | Destinations outside the allowed list are refused. |
A key can read its own live policy at any time — GET /api/v1/usage returns rolling 30-day spend, request counts, and the caps currently in force. An agent never has to guess what it is allowed to do.
What happens at the ceiling
Hitting a cap returns a policy_violation that names the limit hit, the amount attempted, and the endpoint to request more headroom. Errors on this API are { code, message, suggested_action } with a stable code enum, so an agent can branch on the code rather than parse prose.
From there the agent calls request_limit_increase with the cap it needs and a reason. Below the admin-set ceiling it is granted instantly — status auto_granted, and the shipment can be retried immediately. Above it, the request goes to a human operator who may approve, deny, or ask a follow-up question the agent answers with reply_to_limit_request.
Approvals: a human in the loop per shipment
Caps bound the damage; approvals prevent it. Where an organization sets an approval threshold, create_shipment returns pending_approval instead of a label — a manager is notified in Slack, and nothing is bought until they say yes. The agent is expected to tell its human that it is waiting rather than to retry.
Self-serve keys are the exception, and honestly so: there is no Slack workspace to approve in, so caps are the only guardrail. That is why their defaults are tight.
Seeing what it did
Eight HMAC-signed webhook events cover label creation, approvals, delivery, exceptions and limit decisions. Every shipment carries a full audit trail. Quoting is free and has no side effects, so the expensive, irreversible action — buying a label — is always a separate, explicit call made against a price already shown.
The mechanics of those calls are on the MCP tool reference, and you can exercise every path above for free in the sandbox.