# Quickstart

> Make an API key and text yourself from your own number in four steps, then learn the five things to know before you send in a loop.

This takes about five minutes. You need a DogBot account with your Mac connected. If you haven't connected it yet, open **Connect your Mac** in the dashboard first; the app walks you through it.

Every example below shows curl, the TypeScript and Python SDKs, Go, Ruby, PHP and plain `fetch`. Pick a language once and every example on every page follows it.

### Make an API key

In the dashboard, open **Developers → API keys** and press **New key**. Name it after what will use it ("Quickstart" will do), keep the scopes `messages:send` and `messages:read` ticked, and copy the key. It starts with `dog_live_` and is shown once.

Put it in your environment so the examples can read it:

```bash
export DOGBOT_API_KEY="dog_live_…"
```

Check it with `GET /v1/me`, which says which account and key a request acts as:

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

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

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

const me = await client.me();
console.log(me);
```

```python
import os
from dogbot import DogBot

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

me = client.me()
print(me)
```

| You got                         | It means                                                                       | Do next                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| `200` with your account's email | The key works.                                                                 | Go on to step 2.                                                                 |
| `401 unauthorized`              | DogBot doesn't know the key: mistyped, revoked, or not sent as `Bearer <key>`. | Copy the key again, or make a new one. [unauthorized](https://getdogbot.com/docs/errors/unauthorized) |
| `403 insufficient_scope`        | The key can't read the account.                                                | Tick `account:read` on the key, or skip this check.                              |

### Check your Mac

DogBot sends through your Mac, so make sure it's there:

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

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

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

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

```python
import os
from dogbot import DogBot

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

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

| You got                                      | It means                                                                   | Do next                                                                     |
| -------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `"status": "online"` and `"checks_ok": true` | The Mac checked in within the last 2 minutes and every check passed.       | Go on to step 3.                                                            |
| `"status": "offline"`                        | The Mac hasn't checked in for 2 minutes: asleep, off, or off the internet. | Wake it. Texts you send now wait for it rather than fail.                   |
| `"status": "never_connected"`                | No Mac is connected to this account.                                       | Open **Connect your Mac** in the dashboard.                                 |
| `"checks_ok": false`                         | A setup check needs you, such as Messages being signed out.                | Open DogBot from the Mac's menu bar; it says which check and how to fix it. |

### Text yourself

Send a text to your own phone number. It arrives in Messages on your iPhone like any other text you send yourself.

```bash
curl -X POST "https://getdogbot.com/api/v1/messages" \
  -H "Authorization: Bearer $DOGBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-first-text" \
  -d '{
    "to": "+15555550123",
    "text": "Hello from DogBot",
    "metadata": {
      "test": "quickstart"
    }
  }'
```

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

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

const message = await client.messages.send({
  to: '+15555550123',
  text: 'Hello from DogBot',
  metadata: {
    test: 'quickstart',
  },
}, { idempotencyKey: 'quickstart-first-text' });
console.log(message);
```

```python
import os
from dogbot import DogBot

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

message = client.messages.send(
    to="+15555550123",
    text="Hello from DogBot",
    metadata={
        "test": "quickstart",
    },
    idempotency_key="quickstart-first-text",
)
print(message)
```

Put your own number in `to`. US numbers can leave off the `+1`, and `(555) 555-0123` works too.

| You got                                           | It means                                                                                            | Do next                                                                                                                                                             |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `201` with `"state": "queued"` and `"hold": null` | DogBot accepted the text and it's next in line. It goes within a few seconds.                       | Copy the message's `id` and go on to step 4.                                                                                                                        |
| `201` with a `hold`                               | DogBot accepted the text and it's waiting. `hold.reason` says why and `hold.until` says until when. | Read [Holds](https://getdogbot.com/docs/concepts/holds). A test at night usually meets `texting_hours`.                                                                                  |
| `201` with `"state": "canceled"`                  | Your number is on your own stop list.                                                               | Take it off with `DELETE /v1/stops/{person}` and send again.                                                                                                        |
| `400 invalid_request`                             | A field is wrong. `error.details` names it.                                                         | Fix the field and send again with a new `Idempotency-Key`. The old key keeps its first answer, and a changed request under it is refused as `idempotency_conflict`. |

A text that can't go right now is never refused. It's accepted with a `hold` and goes on its own when the hold ends, so a loop never needs to retry a send.

### Watch it go

Read the message back with the `id` from step 3:

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

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

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

const message = await client.messages.get('msg_1Hq2LxW9cVbN3mKpRtYs0a');
console.log(message);
```

```python
import os
from dogbot import DogBot

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

message = client.messages.get("msg_1Hq2LxW9cVbN3mKpRtYs0a")
print(message)
```

| You got                                       | It means                                                    | Do next                                                                 |
| --------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------- |
| `"state": "sent"` and `"service": "imessage"` | Messages on your Mac shows it sent as an iMessage.          | Look at your phone. Soon `delivered_at` fills in too.                   |
| `"state": "sent"` and `"service": "sms"`      | It went as a regular text through your iPhone.              | SMS never reports delivery, so `sent` is as far as it goes.             |
| `"state": "queued"` or `"sending"`            | It hasn't gone yet.                                         | Read it again in a few seconds, or check `hold`.                        |
| `"state": "failed"`                           | Messages couldn't send it. `failure.reason` says why.       | Read [Message states](https://getdogbot.com/docs/concepts/message-states).                   |
| `"state": "unconfirmed"`                      | The Mac handed it to Messages and couldn't confirm it went. | Look in Messages, then settle it with `POST /v1/messages/{id}/resolve`. |

Polling is fine for a test. In an app, let DogBot tell you instead: point a [webhook](https://getdogbot.com/docs/webhooks) at your server, or run `dogbot listen --forward-to http://localhost:3000/webhooks` while you build.

## Before you loop

You've sent one text. Before you send a hundred from a loop, a Zap or an agent, know these five things.

### Holds

A send is answered at once, and a text that can't go yet comes back `queued` with a `hold`. It goes by itself when the hold clears. Don't retry a held text and don't treat a hold as an error; read `hold.reason` if you want to tell someone why it's waiting. [Holds](https://getdogbot.com/docs/concepts/holds) lists every reason.

The answer, `201`:

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

### Pacing

The Mac leaves 20 seconds between texts by default, the way a person sends them one at a time. Send 30 texts in a loop and the 30th goes about 10 minutes later. You can set the pace from 5 to 300 seconds; a faster pace is the quickest way to get a number flagged. [Sending rules](https://getdogbot.com/docs/concepts/sending-rules)

### Texting hours

Each text waits until it’s within texting hours where the person lives, which start at their state’s law: 8 AM to 9 PM in most states. A text sent at 11 PM goes the next morning, unless it expires first. You can change the hours for one state or all of them. [Texting hours](https://getdogbot.com/docs/concepts/texting-hours)

### Idempotency

Send an `Idempotency-Key` header with every POST: any string that is new for each text you mean to send, such as your own order id. If your request times out and you send it again with the same key, you get the first answer back and nobody gets two texts. The SDKs make a key for you. [Idempotency](https://getdogbot.com/docs/concepts/idempotency)

### Expiry

A text still waiting 24 hours after it was due expires and never goes, so "Your table is ready" can't arrive a day late. Set `expires_at` on a send to choose a shorter or longer wait, and listen for `message.expired`. [Scheduled sends](https://getdogbot.com/docs/sending/scheduled)

## Next

- [Receive replies](https://getdogbot.com/docs/webhooks): a webhook for `message.received`.
- [Send a picture](https://getdogbot.com/docs/sending/files): upload a file and send it with the words.
- [Install an SDK](https://getdogbot.com/docs/sdks/typescript): retries, idempotency keys and paging are built in.
- [Limits](https://getdogbot.com/docs/limits): every cap, why it's there, and what happens when you reach it.
