Recipes

Postman recipes

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

Three recipes for Postman. Each names its trigger and the BlueBot 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: Your own code calls BlueBot’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

Steps

Import BlueBot’s Postman collection and add your API key to the collection’s authorization.
Open the request for POST /v1/messages and set the to field to your own number and the text field to a short message.
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

BlueBot 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.

POST/v1/messagesSend a text →

curl -X POST "https://usebluebot.com/api/v1/messages" \
  -H "Authorization: Bearer $BLUEBOT_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"
    }
  }'

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 BlueBot reports
Connects through	API

Steps

Send GET /v1/device to see whether your Mac is online, when it last checked in and how many texts are held.
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

Steps

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

Map the fields

BlueBot 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.

POST/v1/messagesSend a text →

curl -X POST "https://usebluebot.com/api/v1/messages" \
  -H "Authorization: Bearer $BLUEBOT_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"
    }
  }'

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 BlueBot cancels texts to them. Stop words
A text that can’t go yet waits with a hold rather than failing: quiet hours, your Mac away, a daily limit. Holds
Postman with BlueBot on the integrations page says what else the two do together.