iMessage API rate limits and sending rules

Building on the iMessage API? Build on iMessage with Flow: one agent for iMessage, WhatsApp and Telegram. New to it? Read the iMessage API guide.

Two kinds of limits

When people ask about iMessage API limits, they usually mean one of two things.

• Request limits. How many API calls your key can make. These protect the provider’s servers.
• Sending rules. Who you can message, how many new conversations a line can start and how fast it can send. These protect the line from being flagged for unwanted messages.

Request limits are a nuisance. Sending rules are a design constraint. The iMessage API guide covers why a line needs protecting.

Request limits

On Flow, requests are limited per API key and every answer says where you stand:

RateLimit-Limit: 100
RateLimit-Remaining: 97
RateLimit-Reset: 12

Over the limit, the API answers 429 with type rate_limited, a Retry-After header and error.retry_after in seconds. Wait that long and retry with the same idempotency key. The TypeScript SDK retries 429 and 5xx answers for you, twice by default, and honours Retry-After. Use webhooks or the live stream instead of polling GET /v0/events in a tight loop. This is from Flow’s rate limits docs.

Flow’s sending rules

Every send on Flow passes one send gate, which applies each channel’s rules before anything leaves Flow. On an iMessage line:

• Replies are not paced. Replies to a customer who wrote in the last 24 hours go straight out, and they count toward the plan’s people limits below.
• Plans cap people, not messages. The free trial on the shared line covers 25 people, the $25 shared line 300 people a month and 200 a day, and the $100 dedicated line 1,000 people a day with no monthly cap (a new line starts at 250 a day and ramps to 1,000 over its first 14 days). Limits are per account and channel, by UTC calendar day and month. A person counts once in each day or month, with their first message on that channel, and replies count too; in a group, members who never write do not count. A new person past a limit is held, not delivered, and people already talking to the agent keep working.
• Writing first is paced. It comes with the $40 a month Outbound add-on on a dedicated line, and the new conversations a line starts ramp up over 21 days, from 2 a day to 40 a day.
• A first message has to say who is writing and why, and offer a way to opt out, such as reply STOP.
• Flow looks after line health. If a line sees blocks or failed deliveries, Flow pauses cold sends before the number is at risk, and replies still go.

The same send gate applies other channels’ rules. On WhatsApp, free-form messages are allowed for 24 hours after the contact’s last message and then only an approved template, and a Telegram bot is allowed 20 messages a second, in bursts of 40. A send over a rate is refused with 429 rate_limited, and at most one message per conversation is in flight, in the order you sent them.

Flow on iMessage: features, pricing and limits lists the plans and limits in one place.

Design around Flow’s limits

Flow makes the limits visible in the API and applies channel rules before a message leaves the line. That lets your agent decide whether to reply, wait for the customer, retry later or ask them to opt in. For the full plan breakdown, see Flow on iMessage: features, pricing and limits.

Design an agent that respects limits

• Reply, do not broadcast. Agents that answer people who wrote first never meet the new-contact budget or the abuse rules.
• Check before you send. Each endpoint’s docs page lists the channels it works on and their limits. A kind the channel does not take answers 422 unsupported_content and sends nothing, so send a substitute with a new idempotency key.
• Retry only what clears. rate_limited and sender_throttled carry retry_after. outside_window will not clear until the person writes again.
• Use the event ID as the idempotency key, so a retry never sends twice. See idempotency keys.
• Watch sender.status_changed. It is the early warning before a channel acts against a number.
• Get people to write first. An opt-in link opens Messages with the line and a prefilled text, and Flow lines can have one (the sender’s address.link).

Frequently asked questions

Keep reading

All posts: the Flow blog. The Flow docs have the reference.