Skip to content

0013. Workspace send budget and plan-limit behaviour

  • Status: Accepted
  • Date: 2026-11-08

A workspace’s plan allowance (ADR 0014) is shared by all its projects, but each project’s sends are decided in its own store. Checking a global counter on every send would serialize all sends of a workspace and add a round trip inside the send path. Analytics Engine is sampled, so it cannot enforce quotas.

Budget:

  • A WorkspaceBudget Durable Object per workspace (a row with FOR UPDATE in containers) holds the period’s allowance.
  • Project stores obtain budget in chunked leases outside their transactions and consume them locally inside claimSend. Chunk sizes are bounded so total overshoot of a workspace is at most 100 emails. When claimSend finds the local lease empty, it returns without claiming; the caller, outside the transaction, requests a new chunk from WorkspaceBudget and claims again. A message moves to waiting:plan_limit only when the workspace budget itself is exhausted.
  • Transactional sends have a separate small grace pool.

Lease lifecycle:

  • A grant from WorkspaceBudget carries a grant ID, the billing period, an amount, and an expiry. A lease request carries an idempotency key from the project store, so a retried request returns the same grant instead of a second one.
  • claimSend reserves one unit from an unexpired lease of the current period. Each reservation settles with billing (ADR 0012), so the allowance and the bill count the same messages:
    • The Send event: consumed. An accepted message whose Send event has not arrived keeps its reservation held; if none arrives within 72 hours of the attempt, the reservation is released (the message is not billed) and an alert is raised.
    • skipped, failed before acceptance (permanent error), failed:outcome_unknown, and a retryable error that returns the message to queued: released. A requeued message reserves again at its next claimSend. Releasing failed:outcome_unknown matches the rule that unresolved unknowns are not billed (ADR 0012).
    • unknown: held until a Send event consumes it or the message becomes failed:outcome_unknown.
    • A message SES drops because the address is on its suppression list: the consumed unit is returned to the lease’s allowance when the reversal is written.
  • A lease expires. No new reservation is made from an expired lease; reservations already made settle against it. When an expired lease has no unsettled reservations, the project store reports its consumed total to WorkspaceBudget, keyed by grant ID so a repeated report is a no-op, and WorkspaceBudget reclaims the remainder.
  • At period reset, every lease of the old period is void: no reservations are made from it, and reservations already made settle against the old period.
  • When a project store moves a message to waiting:plan_limit, it registers itself with WorkspaceBudget as waiting. After an upgrade or a period reset, WorkspaceBudget wakes every registered project; their tick returns waiting messages that are within their 72-hour window to queued.
  • Billing reads the usage ledger (ADR 0012), not the budget. Analytics Engine is never used for quotas.

At the email limit:

  • Workflow and marketing sends wait as waiting:plan_limit. They resume on upgrade or period reset within 72 hours of first entering waiting:plan_limit; at that deadline they become skipped:plan_limit (ADR 0011).
  • Transactional sends count toward the plan. After the grace pool is used, a transactional send request returns a synchronous plan-limit error. (Whether a transactional send API is in the MVP is open; this rule applies whenever one exists.)
  • The workspace owner is notified at 80% and 100% of the allowance.

At the event cap (about 8× the plan’s emails), counted per workspace through event leases from the same WorkspaceBudget:

  • Past the cap, events are accepted up to 1.5× the cap and the owner is notified.
  • Beyond 1.5×, new events are rejected with a plan-limit error until upgrade or period reset.

Self-hosted installations have no budget and no limits (ADR 0003).

Amendment (2026-11-19, ADR 0041): there is no owner role. The notifications above go to the workspace’s admin users.

  • Plan-limit reasons (waiting:plan_limit, skipped:plan_limit) appear in step logs so users can see why a message was delayed or not sent.
  • Details the plan-limit side of ADR 0014, which superseded ADR 0001: there are no overage charges.
  • The exact grace pool size and the lease chunk sizes are set during implementation within the 100-email overshoot bound.