Holds

A text that can't go right now isn't refused. BlueBot accepts it, answers 201, and puts a hold on it that says why it's waiting and, when it knows, until when. When the hold clears, the text goes by itself. Your code never needs to retry a send because of quiet hours, a sleeping Mac or a daily limit.

What a hold looks like

Every outgoing message has a hold field. It's null when nothing holds the text, and an object when something does:

{
  "id": "msg_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "message",
  "state": "queued",
  "to": "+15555550123",
  "hold": {
    "reason": "quiet_hours",
    "until": "2026-11-14T14:00:00.000Z",
    "description": "Waiting for quiet hours to end at 8:00 AM tomorrow."
  },
  "expires_at": "2026-11-15T04:40:00.000Z"
}

A hold is only ever on a queued text. A scheduled text has none until it's due.

Every reason

The order they're checked

BlueBot checks the reasons in a fixed order and shows the first that applies, so a text has one hold at a time. The first six apply to the whole account, so every queued text shares them:

1. account_held
2. platform_stopped
3. plan_lapsed
4. paused
5. device_offline
6. quiet_hours

The last three apply text by text, in the order the texts were queued:

7. daily_new_people_limit, only for a text to someone you've never texted with through BlueBot
8. platform_daily_limit
9. pacing

When one hold clears, the next may show. A text queued at 11:00 PM waits on quiet_hours; at 8:00 AM, if twenty texts went in ahead of it, it waits on pacing for a few minutes more, then goes. A text held by a daily limit doesn't use up a place in the pace, so texts behind it that can go still go.

Holds are worked out again every time anything changes: a send, a cancel, a settings change, the Mac checking in or going away. Raise new_people_per_day and the texts waiting on it are ready on the Mac's next check-in.

What a hold doesn't change

• Expiry still runs. A held text that's still waiting at its expires_at (24 hours after it was due, by default) becomes expired and never goes. Choose expires_at for texts that only make sense soon, and longer for ones that can wait. Limits
• You can still cancel it. A held text is queued, and POST/v1/messages/{id}/cancel cancels it.
• The stop list isn't a hold. A text to someone on your stop list doesn't wait; it's canceled at once with cancel_reason: "opted_out". Stop words

New sends while the account is held

Most holds let new sends in: they're accepted and wait with everything else. Two refuse new work instead, because nothing will move until a person acts:

• A lapsed plan answers new sends, uploads and webhook creation with plan_lapsed (402). Texts already queued wait with hold.reason: "plan_lapsed" and go once the plan is active again, if they haven't expired. Reading, canceling and changing settings keep working.
• BlueBot pausing your account shows as account_held on every queued text. Write to support@usebluebot.com; a person at BlueBot releases it.

Don't retry a held text

The answer to a held send is a success. Sending the same text again makes a second text with its own hold, and both go when the hold clears. If your code sends in a loop, send each text once with an Idempotency-Key, and let the holds do the waiting. Idempotency

Find what's held

• GET/v1/device counts them: held_count is how many queued texts are waiting on a hold, and queued_count is every queued text.
• GET /v1/messages?state=queued lists them, each with its hold.
• message.queued fires once when a text is queued and carries the hold it had at that moment. A hold changing doesn't fire an event. Listen for message.sent, message.expired and message.canceled to learn how each one ends.

curl "https://usebluebot.com/api/v1/messages?state=queued&limit=50" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"

Tell people why

If your app shows what it sent, show hold.description. It's written for a person and set in your account's time zone: "Waiting for quiet hours to end at 8:00 AM tomorrow.", "Waiting for your Mac to come back online.", "Waiting its turn. It should go around 2:41 PM." The dashboard, the Mac's menu and BlueBot's MCP tools all use the same words.