MailingCore
DocumentationQuota enforcement

Quota enforcement

80% warning, 110% grace period, and 429 blocking.

Monthly email quotas are enforced on every send (POST /emails/send, batch, campaigns). This page explains the enforcement ladder; see Plans for limits per tier.

Enforcement ladder

Usage (% of plan limit)SendingResponse headers
0 – 79%AllowedX-Quota-Limit, X-Quota-Used, X-Quota-Percentage
80 – 100%AllowedAbove + X-Quota-Warning: true
100 – 110%Allowed (grace period)Warning headers remain
> 110%BlockedHTTP 429 Too Many Requests
X-Quota-Limit: 5000
X-Quota-Used: 4200
X-Quota-Percentage: 84
X-Quota-Warning: true

What counts toward quota

  • Successful enqueue of transactional sends and campaign fan-out
  • Each recipient in a batch counts as one email

Failed sends before enqueue may not consume quota; check GET /emails/logs for status.

When you hit 429

{
  "statusCode": 429,
  "message": "Monthly email quota exceeded"
}

Options:

  1. Upgrade — POST /billing/checkout with a higher planSlug
  2. Wait — quota resets at the start of the next billing cycle (after Stripe invoice.paid)
  3. Monitor — GET /billing/subscription and dashboard usage widgets

Integration checklist

  • Read X-Quota-Percentage on every send response
  • Alert your ops team when X-Quota-Warning appears
  • Back off or queue sends when approaching 100%
  • Handle 429 with exponential retry after cycle reset or upgrade

Related