API reference

Lines

A "line" is one of your dedicated iMessage-capable phone numbers. Each line runs in an isolated macOS VM. You can have any number of lines; outbound is routed across them according to your routing strategy.

List your lines

GET/v1/lines

curl 'https://api.bluereplies.com/v1/lines' \
  -H "x-api-key: $BLUEREPLIES_KEY"

response (excerpt)

{
  "data": [
    {
      "id": "lin_abc123",
      "phoneNumber": "+18055551234",
      "status": "active",
      "banStatus": "healthy",
      "consecutiveFailures": 0,
      "dailyMessageCount": 47,
      "dailyMessageLimit": 1000,
      "hourlyMessageCount": 12,
      "isFacetimeEnabled": true,
      "isImessageEnabled": true,
      "lastActiveAt": "2026-05-25T17:23:14.221Z"
    }
  ],
  "total": 1
}

Get a line

GET/v1/lines/:id

Full detail incl. recent send stats, current queue depth, last 24h activity.

Status & health

Each line has two status fields:

status

Field	Type	Description
`active`	enum	Sending and receiving normally.
`provisioning`	enum	VM is being provisioned. Sends will queue.
`inactive`	enum	Manually paused by you or by support.
`error`	enum	VM is unhealthy. Check the dashboard for details.

banStatus

Field	Type	Description
`healthy`	enum	Normal — most sends going through.
`suspected`	enum	Several consecutive failures detected. We auto-throttle to ~25% of normal capacity.
`confirmed`	enum	Apple has blocked outbound from this line. We pause sends and emit `line.ban_detected`.
`recovering`	enum	Auto-recovery in progress (re-registering with Apple IDS).

Lines can be banned

Apple's anti-spam heuristics can ban a line. Common triggers: high volume to new recipients, low reply rate, recipient spam reports, sending to opted-out numbers. We monitor for this and fire line.ban_detected / line.ban_recovered webhooks.

Line webhooks

line.status_changed — line transitioned between active / degraded / inactive / error
line.ban_detected — Apple appears to have blocked this line
line.ban_recovered — line is healthy again after auto-recovery

Routing strategies

If you have multiple lines, set how outbound is routed across them:

area-code (default) — match line area code to recipient when possible
round-robin — evenly cycle
least-loaded — pick the line with lowest hourly count
random — random selection
sticky — consistent hash per recipient (same recipient always gets the same line)

Set via the dashboard. Per-customer routing strategy lives in your account settings.

Adding new lines

Lines are provisioned via support (BlueReplies team) or self-serve via the dashboard if your plan allows. Provisioning takes ~10 minutes: we activate an eSIM, sign in to an Apple Account on a fresh macOS VM, link iMessage, and verify outbound to the sandbox before marking the line active.