primitive docs
primitive app

Limits & Quotas

Primitive enforces a small set of per-organization limits. Your account's effective limits are returned by the API, so you never have to hard-code them — read them at runtime and adapt.

For plan options and pricing, see the pricing page. This page documents the limits themselves and how to observe them.

Read your effective limits

GET /v1/account returns a limits object alongside your plan and granted entitlements:

curl https://api.primitive.dev/v1/account \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY"
{
  "success": true,
  "data": {
    "plan": "developer",
    "entitlements": ["..."],
    "limits": {
      "storage_mb": 5120,
      "send_per_hour": 1000,
      "send_per_day": 10000,
      "api_per_minute": 120,
      "webhooks_max_global": 1,
      "webhooks_per_domain": false,
      "filters_per_domain": false,
      "spam_thresholds_per_domain": false
    }
  }
}
FieldMeaning
storage_mbYour plan's stored-email storage allowance, in MB. Actual usage is reported by GET /v1/account/storage (below); if its quota_mb differs from this value for your account, contact support.
send_per_hour / send_per_dayOutbound send caps over a rolling hour and day.
api_per_minutev1 REST API request cap per minute.
webhooks_max_globalMaximum endpoints across the org. null means unlimited.
webhooks_per_domainWhether endpoints can be scoped per domain.
filters_per_domainWhether allow/block filters can be scoped per domain.
spam_thresholds_per_domainWhether spam thresholds can be set per domain.

webhooks_max_global is null when unlimited. Treat any limit as plan-dependent and read it from this endpoint rather than assuming a fixed value.

Storage quota

GET /v1/account/storage reports how much of your stored-email quota is in use. Its quota_mb is the figure that the returned percentage is computed against:

curl https://api.primitive.dev/v1/account/storage \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY"
{
  "success": true,
  "data": {
    "quota_mb": 5120,
    "used_mb": 142,
    "used_kb": 145408,
    "used_bytes": 148897792,
    "percentage": 2.8,
    "emails_count": 5120
  }
}

Stored raw email and attachments count toward the quota. To free space, discard content you no longer need.

Content retention

Primitive does not delete your inbound email content on a schedule — stored raw email and attachments are retained until you remove them. When you want to delete content, you do it yourself with content discard, which is irreversible. See the Privacy Policy for the full data-handling and deletion terms.

Rate limits

When you exceed a rate limit, the API responds with 429 (error code rate_limited, or rate_limit_exceeded on some per-resource limiters), plus Retry-After and ratelimit-* headers. Branch on the 429 status, not the code. See Errors → Rate-limit responses for the exact headers and the recommended back-off.

Outbound sends are additionally bounded by send_per_hour / send_per_day. These protect shared outbound IP reputation; if you have a legitimate higher-volume use case, contact support.

Entitlement-gated features

Some capabilities are turned on per organization and appear in the entitlements array from GET /v1/account. If a feature is not enabled, the relevant endpoint returns 403 feature_disabled with a docs_url in error.details. Examples include x402 payments (invite-only) and per-domain filters and routes on paid plans.

Related Pages