Send a message

POST /v1/send: send a text message with your dashboard key. Request body, response and errors.

POST /v1/send is live. It sends a text message with a dashboard key.

POST https://api.bluereacher.com/v1/send

Authentication

Send your dashboard key in the x-custom-location-key header. The route also accepts x-api-key or Authorization: Bearer. You create the key in the Blue Reacher dashboard under Developers. See API keys.

Request body

Send the body as JSON with Content-Type: application/json. Any other content type returns 415 unsupported_media_type.

Field	Type	Description
`phone`	string	Required. The full number with country code, for example `+15551234567`. A 10-digit US number is also accepted and gets +1.
`message`	string	Required. The text of the message.
`message_id`	string	Optional. Your own id for the message. If you leave it out, Blue Reacher generates one.
`location_id`	string	Only needed when the key covers more than one workspace.

Sending to a workspace the key does not cover returns 403 wrong_workspace. If the key covers more than one workspace and you leave out location_id, the request returns 400 workspace_required.

Send a text message

curl -X POST https://api.bluereacher.com/v1/send \
  -H "x-custom-location-key: YOUR_SEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "message": "Thursday 10am still work for the walkthrough?",
    "message_id": "walkthrough-reminder"
  }'

Response

A successful request returns 202:

{
  "success": true,
  "message_id": "walkthrough-reminder",
  "status": "queued",
  "delay_seconds": null
}

success: true when the message was accepted.
message_id: the id you sent, or the id Blue Reacher generated.
status: queued. The response does not say the message was delivered.
delay_seconds: a number of seconds, or null.

Errors

Error responses look like this:

{
  "success": false,
  "error": "Human-readable message",
  "error_code": "invalid_phone"
}

Status	Code	Meaning
400	`invalid_json`	The body is not valid JSON.
400	`invalid_phone`	`phone` is not a valid number with a country code.
400	`missing_message`	`message` is missing.
400	`workspace_required`	The key covers more than one workspace and `location_id` is missing.
401	`missing_api_key`	No key was sent.
401	`invalid_api_key`	The key is not valid or has been revoked.
403	`wrong_workspace`	`location_id` is a workspace the key does not cover.
405	`method_not_allowed`	The route takes POST only. A GET or any other method returns this.
415	`unsupported_media_type`	Send the body with `Content-Type: application/json`.
429	`rate_limited`	Too many requests. Retry later.
502	`send_failed`	The send failed. Retry shortly.
504	`upstream_timeout`	The send timed out. Retry shortly.

Fix the request before you send it again for any 400, 401, 403 or 415 error.

Checking delivery status

POST /v1/send returns queued, not a delivery result. Save the message_id from each response on your side.

To read delivery status from the API, send through POST /v1/messages with an OAuth access token instead, then read it with GET /v1/messages/{id}. See Authentication.