# Holds

> Why a text that can't go yet is accepted and waits instead of failing, every reason it can wait, the order they're checked in, and when each one clears.

A text that can't go right now isn't refused. DogBot 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 texting 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:

The answer, `201`:

```json
{
  "id": "msg_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "message",
  "state": "queued",
  "to": "+15555550123",
  "hold": {
    "reason": "texting_hours",
    "until": "2026-11-14T14:00:00.000Z",
    "rule": "federal_law",
    "state": "TX",
    "description": "Federal law allows business texts from 8 AM to 9 PM where this person lives. It goes at 8:00 AM tomorrow."
  },
  "expires_at": "2026-11-15T04:40:00.000Z"
}
```

| Field         | What it is                                                                                                                                                                                                              |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reason`      | Why it waits, as a stable code. Program against this.                                                                                                                                                                   |
| `until`       | When it should stop waiting, when that's known: when texting hours open where the person lives, the next midnight, or the text's estimated slot in the pace. `null` when nobody can say, such as while the Mac is away. |
| `rule`        | Only on `texting_hours`: whose hours held it, `state_law`, `federal_law` or `yours`. `null` on every other reason. [Texting hours](https://getdogbot.com/docs/concepts/texting-hours)                                                        |
| `state`       | Only on `texting_hours`: the person’s state, or `null` when DogBot doesn’t know it. `null` on every other reason.                                                                                                       |
| `description` | The hold in words, in your time zone, ready to show a person.                                                                                                                                                           |

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

## Every reason

| `hold.reason`            | What it means                                                                                                                                                                                                                                                                  | When it clears                                                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `account_held`           | DogBot’s operator paused this account’s sending. Nothing sends.                                                                                                                                                                                                                | Only DogBot, after you write to support. Meanwhile the API still accepts sends, and they wait with this hold.                           |
| `platform_stopped`       | DogBot stopped all sending for every account, for an incident.                                                                                                                                                                                                                 | DogBot turning sending back on. Texts go in their order, subject to their expiry.                                                       |
| `plan_lapsed`            | The account’s plan isn’t active.                                                                                                                                                                                                                                               | An active plan again (update the card on the Billing page).                                                                             |
| `paused`                 | You paused sending from the Mac’s menu or the dashboard.                                                                                                                                                                                                                       | Resuming, or the pause’s own end (`until`): an hour, or 8:00 AM in your zone.                                                           |
| `device_offline`         | Your Mac hasn’t checked in for 2 minutes: asleep, off, or off the internet.                                                                                                                                                                                                    | The Mac checking in again. If it stays away past the text’s `expires_at`, the text expires.                                             |
| `texting_hours`          | It’s outside texting hours where the person lives: their state’s law, the federal 8 AM to 9 PM, or the hours you set for their state.                                                                                                                                          | `until`: when texting hours open where they live. The text then takes its place in the pace.                                            |
| `new_people_paused`      | Your number’s health dropped: many texts fell back to regular texts, many iMessages didn’t show as delivered, or several people replied STOP. DogBot paused texts to people who haven’t replied yet. Texts to people already talking with you still go.                        | You pressing **Resume texting new people** under Number health in Settings, after you look over who you’re texting. There’s no `until`. |
| `warm_up_limit`          | Your number is still warming up, and you’ve texted as many people who haven’t replied yet as it allows today: 20 at first, rising one step each day you text while your number stays healthy, up to 100, and then the limit ends. People already talking with you don’t count. | `until`: the next midnight in your zone. The limit isn’t a setting.                                                                     |
| `daily_new_people_limit` | You’ve texted as many new people today as your setting allows (50 by default). People you already have a conversation with don’t count.                                                                                                                                        | `until`: the next midnight in your zone, or raising the setting.                                                                        |
| `platform_daily_limit`   | The account sent 1,000 texts today, DogBot’s ceiling for one account.                                                                                                                                                                                                          | `until`: the next midnight in your zone. This one isn’t a setting.                                                                      |
| `pacing`                 | Waiting its turn: the Mac leaves your pace (20 seconds by default) between texts.                                                                                                                                                                                              | `until`: its estimated slot. It moves as texts ahead of it go or are canceled.                                                          |

## The order they're checked

DogBot checks the reasons in a fixed order and shows the first that applies, so a text has one hold at a time. The first five 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`

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

6. `texting_hours`, read where the person lives
7. `daily_new_people_limit`, only for a text to someone you've never texted with through DogBot
8. `platform_daily_limit`
9. `pacing`

When one hold clears, the next may show. A text queued at 11:00 PM waits on `texting_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](https://getdogbot.com/docs/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](https://getdogbot.com/docs/concepts/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`](https://getdogbot.com/docs/errors/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.
- **DogBot pausing your account** shows as `account_held` on every queued text. Write to [support@getdogbot.com](mailto:support@getdogbot.com); a person at DogBot 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](https://getdogbot.com/docs/concepts/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.

```bash
curl "https://getdogbot.com/api/v1/messages?state=queued&limit=50" \
  -H "Authorization: Bearer $DOGBOT_API_KEY"
```

```ts
import DogBot from '@getdogbot/sdk';

const client = new DogBot({ apiKey: process.env.DOGBOT_API_KEY });

const page = await client.messages.list({
  state: 'queued',
  limit: 50,
});
console.log(page.data);
```

```python
import os
from dogbot import DogBot

client = DogBot(api_key=os.environ["DOGBOT_API_KEY"])

page = client.messages.list(state="queued", limit=50)
print(page.data)
```

| You got                                       | It means                                                       | Do next                                                                                                                        |
| --------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Every text with the same `hold.reason`        | An account-wide hold: the Mac is away, or sending is paused.   | Fix the cause, or wait for `hold.until`.                                                                                       |
| `texting_hours` on texts sent at night        | It’s outside texting hours where those people live.            | Nothing. Each text goes when the hours open where its person lives. [Texting hours](https://getdogbot.com/docs/concepts/texting-hours)              |
| `pacing` with times spread over the next hour | A long line at your pace.                                      | Nothing; they go in order. Lower `pace_seconds` only if you understand the risk. [Sending rules](https://getdogbot.com/docs/concepts/sending-rules) |
| `daily_new_people_limit` on some texts        | You've texted as many new people today as your setting allows. | Wait for midnight, or raise `new_people_per_day`.                                                                              |
| `device_offline` with `until: null`           | The Mac hasn't checked in for 2 minutes.                       | Wake it, or check its power and network. [The Mac app](https://getdogbot.com/docs/concepts/mac-app)                                                 |

## 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: "Florida law allows business texts from 8 AM to 8 PM where this person lives. It goes 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 DogBot's MCP tools all use the same words.
