# Sending rules

> The settings that control how fast and how often your number sends, each with its default, what it does, how to read and change it through the API, and the warnings DogBot gives when you loosen one.

DogBot sends from your own number, so it sends the way a careful person would. A handful of settings decide how: how far apart texts go, how many new people you text in a day, the texting hours for each state, how long a text may wait, and whether STOP works. Each one starts at a safe default, and each one is yours to change, under **Settings → Sending rules** in the dashboard or with `PATCH /v1/settings`.

A text that a rule holds back isn't refused. It's accepted and waits with a [hold](https://getdogbot.com/docs/concepts/holds) that says why, then goes by itself.

## The settings

| Setting              | Default                                                         | Range                                             | What it does                                                                                                                                                                                                                     |
| -------------------- | --------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pace_seconds`       | 20                                                              | 5 to 300                                          | The gap between two texts leaving your Mac.                                                                                                                                                                                      |
| `new_people_per_day` | 50                                                              | 0 to 1,000                                        | How many people you've never texted can be texted in one day.                                                                                                                                                                    |
| `texting_hours`      | Each state’s law                                                | Whole hours for one state, several or all of them | Texts wait until it’s within texting hours where each person lives.                                                                                                                                                              |
| `time_zone`          | Your browser's zone when you signed up, else `America/New_York` | Any IANA zone                                     | The zone for people with no known state, "today" and every time DogBot shows you.                                                                                                                                                |
| `stop_words`         | On                                                              | On or off                                         | A reply of only STOP (or another stop word) puts the person on your stop list.                                                                                                                                                   |
| `expiry_hours`       | 24                                                              | 1 to 168                                          | A text still waiting this long after it was due expires and never goes.                                                                                                                                                          |
| `paused_until`       | `null`                                                          | Any future time, or `null`                        | While it's in the future, nothing goes.                                                                                                                                                                                          |
| `inbound_mode`       | `replies`                                                       | `replies` or `everything`                         | Which conversations the Mac copies to DogBot. It's here because it's a setting, not a rule. [The Mac app](https://getdogbot.com/docs/concepts/mac-app)                                                                                                |
| `business_name`      | `null`                                                          | Up to 120 characters, or `null`                   | What `{{business}}` fills in. Until you set it, the widget's first text leaves out who it's from, and a template that needs `{{business}}` with no fallback can't be sent through the API. [Templates](https://getdogbot.com/docs/concepts/templates) |

One more number isn't yours to change: `platform_daily_limit`, DogBot's ceiling of 1,000 texts a day from one account. It's there to protect your number, and [Limits](https://getdogbot.com/docs/limits) says why.

## Pace

`pace_seconds` is the time between two texts leaving the Mac. At the default of 20 seconds, a hundred texts take about 33 minutes. Each text waiting its turn has `hold.reason: "pacing"` with an estimated time in `hold.until`, and the estimate moves as texts ahead of it go.

People don't send texts a second apart. Texts that go out at a machine's rhythm are what Apple and the carriers look for, so the default is slower than you might expect. Anything under 10 seconds gets a warning.

Pace is one queue for the whole account. A text you send now goes after the texts already waiting, unless you [schedule](https://getdogbot.com/docs/sending/scheduled) the others for later.

## New people per day

`new_people_per_day` caps how many people you text for the first time each day, counted from midnight in your `time_zone`. A new person is someone with no text in DogBot yet, in either direction. Five texts to the same new person count once.

When the day's count is reached, texts to more new people wait with `daily_new_people_limit` until midnight. Texts to people you already know keep going. Group chats never count.

Set it to `0` to text only people you already know. Over 200 gets a warning, because a personal number that reaches hundreds of strangers a day is the pattern that gets numbers flagged.

## Texting hours

Every text waits with `texting_hours` until it’s within texting hours where the person lives. Each state starts at its law, which is 8 AM to 9 PM in most states, and you can change one state or all of them. `texting_hours.custom` lists the places you changed. [Texting hours](https://getdogbot.com/docs/concepts/texting-hours) has the law for each state, how DogBot finds where a person lives, and how to change or reset the hours.

## Expiry

Every text has an `expires_at`. Unless you set one on the send, it's the time the text was due plus `expiry_hours`. A text still waiting at that moment becomes `expired`, `message.expired` fires, and it never goes. A Mac that's away for a weekend won't send Friday's "Your table is ready" on Monday.

Choose a short `expires_at` on texts that only make sense soon, and a long one for texts that can wait. `expiry_hours` sets the default for texts made after you change it; texts already waiting keep the `expires_at` they were given.

## Stop words

With stop words on, a reply of only STOP, STOPALL, UNSUBSCRIBE, CANCEL, END or QUIT puts that person on your stop list, and DogBot cancels every text still waiting for them. [Stop words](https://getdogbot.com/docs/concepts/stop-words) has the rules and the stop list API.

## Pausing

Set `paused_until` to a time to stop all sending until then, and to `null` to resume. While paused, texts are accepted and wait with `paused`. The Mac's menu has **Pause for an hour** and **Pause until tomorrow morning**, and the dashboard can pause until you resume; a pause with no end reads back as a date far in the future.

## Read the settings

```bash
curl "https://getdogbot.com/api/v1/settings" \
  -H "Authorization: Bearer $DOGBOT_API_KEY"
```

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

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

const settings = await client.settings.get();
console.log(settings);
```

```python
import os
from dogbot import DogBot

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

settings = client.settings.get()
print(settings)
```

The answer, `200`:

```json
{
  "object": "settings",
  "business_name": "Dana's Salon",
  "time_zone": "America/Chicago",
  "pace_seconds": 20,
  "new_people_per_day": 50,
  "texting_hours": {
    "custom": []
  },
  "stop_words": {
    "enabled": true,
    "words": ["stop", "stopall", "unsubscribe", "cancel", "end", "quit"],
    "start_words": ["start", "unstop", "yes"]
  },
  "expiry_hours": 24,
  "inbound_mode": "replies",
  "paused_until": null,
  "platform_daily_limit": 1000,
  "warnings": []
}
```

Reading needs a key with the `account:read` scope.

## Change them

Send only the settings you're changing. Everything you leave out stays as it is. Changing needs the `messages:send` scope, since these settings decide what goes out.

Dana runs a small salon in Austin, and some of her clients live in Florida. She names her business, moves her account to Central time, slows the pace to 30 seconds, and texts her Florida clients only from 9 AM to 6 PM, Monday to Saturday:

```bash
curl -X PATCH "https://getdogbot.com/api/v1/settings" \
  -H "Authorization: Bearer $DOGBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Dana'\''s Salon",
    "time_zone": "America/Chicago",
    "pace_seconds": 30,
    "texting_hours": {
      "places": [
        {
          "place": "FL",
          "hours": {
            "start_hour": 9,
            "end_hour": 18,
            "sundays": false
          }
        }
      ]
    }
  }'
```

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

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

const settings = await client.settings.update({
  businessName: 'Dana\'s Salon',
  timeZone: 'America/Chicago',
  paceSeconds: 30,
  textingHours: {
    places: [
      {
        place: 'FL',
        hours: {
          startHour: 9,
          endHour: 18,
          sundays: false,
        },
      },
    ],
  },
});
console.log(settings);
```

```python
import os
from dogbot import DogBot

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

settings = client.settings.update(
    business_name="Dana's Salon",
    time_zone="America/Chicago",
    pace_seconds=30,
    texting_hours={
        "places": [
            {
                "place": "FL",
                "hours": {
                    "start_hour": 9,
                    "end_hour": 18,
                    "sundays": False,
                },
            },
        ],
    },
)
print(settings)
```

The answer is the whole settings object as it now stands. A change takes effect at once: DogBot works out every waiting text's hold again in the same step, so a text waiting on `daily_new_people_limit` after you raise the limit is ready on the Mac's next check-in, about 10 seconds later.

| You got                                                                | It means                                                                                                            | Do next                                                       |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `200` with your new values and `"warnings": []`                        | The change is saved.                                                                                                | Nothing. Read `hold` on a waiting text to see the new timing. |
| `200` with something in `warnings`                                     | Saved, but a setting is looser than is safe.                                                                        | Read the warning, and change it back if you didn't mean it.   |
| `400` [`invalid_request`](https://getdogbot.com/docs/errors/invalid_request) with `details` | A value is out of range, texting hours end before they start, a zone isn't one DogBot knows, or the body was empty. | Fix the field named in `details`.                             |
| `403` [`insufficient_scope`](https://getdogbot.com/docs/errors/insufficient_scope)          | The key can't send texts, so it can't change what goes out.                                                         | Use a key with `messages:send`.                               |

## Warnings

Loosening a rule is allowed, and DogBot says what it costs. `warnings` holds a sentence for each setting past the safe line:

| When                                   | The warning                                                                                                 |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `pace_seconds` under 10                | Texts less than 10 seconds apart can look automated to Apple and the carriers. 20 seconds or more is safer. |
| `new_people_per_day` over 200          | Texting more than 200 new people a day from one number is how numbers get flagged as spam.                  |
| Texting hours wider than a state’s law | Some of your texting hours are wider than the law allows. Settings → Texting hours shows which.             |
| Stop words off                         | Stop words are off. Someone who replies STOP will keep getting texts until you stop them by hand.           |

The same warnings show in the dashboard beside each setting.

## What the rules can't do

The rules lower the chance that Apple or a carrier flags your number. They can't remove it, and Apple doesn't publish what it looks for. The rules also don't decide whether you may text someone. That's up to the law where they live and DogBot's acceptable use policy, which [Capabilities](https://getdogbot.com/docs/concepts/capabilities#send-at-volume) sums up. Text people who know you and expect to hear from you, and keep the defaults unless you have a reason.
