# Postman recipes

> Try every endpoint from DogBot’s Postman collection before you write any code.

Three recipes for Postman. Each names its trigger and the DogBot step, lists the fields to map and says how to test it with your own number before anyone else gets a text.

## How Postman connects

- **[API](https://getdogbot.com/docs/api)**: Your own code calls DogBot’s REST API and listens to its signed webhooks.

## Send yourself a first text

| Part             | What it is                      |
| ---------------- | ------------------------------- |
| Trigger          | You send a request from Postman |
| Action           | `POST /v1/messages`             |
| Connects through | [API](https://getdogbot.com/docs/api)                |

### Steps

1. Import DogBot’s Postman collection and its environment from the OpenAPI and Postman docs page, and paste your API key into the environment’s dogbotApiKey.
2. Open the request for POST /v1/messages and set the to field to your own number and the text field to a short message.
3. Send it, then open GET /v1/messages/{id} with the id it returned to watch the state move from queued to sent to delivered.

### Map the fields

| DogBot field | Map it to                                                                                                                                    |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `to`         | The person’s mobile number from Postman. US numbers can leave off the +1.                                                                    |
| `text`       | Hello from Postman.                                                                                                                          |
| `metadata`   | `source` set to `postman`, and `record_id` set to the record’s id, so the status and reply webhooks for this text can find the record again. |
| `service`    | Auto, the default: iMessage when the person uses it, otherwise SMS through your iPhone.                                                      |

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

```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 Postman.',
  metadata: {
    source: 'postman',
    record_id: '1042',
  },
}, { idempotencyKey: 'postman-1042' });
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 Postman.",
    metadata={
        "source": "postman",
        "record_id": "1042",
    },
    idempotency_key="postman-1042",
)
print(message)
```

### Test it

Run the request with your own number in `to`. A text arrives on your phone from your own number.

## Check your Mac before you build

| Part             | What it is                          |
| ---------------- | ----------------------------------- |
| Trigger          | You send a request from Postman     |
| Action           | Postman acts on what DogBot reports |
| Connects through | [API](https://getdogbot.com/docs/api)                    |

### Steps

1. Send GET /v1/device to see whether your Mac is online, when it last checked in and how many texts are held.
2. Send GET /v1/lookup with a number to see whether it’s likely on iMessage, and on what basis.

### Test it

Try it once with your own number before you turn it on for anyone else.

## See that a retry never sends twice

| Part             | What it is                      |
| ---------------- | ------------------------------- |
| Trigger          | You send the same request twice |
| Action           | `POST /v1/messages`             |
| Connects through | [API](https://getdogbot.com/docs/api)                |

### Steps

1. Send POST /v1/messages with an Idempotency-Key header.
2. Send the same request again with the same key, and DogBot answers with the first message instead of sending another.
3. Change the body but keep the key, and DogBot answers 409 idempotency_conflict.

### Map the fields

| DogBot field | Map it to                                                                                                                                    |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `to`         | The person’s mobile number from Postman. US numbers can leave off the +1.                                                                    |
| `text`       | Testing a retry from Postman.                                                                                                                |
| `metadata`   | `source` set to `postman`, and `record_id` set to the record’s id, so the status and reply webhooks for this text can find the record again. |
| `service`    | Auto, the default: iMessage when the person uses it, otherwise SMS through your iPhone.                                                      |

```bash
curl -X POST "https://getdogbot.com/api/v1/messages" \
  -H "Authorization: Bearer $DOGBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: postman-1042" \
  -d '{
    "to": "+15555550123",
    "text": "Testing a retry from Postman.",
    "metadata": {
      "source": "postman",
      "record_id": "1042"
    }
  }'
```

```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: 'Testing a retry from Postman.',
  metadata: {
    source: 'postman',
    record_id: '1042',
  },
}, { idempotencyKey: 'postman-1042' });
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="Testing a retry from Postman.",
    metadata={
        "source": "postman",
        "record_id": "1042",
    },
    idempotency_key="postman-1042",
)
print(message)
```

### Test it

Run the request with your own number in `to`. A text arrives on your phone from your own number.

## Before you turn it on

- Text only people who asked to hear from you. Anyone who replies STOP goes on your stop list, and DogBot cancels texts to them. [Stop words](https://getdogbot.com/docs/concepts/stop-words)
- A text that can’t go yet waits with a hold rather than failing: texting hours, your Mac away, a daily limit. [Holds](https://getdogbot.com/docs/concepts/holds)
- [Postman with DogBot](https://getdogbot.com/integrations/postman) on the integrations page says what else the two do together.
