Limits

Plan limits and how they are enforced, and inbox, address, TTL, message, attachment, batch, sandbox and retention limits.

Source: https://machinemail.dev/docs/reference/limits

These are the limits the API enforces.

Plans

Every plan has unlimited inboxes. Plans differ in how much mail and storage they include; see pricing for prices and overage rates.

An outbound message counts once per recipient. Spam and quarantined mail never count. On Free, inbound mail past the allowance is held until it resets or you upgrade, and sending pauses until then. Upgrade in the dashboard under Billing.

How plan limits are enforced

What counts

• Periods. Allowances are per calendar month in UTC and reset at 00:00 UTC on the first day of the next month. The Free daily limit resets at 00:00 UTC every day.
• Inbound. Each inbound message counts once, including mail injected with POST /inbound/raw (even when it is marked spam or quarantined: its content is yours) and mail your own receive lists block. Spam and quarantined mail never count; a message you move out of spam or quarantine (by removing the SPAM or QUARANTINE label) counts from then on. Mail an agent's sandbox inbox received before you claimed it counts toward the month it is claimed in.
• Outbound. Each sent message counts once per distinct recipient across to, cc and bcc: a send to 5 addresses counts 5. Sends, replies, reply-all, forwards and drafts (scheduled or not) all count. A send refused before it goes out (suppressed or blocked recipient, a limit) does not count; a send that bounces after it was accepted does.
• Storage. The size of your stored messages, your drafts (body and attachments) and held mail. Spam and quarantined mail do not count, up to 1,000 MB of it per organization. Past that, on Free new spam and quarantined mail is not stored (message.rejected with reason plan_limit); on paid plans it counts toward your storage usage but is never billed. 1 GB is 1,000,000,000 bytes.
• Deleting mail frees storage but does not give back messages already counted this month.

Check your usage with GET /v0/organizations/usage, machinemail org usage, or the Usage page of the dashboard.

Free plan

When both the monthly and the daily limit apply, the error reports the monthly one. A send to more recipients than the limit itself can never fit: its error has no resets_at.

Held mail

Held mail is stored but not delivered to your agents:

• It is not listed, searchable or exported, and getting it by ID returns 404.
• No message.received event, webhook, realtime event or MCP notification fires, and wait_for_message does not see it.
• Once any mail is held for an inbox, new mail to that inbox waits behind it, so an inbox's mail is always delivered in the order it arrived. This holds on every plan, also right after an upgrade.
• The dashboard shows a banner with the held count, and GET /v0/organizations/usage reports it in held. POST /inbound/raw lists held copies in held instead of messages.

Held mail is delivered, oldest first, within about a minute of any of these:

• the daily limit resets (mail held for the daily limit) or the monthly one does;
• you free up storage (mail held for storage);
• your organization moves to a paid plan.

On delivery, message.received fires as usual. The message's created_at is the delivery time and held_at is when it arrived. It joins its thread as of delivery, so replies that arrived meanwhile thread correctly.

Delivered mail counts toward the month and the day it is delivered in, so a backlog is delivered at most 100 messages a day (the daily limit), oldest first, while new mail queues behind it. Mail held for storage is delivered one message at a time as it fits next to the mail you keep.

Paid plans

Pro, Team and Scale are never blocked. Usage past an allowance is counted and billed as overage at the rates on the pricing page: inbound per 1,000 messages, outbound per 1,000 recipients, storage per GB-month, and custom domains past the plan's number per domain-month. Spam and quarantined mail are never billed.

• When. Overage is billed monthly in arrears, at the end of each billing period, for the usage in that period. A paid plan's billing period runs monthly from the day you subscribed, so it can differ from the calendar month that GET /v0/organizations/usage reports.
• Storage is billed on your average storage over the period (GB-month), from a daily reading.
• Custom domains are billed on the most domains you had at once during the period, from a daily reading.
• Plan changes. An upgrade takes effect right away, with the new allowances, and the price difference for the rest of the period is charged pro rata. A downgrade takes effect at the end of the period. Moving to Free keeps your data: existing domains and members stay, and Free limits apply to new usage.

Already over a limit

Each account can own one Free organization. Creating another returns 402 plan_limit_exceeded (limit_key: "free_organizations"); organizations on a paid plan do not count, and joining other people's organizations is not limited.

Limits apply to new additions only. An organization with more custom domains or members than its plan allows (after a move to Free, for example) keeps them; it cannot add more until it is under the limit. An invitation is checked when it is sent, so an invitation sent earlier can still be accepted.

The agent sandbox has its own limits: plan limits do not apply to unclaimed sandbox inboxes. Once claimed, the inbox belongs to an organization and that organization's plan applies; the mail it received so far counts toward that month, and on Free a claim that does not fit in the month's allowance returns 402 plan_limit_exceeded and nothing moves.

Inboxes and addresses

Addresses on the shared domain are first come, first served across all organizations. Mail to an unknown address on the shared domain is never turned into a new inbox.

Ephemeral inboxes

Catch-all domains

A custom domain with catch_all: true creates an inbox the first time mail arrives for an unknown address, when all of these hold:

• the domain is VERIFIED and inbound_enabled is true;
• the local part is a valid username.

The new inbox has created_by: "catch_all". If the domain sets catch_all_ttl_seconds (any positive number), the inbox is ephemeral with that TTL; otherwise it is permanent. inbox.created is emitted.

Messages and attachments

Batches, lists and search

Webhooks and events

Domains

Pods

• The default pod cannot be deleted.
• A pod with inboxes cannot be deleted (409 Pod still has inboxes; delete them first).

Agent sandbox

An agent that registers itself anonymously through auth.md gets, until a person claims it:

Every send counts when it is made: deleting sent messages or threads does not give any back. Sends to disposable email addresses (throwaway inboxes) can be refused with 403 and error.code disposable_email_not_allowed (param is the field holding the address: to, cc or bcc). Claiming the agent lifts the sandbox caps and this rule. See Rate limits.

Credentials

Retention

Messages, raw MIME, attachments, events and webhook deliveries are kept until you delete them (or the inbox expires). There is no automatic retention window today.