API rate limits and sending quotas

#Requests per second

Each team has a limit of requests per second, summed across all its keys. The value depends on the plan:

Values refreshed from GET /plans when the page opens.

The limit in effect for your team appears in GET /usage (rate_limit). Apps that hold only a sending key can see it too: GET /usage accepts sending_access keys, and the X-RateLimit-* headers come with every response, including sends. Every response carries these headers:

Go over the limit and the response is 429 rate_limit_exceeded. To send many emails, use batch sending: 100 emails count as one request.

The limit belongs to the team, not to the key, and also applies to the MCP server. The SDKs read the headers for you: postal.rateLimit (Node.js) and $postal->rateLimit() (PHP) keep the limit of the last response, even with a sending-only key, and wait for Retry-After before retrying a 429.

#Sending quotas

Sends count when the email is created (including scheduled emails and template tests). Each broadcast recipient, each broadcast test and each automation email also counts. The day and the month are counted in UTC.

Values refreshed from GET /plans when the page opens.

When you reach the quota, sends receive 429 daily_quota_exceeded or 429 monthly_quota_exceeded (over SMTP, 452 4.5.3). A broadcast that hits the quota midway is paused and resumes by itself when the quota renews; an automation send fails, and so does the run. On plans that allow it, you can turn on sending beyond the quota in the dashboard, under Billing: extra emails are charged per thousand, with no blocking. Your plan stays the same; you only pay for the extra packs, on the next invoice. Track your usage in GET /usage.

Account reputation. The daily limit in force is the lower of the plan's and the ceiling of the account reputation: a score from 0 to 100 that starts at 0 for new accounts and goes up with each day of sending without bounces or complaints. At levels 1 to 4 the ceiling is 500, 2,000, 5,000 and 10,000 emails a day; at level 5 only the plan's limit applies. The limit in force is in emails.daily.limit of GET /usage, with plan_limit (the plan's) and limited_by (plan or reputation), and the reputation block has the score, the level and the next level. When the reputation is what limits, the message of the 429 daily_quota_exceeded gives the level and the ceiling.

Sends add-on. When the team's plan has a monthly limit and offers the Sends add-on, the owner or an admin buys, with a one-time payment, a reserve of sends that is only used once the monthly quota runs out: first the plan's quota, then the reserve (one credit per email, the ones expiring soonest first), then sending beyond the quota, if the team turned it on, and only then the refusal. Broadcasts do not use the reserve, emails to test addresses take no credit, and the plan's daily limit still applies. The message of the 429 monthly_quota_exceeded says where to buy when that is possible. See Sends add-on and the API reference.

#Features by plan

Plans and pricing: postal.so/precos or, through the API, GET /plans (public, no key needed).

Values refreshed from GET /plans when the page opens.

Teams can have their limits adjusted individually. The value that applies to you is always the one in GET /usage.

The volume scale is made of bands defined by Postal (for example 3,000, 50,000, 100,000 and 250,000 emails per month): each plan serves some of those bands, with the price of each, and above the last band only the custom plan serves. The list of bands and the ones each plan serves is in GET /plans (volume_bands and bands).

#Plan limits and features

Each plan sets, per team, how many things you can have and which features are included. Going over the limit for an item, or using a feature the plan does not include, answers 403 plan_limit_reached, with a message that says which one. The full list, with the text of each feature and whether the API already enforces it (enforced), comes in GET /plans (feature_catalog), and your team's values in GET /usage. For numbers, null means unlimited and 0 means not included; for on/off features, 1 means included and 0 not.

Quantity

They only block creating one more item. What already exists is never deleted.

Contacts above the limit. The contact limit of the marketing plan can also be exceeded, like the email one: under Billing, the team owner or an admin turns on Keep adding contacts above the plan limit (one switch per product, off by default). When it is on, imports, forms, the API and the CRM integrations stop refusing with 403 plan_limit_reached at the limit, and the extra contacts are charged per pack of 1,000 (rounded up) on the next invoice, without changing plans. What is charged is the most contacts the team had in the billing period (or the contacts that received campaigns in the cycle, if higher: see below), and deleting contacts afterwards does not lower what was already measured. Unsubscribed contacts and suppressed addresses count as contacts, as always. It only works with an active marketing subscription, on a plan that allows overage and has a price for extra contacts; otherwise the limit keeps refusing. The refusal message says how to turn it on when the option is available.

Contacts add-on. When the team's marketing plan offers the Contacts add-on, the owner or an admin adds contacts to the limit without changing plans: the pack's price goes on the subscription's invoice and the limit becomes the plan's plus the packs'. The limit the API checks (403 plan_limit_reached) and the one GET /usage shows already include the packs. They only apply to a paid, active marketing plan. See Contacts add-on and the API reference.

Contacts that receive campaigns in the cycle

The marketing plan's contact limit (with the Contacts add-on) also applies to who receives campaigns: in the team's usage cycle (the month that renews on your plan's day), campaigns and automation emails can go to up to that many different contacts. Each address counts once per cycle. Contacts that already received a campaign in the cycle keep counting until the renewal, even if deleted, and deleting and creating the same address again does not count twice. Deleting contacts that have not received a campaign yet frees room right away. Sending several campaigns to the same contacts does not use more. Transactional emails do not count.

Example, with a limit of 50,000 contacts: sending 5 campaigns to the same 50,000 contacts in the cycle is within the plan. Deleting the 50,000 that already received one and importing another 50,000 in the same cycle goes over the limit: the campaign to the new ones is refused until the renewal.

A campaign that would go over the limit is refused as a whole, without sending anything, with 422 cycle_recipients_limit, a message with the numbers, the renewal date and what to do, and the cycle_recipients block (new, used, limit, remaining and resets_at). Postal checks again when a scheduled campaign is about to go out: if it no longer fits, it is paused with the same reason. An automation email to a contact that has received nothing in the cycle, with the limit full, is skipped. The owner and admins get an email at 80% and at 100%. With contact overage turned on, nothing is refused and the contacts above the limit are billed as extra contacts. Without a contact limit, there is no recipient limit. The counter is in GET /usage (marketing_recipients) and in Settings › Usage, and what a campaign would do, before sending, in GET /broadcasts/audience.

Other monthly limits do not give a 403: emails_per_day and emails_per_month give 429 (see sending quotas); ai_credits, 429 ai_credits_exhausted; email_verifications_per_month, 403 if the plan does not include email validation and 429 verification_credits_exhausted when the credits run out; and automation_runs: above the limit, new automation runs do not start (they are marked skipped).

On/off features

retention_days, priority_support, uptime_sla and dedicated_manager are informative: the API blocks nothing because of them (retention is 30 days for everyone, and support is arranged separately).

When the plan drops

When the plan changes, the amount the team already has can go over the new limit. Nothing is deleted: of domains, inboxes, templates, layouts, API keys, webhooks, automations, segments, topics and forms, the oldest ones up to the limit stay active and the newest ones get paused_by_plan: true. A paused item shows up in lists and can be read and deleted, but not changed or used: the domain does not send, the API key does not authenticate, the webhook receives no events, the template does not send, the form goes offline, the automation does not fire, the segment cannot be used as an audience and the inbox does not run the agent (it keeps receiving email). Any attempt to change it answers 403 paused_by_plan. Items come back on their own when the plan, the volume tier or the count allows it, and GET /usage lists what is paused in paused. Contacts, team members and connections are not paused: the limit only prevents adding more.

The monthly email quota and the number of contacts follow the volume tier you subscribed to (see Plans), and a team can have limits adjusted individually. The value that applies to you is always the one in GET /usage.

#Sizes and quantities