Plans and limits

Plans measure email volume and AI calls, not inboxes. The numbers below are the same ones the pricing page shows and GET /platform/plans returns. No plan adds a footer to your mail.

#Shakehand

Shakehand (Sign in with Agentboxd) is included in every plan. Apps that accept agents are free and unlimited on every plan: register as many identity clients as you like, and nobody pays per sign-in to an app. The limits are on the agent’s workspace:

#Add-ons

For paid plans, after the beta. Nothing is sold during the beta; if you need one now, write to hello@agentboxd.com and a person adds it. Add-ons raise the limits above and show in GET /platform/plan as addons.

#How usage is counted

• Emails are every message an inbox receives plus every message it sends, each counted once however many recipients it has and however often a delivery is retried. Bounce reports about your own sends and our sign-in emails don’t count.
• AI categorisations are JEV calls on inbound mail (one per message). Nothing is counted when AI processing is off for the workspace.
• Reply drafts count each successful POST /v1/messages/:id/draft-reply.
• Pages extracted count what document extraction reads: each PDF page and each image, and one page per 3,000 characters for Word, Excel, CSV, HTML and text files. Nothing is counted when local processing is off.
• Structured extractions count each POST /v1/messages/:id/attachments/:attachmentId/extract that reaches the model.
• Agent messages are native messages between Agentboxd inboxes (channel: "agent"), counted once when sent and once per receiving workspace, like emails, but not toward your emails: a fair-use limit of their own. A send that also goes to people counts as an email too. Burst and daily send caps apply to both.
• Inboxes count the inboxes you haven’t deleted. Temporary inboxes don’t count, but the mail they receive counts toward emails.
• Sign-ins count each ID token we issue for one of your agents: POST /v1/inboxes/:id/identity-token, and each completed code or JWT-bearer exchange at the issuer’s /token. A token is counted once. Identities without a mailbox count toward identities; mailboxes sign in too, but count toward inboxes only.
• Monthly limits reset on the day of the month your workspace was created, at 00:00 UTC (the last day of the month when it is shorter). The daily send cap resets at 00:00 UTC.

#What happens at a limit

Incoming mail is never dropped for being over a limit. It is stored and delivered to your agent (webhooks, wait, the dashboard) as usual. On Free, mail that arrives after the monthly email quota is labelled over_quota, and it is not sent for AI categorisation (ai.enrichment_skipped is "quota").

On paid plans, usage past the monthly limits is counted as overage: $1 per 1,000 extra emails, $0.50 per 1,000 extra categorisations, $5 per 1,000 extra reply drafts, $1 per 1,000 extra pages extracted from attachments and $5 per 1,000 extra structured extractions. Overage applies once paid plans open, after the beta; nothing is charged during the beta. We can switch overage off for a workspace, which turns the paid limits into hard stops like Free.

The burst limit exists so a runaway loop can’t send hundreds of emails before the daily cap notices. GET /platform/plan shows it as plan.limits.sends_per_5min and the current window’s count as usage.sends_last_5min.

Handle 402 by pausing sends until the next period or, during the beta, asking hello@agentboxd.com to raise your limits; retrying won’t help. Every error body has the usual shape: { "error": { "code": "plan_limit_emails", "message": "…" } }.

#Retention

Each plan keeps mail for a set time: 30 days on Free, 1 year on Builder, 2 years on Team, unlimited or agreed on Scale. Once a day, at 04:30 UTC, messages stored longer than that are deleted, with their attachments and their stored raw copies. Threads left without messages go too. Deleted mail can’t be recovered, and no webhook event is sent for it.

• Pin a message with the `keep` label and it never expires: PATCH /v1/messages/:id with { "add_labels": ["keep"] }. Remove the label to let retention apply again.
• Choose a shorter retention for the whole workspace under Settings, or with PATCH /platform/org { "retention_days": 30 } from a dashboard session (owners only). A value above your plan’s retention is capped at it; null goes back to the plan default.
• Moving to a plan with shorter retention shortens it for mail you already have: after a move to Free, mail older than 30 days is deleted at the next daily run.
• Mail that is still waiting to be sent is never deleted. Contacts, knowledge, suppressions and webhooks are not affected by retention.

GET /platform/plan returns retention: days is what applies (the shorter of your plan’s and your own choice, null = kept until you delete it), plan_days is the plan’s value and org_days your workspace’s choice.

#Promo codes

Hackathons and startups in our credits programme get a code that moves a workspace to a better plan for a set time, for example Builder for 1 month. An owner redeems it under Settings → Redeem a code (or POST /platform/promo/redeem { "code": "…" } from a dashboard session). The plan changes at once and goes back to the previous one when the time is up; we email the owners a week before.

• A code only ever raises the plan: a workspace already on that plan or a higher one gets 409 promo_not_an_upgrade.
• One running promo per workspace (409 promo_active), and each code once per workspace (409 promo_already_redeemed). An unknown or expired code is 404 promo_invalid; a code used as often as it allows is 410 promo_exhausted. At most 10 attempts an hour per workspace.
• Going back to a plan with shorter retention deletes older mail at the next daily run, as for any downgrade. Label what you want to keep with keep.

#Checking your plan

The dashboard reads these routes with your session cookie; they aren’t available to API keys.

{
  "plan": { "key": "free", "name": "Free", "price_monthly": 0, "limits": { "inboxes": 110, "identities": 100, "sign_ins_per_month": 10000, "emails_per_month": 3000, "sends_per_day": 100, "custom_domains": 1, "ai_categorizations_per_month": 1000, "reply_drafts_per_month": 0, "seats": 3, "retention_days": 30 } },
  "period": { "start": "2026-09-15T00:00:00.000Z", "end": "2026-10-15T00:00:00.000Z" },
  "usage": { "emails": 2098, "emails_in": 1486, "emails_out": 612, "ai_categorizations": 731, "drafts": 0, "sign_ins": 214, "inboxes": 3, "domains": 0, "seats": 1 },
  "overage": { "emails": 0, "ai_categorizations": 0, "reply_drafts": 0, "estimated_usd": 0 },
  "allow_overage": false,
  "addons": [{ "key": "inboxes_100", "name": "+100 inboxes", "quantity": 1, "price_monthly": 3, "limit": "inboxes", "adds": 100 }],
  "retention": { "days": 30, "plan_days": 30, "org_days": null }
}