Rate limits and sending capacity

BlueReacher has two limits that people mix up. They are not the same thing and they fail in different ways. API rate limits cap how fast your code can call the API. They are a technical limit. You hit them with a 429 and a Retry-After header, you back off, you continue. Sending capacity caps how many new conversations one line starts per day. It is a deliverability limit, not a technical one. It exists to protect how recipients and their devices treat your line. You cannot back off and retry your way past it in the same hour.

	API rate limits	Sending capacity
What it counts	HTTP requests	New conversations started
Scope	Per API key	Per line
Window	Per second and per minute	Per rolling hour and per day
Fix when you hit it	Retry after the header says	Add lines, or wait for the daily reset
Signal	`429 rate_limit_exceeded`	`429 line_capacity_reached`

API rate limits

Limits apply per API key, across all lines on that key.

Endpoint group	Limit
`POST /messages`	60 requests per minute
Other write endpoints (POST, PATCH, DELETE)	120 requests per minute
Read endpoints (GET)	300 requests per minute
Any endpoint, burst ceiling	10 requests per second

Every response carries your current counters.

Header	Example	Meaning
`X-RateLimit-Limit`	`60`	Requests allowed in the current window
`X-RateLimit-Remaining`	`41`	Requests left in the current window
`X-RateLimit-Reset`	`1785945660`	Unix timestamp when the window resets
`Retry-After`	`12`	Seconds to wait. Sent on `429` responses only

Read X-RateLimit-Remaining on every response and slow down before you hit zero. That is cheaper than handling 429s.

Sending a message

POST https://api.bluereacher.com/functions/v1/messages Authenticate with Authorization: Bearer bluereacher_your_api_key.

Field	Type	Required	Description
`from`	string	yes	The line sending the message, in E.164 format
`to`	string	yes	Recipient number in E.164 format
`content`	string	yes	Message body
`channel`	string	no	`imessage`, `rcs`, or `sms`. Defaults to `imessage`
`external_id`	string	no	Your own id. Reused values are treated as the same message, so retries never send twice
`media_url`	string	no	Public URL of an image or file to attach

curl -i -X POST https://api.bluereacher.com/functions/v1/messages \
  -H "Authorization: Bearer bluereacher_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155550142",
    "to": "+16465550119",
    "content": "Hey Dana, saw you took over ops at Northline. Worth a quick chat?",
    "channel": "imessage",
    "external_id": "seq-4471-step-1"
  }'

A 429 looks like this.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests on this API key. Retry after 12 seconds.",
    "retry_after": 12
  }
}

Always set external_id before you add retries. Without it, a retry after a timeout can deliver the same message twice.

import time
import requests

BASE = "https://api.bluereacher.com/functions/v1/"
HEADERS = {
    "Authorization": "Bearer bluereacher_your_api_key",
    "Content-Type": "application/json",
}

def send(payload, max_attempts=5):
    for attempt in range(max_attempts):
        r = requests.post(BASE + "messages", json=payload, headers=HEADERS)
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        code = r.json().get("error", {}).get("code")
        if code == "line_capacity_reached":
            raise RuntimeError("line is out of capacity today, route to another line")
        time.sleep(int(r.headers.get("Retry-After", 2 ** attempt)))
    raise RuntimeError("still rate limited after retries")

Retrying a line_capacity_reached error is pointless. That Retry-After can be hours. Route the message to another line or queue it for tomorrow.

Sending capacity

Every BlueReacher line is a dedicated iMessage line, managed for you. Each one has a daily allowance of new conversations.

Line age	New conversations per day
Days 1 to 7	25
Days 8 to 14	50
Days 15 to 21	75
Day 22 and after	100

A second cap applies on top: 20 new conversations per line per rolling 60 minutes. This stops a burst from looking like a blast. A conversation counts as new when you message someone the line has not exchanged messages with in the last 30 days. Replies inside an active thread do not count. A line at its daily cap can still answer everyone who wrote back.

Why capacity exists

Sender reputation. There is no A2P registration required on a BlueReacher line, so nothing here comes from a carrier registry or a campaign approval queue. The limit comes from recipient behavior. Recipients report messages as junk. They block numbers. Those signals get counted against the line that sent the message, and a line carrying too many of them starts landing badly for everyone you message from it, including people who wanted to hear from you. Damage compounds and it is slow to undo. Pacing keeps the signals low. BlueReacher spreads a line’s daily allowance across its sending window with randomized gaps rather than firing everything at once. Lines are also monitored for health. If a line’s block and report rate climbs past 2 percent of recipients, its daily capacity drops automatically until the rate recovers. If 120 consecutive outbound messages from a line go unanswered, new-conversation sending on that line pauses so you can fix the list or the copy.

Checking a line

GET https://api.bluereacher.com/functions/v1/lines/{line_id} Authenticate with Authorization: Bearer bluereacher_your_api_key.

Field	Type	Required	Description
`line_id`	string	yes	Path parameter. The line to inspect

curl https://api.bluereacher.com/functions/v1/lines/lin_8f2a3c91 \
  -H "Authorization: Bearer bluereacher_your_api_key" \
  -H "Content-Type: application/json"

{
  "line_id": "lin_8f2a3c91",
  "from": "+14155550142",
  "channel": "imessage",
  "status": "active",
  "warmup_stage": "week_3",
  "daily_capacity": 75,
  "sent_today": 62,
  "remaining_today": 13,
  "capacity_resets_at": "2026-07-25T00:00:00Z",
  "created_at": "2026-07-03T16:11:04Z"
}

Field	Type	Description
`line_id`	string	Unique id for the line
`from`	string	The line’s number in E.164 format
`channel`	string	`imessage`, `rcs`, or `sms`
`status`	string	`active`, `warming`, `throttled`, or `paused`
`warmup_stage`	string	`week_1` through `week_3`, or `full` once warmup finishes
`daily_capacity`	integer	New conversations allowed today
`sent_today`	integer	New conversations started today
`remaining_today`	integer	`daily_capacity` minus `sent_today`
`capacity_resets_at`	string	ISO 8601 timestamp of the next daily reset, in UTC
`created_at`	string	ISO 8601 timestamp of when the line was provisioned

Poll this before each batch and route around any line where remaining_today is zero or status is throttled.

Scale by adding lines, not by pushing one line

Capacity is per line, so volume is a multiplication problem. One line at 100 per day is the ceiling. Ten lines at 100 per day each is 1,000 per day, with every line still inside a safe range.

Lines	New conversations per day	Per month (22 sending days)
1	100	2,200
5	500	11,000
20	2,000	44,000

Rules that keep this working:

Sort your list by line, not by line by list. One prospect gets messaged from one line and stays with that line for the whole sequence. Switching mid-thread confuses the recipient and splits your reply history.
Fill lines evenly. Running three lines at capacity and seven at 10 percent gives you the risk profile of three hot lines.
Add lines before you need them, not the week you need them. A new line takes three weeks to reach full capacity, so order for the volume you want a month out.
Watch reply rate per line. A line that sends 100 and gets 2 replies has a copy problem that more lines will only spread around.

Error reference

Status	Code	Meaning	What to do
429	`rate_limit_exceeded`	API request limit for the key	Wait `Retry-After` seconds, then retry
429	`line_capacity_reached`	Line used its daily allowance	Send from another line, or wait for `capacity_resets_at`
429	`hourly_capacity_reached`	Line hit 20 new conversations this hour	Retry after `Retry-After`, or use another line
409	`line_paused`	Line paused on health grounds	Check the line, fix list quality, contact support to resume
400	`invalid_line`	`from` is not a line on your account	Confirm `line_id` with `GET /lines`

Getting started

Integrations

Platform

Rate limits and sending capacity

API rate limits

Sending a message

Sending capacity

Why capacity exists

Checking a line

Scale by adding lines, not by pushing one line

Error reference

​API rate limits

​Sending a message

​Sending capacity

​Why capacity exists

​Checking a line

​Scale by adding lines, not by pushing one line

​Error reference

API rate limits

Sending a message

Sending capacity

Why capacity exists

Checking a line

Scale by adding lines, not by pushing one line

Error reference