Send limits, reputation & budgets

When many agents send on your behalf, one bad actor — a loop that blasts a stale list, a prompt that emails the wrong people — can drag down delivery for everyone. Dairo gives you two ways to contain it: a budget is the hard cap you set in advance, and reputation is the automatic brake that reacts to bounces and complaints. Use either or both. Both are part of the optional agent layer. They use separate scopes: reading reputation uses agents:read and clearing a tripped agent uses agents:write; reading budgets uses budgets:read and setting or deleting one uses budgets:write.

Reputation

Reputation watches each agent’s bounces and complaints and gives you a simple shouldSend signal to check before you dispatch. If an agent goes off the rails, it’s contained automatically.

Check before you send

The fastest use: read one agent’s state and gate on shouldSend (or verdict === "allow") before a batch.

curl https://api.dairo.app/v1/agents/agt_7h2k9q4m3xeyrt6bv8wn0pcd/reputation \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const rep = await dairo.agents.getReputation("agt_7h2k9q4m3xeyrt6bv8wn0pcd");
if (!rep.shouldSend) console.warn("paused:", rep.state, rep.lastReason);

rep = dairo.agents.reputation("agt_7h2k9q4m3xeyrt6bv8wn0pcd")
if not rep.should_send:
    print("paused:", rep.state, rep.last_reason)

Each agent reports a state, a verdict, its live bounce and complaint rates over the window, and a shouldSend boolean:

`state`	`verdict`	Meaning
`healthy`	`allow`	Sending normally.
`throttled`	`throttle`	Rate-limited after warning-level signals.
`quarantined`	`block`	Tripped — sends are paused.
`review`	`review`	Held for a human decision.

overrideLocked flags an agent you’ve pinned so it won’t auto-trip again.

See your whole fleet

GET /v1/agents/reputation returns every agent’s state, newest-tripped first, with the window and thresholds alongside the data.

curl https://api.dairo.app/v1/agents/reputation \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const report = await dairo.agents.listReputation();
for (const a of report.agents) {
  console.log(a.agentId, a.state, a.verdict, a.shouldSend);
}

report = dairo.agents.list_reputation()
for a in report.agents:
    print(a.agent_id, a.state, a.verdict, a.should_send)

Tool: list_agents  (scope agents:read)
Args: { "action": "listReputation" }

{
  "agents": [
    {
      "agentId": "agt_7h2k9q4m3xeyrt6bv8wn0pcd",
      "state": "healthy",
      "verdict": "allow",
      "shouldSend": true,
      "window": { "sent": 1200, "bounces": 5, "complaints": 0 },
      "rates": { "bounceRate": 0.004, "complaintRate": 0.0001 },
      "lastReason": null,
      "lastTrippedAt": null,
      "overrideLocked": false
    }
  ],
  "window": { "hours": 24 },
  "thresholds": { "complaintWarn": 0.001, "complaintTrip": 0.002, "bounceWarn": 0.03, "bounceTrip": 0.04 }
}

Clear a tripped agent

DELETE /v1/agents/{id}/reputation is an operator override: it lifts a quarantine or resolves a review back to healthy, and returns the reset state. It uses agents:write and is recorded in your audit log.

curl -X DELETE https://api.dairo.app/v1/agents/agt_7h2k9q4m3xeyrt6bv8wn0pcd/reputation \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const cleared = await dairo.agents.clearReputation("agt_7h2k9q4m3xeyrt6bv8wn0pcd");
console.log(cleared.state, cleared.shouldSend);

cleared = dairo.agents.clear_reputation("agt_7h2k9q4m3xeyrt6bv8wn0pcd")
print(cleared.state, cleared.should_send)

Send budgets

A budget is a hard ceiling on sending that Dairo enforces for you. Set one on your whole account, a single API key, or an individual agent, and Dairo stops the next send the moment it would cross the line — so one bad loop can never quietly torch your sender reputation. If a human triggers every send, you may never need it. If code or an AI agent sends on its own, a budget is the seatbelt.

Pick what a budget covers

A budget attaches to one of three things. Set the ceiling where it makes sense — on the whole account, on the key a service uses, or on a specific agent.

Covers	Use it for	What you pass
Account	A single ceiling across everything you send.	`scope: "account"`
Key	One service or integration, isolated from the rest.	`scope: "key"` + the key’s id
Agent	One agent, so a misbehaving bot can’t spend the whole account.	`scope: "agent"` + the agent’s id

Set a budget

One call creates or updates a budget. Pass the scope, the thing it covers, and at least one limit. You get back the budget with its live usage so far.

curl -X PUT https://api.dairo.app/v1/budgets \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "scope": "agent",
        "scopeId": "agt_7h2k9q4m3xeyrt6bv8wn0pcd",
        "limits": { "maxSendsPerDay": 500, "maxNewRecipientsPerHour": 100, "hardStopOnComplaint": true }
      }'

const { budget } = await dairo.budgets.set({
  scope: "agent",
  scopeId: "agt_7h2k9q4m3xeyrt6bv8wn0pcd",
  limits: {
    maxSendsPerDay: 500,
    maxNewRecipientsPerHour: 100,
    hardStopOnComplaint: true,
  },
});

console.log(budget.usage.sendsLast24h, "of", budget.limits.maxSendsPerDay);

budget = dairo.budgets.set(
    scope="agent",
    scope_id="agt_7h2k9q4m3xeyrt6bv8wn0pcd",
    limits={"maxSendsPerDay": 500, "maxNewRecipientsPerHour": 100, "hardStopOnComplaint": True},
)

print(budget.usage.sends_last_24h, "of", budget.limits["maxSendsPerDay"])

Tool: manage_budgets  (scope budgets:write, confirm required)
Args: { "action": "set", "scope": "agent", "scopeId": "agt_…", "limits": { "maxSendsPerDay": 500 }, "confirm": true }
> "Cap this agent at 500 sends a day and stop it cold on any spam complaint."

{
  "budget": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "scope": "agent",
    "scopeId": "agt_7h2k9q4m3xeyrt6bv8wn0pcd",
    "enabled": true,
    "limits": { "maxSendsPerDay": 500, "maxNewRecipientsPerHour": 100, "hardStopOnComplaint": true },
    "usage": { "sendsLast24h": 18, "newRecipientsLastHour": 3, "accountHasComplaint": false },
    "createdAt": "2026-06-12T10:00:00Z",
    "updatedAt": "2026-06-12T10:00:00Z"
  }
}

The limits you can set

Set any combination of these. A budget needs at least one.

Limit	What it caps
`maxSendsPerDay`	Total sends in a rolling 24-hour window.
`maxNewRecipientsPerHour`	First-time recipients per hour — the classic shape of a runaway loop blasting a fresh list.
`hardStopOnComplaint`	When `true`, the moment a recipient reports spam, every further send under this budget stops until you intervene.

maxSpendPerDayCents is reserved — accepted in your config but not currently enforced. Cap on sends and recipients, the limits Dairo acts on.

What happens at the ceiling

When a send would cross a budget, Dairo refuses it with a 429 carrying the budget_exceeded error code — whether the ceiling it hit was a send cap, a new-recipient cap, or the complaint hard-stop. The code lets an agent branch cleanly: back off, queue for later, or alert a human, instead of retrying into a wall.

{
  "error": {
    "code": "budget_exceeded",
    "message": "Daily send budget reached for this agent."
  }
}

An agent that reacts to its own ceiling should catch budget_exceeded and pause the loop rather than retry. See Errors for the full list of codes and how to handle them.

Check usage against a cap

Every budget carries live usage, so you can see how close a scope is to its ceiling before it gets there. List all budgets, or fetch one.

# Every budget
curl https://api.dairo.app/v1/budgets \
  -H "Authorization: Bearer $DAIRO_API_KEY"

# Only the account-wide one
curl https://api.dairo.app/v1/budgets/account \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const { budgets } = await dairo.budgets.list();

const { budget: account } = await dairo.budgets.get("account");
console.log(account.usage.sendsLast24h, account.usage.newRecipientsLastHour);

budgets = dairo.budgets.list()

account = dairo.budgets.get("account")
print(account.usage.sends_last_24h)

Fetch one budget by passing account, or a key or agent id as the scopeId.

Remove a budget

Deleting a budget removes the cap entirely — sending under that scope is no longer ceilinged.

curl -X DELETE https://api.dairo.app/v1/budgets/agt_7h2k9q4m3xeyrt6bv8wn0pcd \
  -H "Authorization: Bearer $DAIRO_API_KEY"

await dairo.budgets.delete("agt_7h2k9q4m3xeyrt6bv8wn0pcd");

dairo.budgets.delete("agt_7h2k9q4m3xeyrt6bv8wn0pcd")

Setting or deleting a budget is a privileged action. A key that can only send mail can’t raise its own ceiling — so a leaked sending key stays boxed in by the limits you set.

Next steps

Land in the inbox

The bounces and complaints that drive send health.

Agent identity & provenance

The agent identities reputation keys on and budgets attach to.

Why Dairo is agent-native

Patterns for safe, autonomous email agents.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

Send limits, reputation & budgets

Reputation

Check before you send

See your whole fleet

Clear a tripped agent

Send budgets

Pick what a budget covers

Set a budget

The limits you can set

What happens at the ceiling

Check usage against a cap

Remove a budget

Next steps

Land in the inbox

Agent identity & provenance

Why Dairo is agent-native

​Reputation

​Check before you send

​See your whole fleet

​Clear a tripped agent

​Send budgets

​Pick what a budget covers

​Set a budget

​The limits you can set

​What happens at the ceiling

​Check usage against a cap

​Remove a budget

​Next steps

Land in the inbox

Agent identity & provenance

Why Dairo is agent-native

Reputation

Check before you send

See your whole fleet

Clear a tripped agent

Send budgets

Pick what a budget covers

Set a budget

The limits you can set

What happens at the ceiling

Check usage against a cap

Remove a budget

Next steps