Core concepts

Rate limits + warmup

Two kinds of limits — the HTTP API rate limit, and Apple's per-line "warmup" caps that we mirror to keep your lines from getting flagged.

HTTP API rate limit

Each API key is rate-limited at 100 requests / minute by default. Public endpoints (no auth) are rate-limited per IP. We respond with these headers on every request so you can budget:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1779590100

When you exceed the limit, we return 429 Too Many Requests with a Retry-After header in seconds. Back off and retry.

Need higher limits?

Growth and Enterprise plans bump the per-key limit to 500/min and 5000/min respectively. The official Node SDK auto-retries 429s with exponential backoff.

Per-line warmup curve

Apple silently shadow-bans iMessage lines that send too aggressively too fast. We mirror the proven LoopMessage warmup curve so your lines stay healthy. NEW outbound conversations (first-ever send to a phone from a line) are what counts. Replies and follow-ups inside an existing conversation are unlimited.

Line age	New conversations / day
Day 1–2	2
Day 3–4	5
Day 5–7	10
Day 8–14	20
Day 15–21	30
Day 22+	50

Once a line is fully warmed (22+ days), the steady-state cap stays at 50 new conversations / day / line. Lines stack: 5 warmed lines = 250 new conversations / day.

Per-contact daily limits

Even on a fully warmed line, we cap how many messages you can send to a single recipient in a 24h window:

200 messages / contact / day — hard ceiling. Protects against bugs (loops).
6 consecutive unanswered messages — soft cutoff. Resets on any inbound reply. Tunable per account.

Unanswered cutoff is the biggest deliverability lever

Spam reports from pestered recipients are the #1 way a line gets banned. The 6-unanswered rule is the single most effective defense we have. Don't disable it unless you really know what you're doing.

Hourly safety cap

On top of the daily caps, we also smooth your sends with an hourly ceiling (default 50/hour/line) to prevent bursty patterns that look bot-like. Tune via lines.hourlyMessageLimit if needed.

Conversation stickiness

Once a conversation begins on a line, every future message in that conversation routes through the same line — even if you have many lines and use auto-routing for new conversations. This is required: switching lines mid-conversation looks like spam to Apple and the recipient.

If the original line is offline when you try to send a follow-up, you get a hard error (not silent line switching). Wait for the line to recover, or contact support to reassign.