Errors and limits

Errors

Postilon uses HTTP status codes, and every error has this body:

{
  "error": {
    "code": "domain_not_verified",
    "message": "Sender domain acme.com is not verified in this workspace. Verify it under Domains, or send with a test API key."
  }
}

Status	Code	What to do
400	invalid_json	Send a valid JSON body with the documented types. variables values must be strings.
400	validation_error	A required field is missing or invalid; the message says which.
400	invalid_scheduled_at	Use an RFC 3339 time such as 2026-11-01T09:00:00Z.
401	missing_authorization	Send Authorization: Bearer <API key>.
401	unauthorized	The key is wrong, revoked or expired.
402	insufficient_credits	Buy credits in the dashboard, or turn on auto-recharge.
403	domain_not_verified	Verify the sender domain, or send from a verified one.
403	domain_restricted	The key may only send from another domain, or its domain was removed. Use a key for this domain.
403	insufficient_scope	The key is a sending-only key; use a full-access key for this endpoint.
403	workspace_suspended	Sending is paused for the workspace; contact support.
404	not_found	The email, domain, template, webhook or other resource does not exist in this workspace.
409	already_exists	The domain is already in this workspace.
409	cannot_cancel	The email is already being delivered or was sent.
409	idempotency_key_reused	The Idempotency-Key was used for a different request; use a new key for a new email.
429	rate_limit_exceeded	Slow down; see the rate limit headers.
429	daily_limit_reached	The workspace's daily sending limit is reached. Try later, or ask for a higher limit.

Rate limit

A workspace can make 100 API requests per second, shared by all its keys. Every response says where you stand:

Header	Meaning
X-RateLimit-Limit	Requests allowed per second (100).
X-RateLimit-Remaining	Requests left in the current second.
X-RateLimit-Reset	When the window resets, in Unix seconds.

Over the limit, requests fail with 429 rate_limit_exceeded. Wait until the reset time, and use batch sending for many emails at once.

Limits

Limit	Value
Daily sending limit	100 recipients per rolling 24 hours for new workspaces; 10,000 after the first paid top-up. Higher limits on request.
API requests	100 per second per workspace
Emails per batch request	100
Message size	10 MB (enforced on the SMTP relay)
Credits	1 per recipient; credits are valid for 90 days from purchase or grant

Sending health

Sending pauses automatically when, over 24 hours and at least 100 emails, bounces reach 5% or spam complaints reach 0.3%. Keep bounces under 2% and complaints under 0.1%: send only to people who asked for your email, and remove addresses that bounce. Postilon adds hard-bounced, complaining and unsubscribed addresses to your suppression list for you. See the Acceptable Use Policy.