Lines

A line is one managed iMessage sending number. In API field names a line is called a device (device_id, device_name); the two words mean the same thing everywhere in these docs.

List lines

GET https://api.bluereacher.com/v1/devices

Returns every line in the key's workspace with online state, today's cold-outreach usage against its effective daily cap (warm-up aware), and queue depth. Use it to pick a device_id for a send, or to check available capacity before a batch.

curl https://api.bluereacher.com/v1/devices \
  -H "Authorization: Bearer brk_your_api_key"

{
  "success": true,
  "devices": [
    {
      "id": "8c9a4f2e-1d3b-4a6c-9e8f-2b7c5d1a9e3f",
      "name": "Line 2",
      "number": "+14155550142",
      "status": "online",
      "sent_today": 212,
      "cold_outreach_today": 38,
      "daily_cap": 50,
      "queue_depth": 6,
      "available_today": 12,
      "last_seen": "2026-08-31T07:58:12Z",
      "warmup": null
    }
  ]
}

Route around any line where available_today is 0 or status is offline; or skip routing entirely by omitting device_id on sends and letting load-balancing pick.

Warm-up

A new line earns capacity over roughly four weeks of active days, not calendar days: a day banks toward the ramp when the line actually does meaningful sending, and idle days pause progress rather than resetting it. The ramp climbs from a handful of new contacts per day to the line's full cap. warmup.active_days against warmup.duration_days tells you where a line is. Blue Reacher manages the schedule; you never have to pace a ramping line yourself, because daily_cap already reflects its current tier and the drip queue respects it.

Health lifecycle

Deliverability enforcement on iMessage happens at Apple's end, per number. Blue Reacher's job is to keep your lines under those thresholds and to absorb the damage when one gets hit anyway.

• Healthy. The steady state. The drip queue paces sends, quiet hours clamp cold deliveries to the recipient's local daytime, and caps hold new-contact volume in the safe range.
• Cooldown. If Apple rate-limits a number (the typical trigger is too many new cold contacts too fast, or a spike in spam reports), our system pauses cold sends on that line automatically and lets it rest, typically 24 to 72 hours, then re-ramps it. Replies to engaged contacts continue. You will see the pause reflected in daily_cap and, if you subscribe, a device.health_changed webhook.
• De-registration and replacement. In the worst case Apple de-registers the number from iMessage entirely. The number still works for SMS, but we do not run lines that way: we are an iMessage-first platform, so we replace the line. Replacement is free (once per line per month), typically live within one business day. Conversation history stays in the platform under the line; the new number is a new sender from the recipient's side, so re-opened threads count as new conversations and the replacement line ramps like a new one. Apple bans the number itself, not the account or the platform, which is exactly why the fix is a number swap.

device.status_changed (online/offline) and device.health_changed (can-it-actually-send states like send_outage, imessage_collapse) are separate webhook events, so a line powered down on purpose never shows up as a health incident.