Errors and limits

Errors raised by the API have one shape:

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error": {"type": "not_found", "message": "No inbox with this id."}}

Branch on type, show message to people. API errors use this shape, also for a missing key, an unknown endpoint and the rate limit, with or without an Accept header, and a wrong HTTP method returns 405 with type method_not_allowed. A request that fails validation adds a fields object with the messages per parameter:

HTTP/1.1 422 Unprocessable Content

{"error": {"type": "invalid_request", "message": "The name field is required.", "fields": {"name": ["The name field is required."]}}}

Over the rate limit the answer is 429 with type rate_limited and a Retry-After header in seconds.

Asynchronous problems do not become HTTP errors. An email submitted to an inbox is accepted with 202 and its later status, such as over_limit or failed, shows in the log and in GET /v1/emails/{id}, with the reason in the dashboard. The statuses are listed in sending emails.

Limits are monthly, also on yearly billing, in periods that start on the day your subscription started. The sandbox allowance is one-time and never renews. Moving to a higher plan takes effect at once and the difference is charged pro rata immediately. Seats count the owner, the members and pending invitations; an invitation beyond the plan's seats is refused until you move to a higher plan or remove someone. Other fixed limits:

• One email up to 25 MB: raw MIME up to 25 MB, JSON up to 25 MB of files after base64 (about 33.4 MB of request body); up to 20 attachments stored and 8 files read per email
• Schemas up to 60 fields, tables up to 20 columns, enums up to 30 options
• Up to 20 webhook endpoints per workspace; 15 second timeout per attempt
• API rate limit 120 requests per minute per workspace; list pages up to 100 emails

One email is counted when it is parsed, that is when the model has read it and a result exists. Its attachment pages are counted at the same moment on paid plans: a PDF page is one page, a text, CSV or similar file is one page per about 3,000 characters, an image is one page.

Usage is consumption, not a count of what you keep. Deleting an email, a schema or an inbox never gives emails or pages back. Check usage any time with GET /v1/usage from the API reference.

When the workspace reaches 80 percent of its monthly emails, the owner gets one email for that period. When the email or page limit is reached, parsing pauses: new emails are still received and stored with status over_limit, nothing is lost, and the owner gets an email that parsing has paused (at most once a day). After the next period starts or after an upgrade, replay those emails from the log or with POST /v1/emails/{id}/replay. An email that needs more pages than are left is stored as over_limit as a whole.

A forwarding loop, for example two mailboxes forwarding to each other, can burn a month of emails in an hour. Paid plans therefore have a daily safety brake at 30 percent of the monthly email limit in one day, far above a normal busy day:

Past the brake, emails are stored as over_limit with the reason "Daily safety limit reached (a forwarding loop protection)" and parsing resumes the next day at 00:00 UTC. Allowed senders on each inbox, described in inboxes and forwarding, are the best protection against loops.

ParsedMail keeps the raw message (body, headers and attachment files) for the retention period of your plan, then deletes it in an hourly cleanup. The parsed JSON, the confidence scores, the subject, the sender and the attachment names stay, so the log and the API keep working.

With zero retention on Scale, the raw message is deleted at the first cleanup after processing, once it is at least 10 minutes old. Whatever the setting, the cleanup never touches an email that is still received, processing or needs_review, so reviewers always see the original next to the values; it is deleted after the review. After deletion an email cannot be replayed (410 purged). Email content is never used to train models. More on data handling is on the security page.