SMS

Send an SMS (Tier 2)

POST /v1/sms

Scope

messages:send

Tier

Tier 2 (reaches or unlocks real people)

Data

Personal data

Idempotency

Idempotency-Key: required

TIER 2: needs the scope messages:send, the account switch tier2_sms_send_enabled (403 tier_not_enabled otherwise) and a key made by the account's guided sending setup (IP allow-list, daily cap, per-minute cap). The message is sent from the account's own sender name. Before anything is sent the number goes through the same compliance checks as the console: Do-Not-Call (422 on_dnc), blocked countries (422 blocked_country), calling hours and consent (422 message_refused, errors[0].code says why) and the balance (402 insufficient_balance). Every message carries your own client_reference: a second message with the same reference answers 409 duplicate_client_reference and nothing is sent again. Messages count against the key's and the account's daily and per-minute caps and the account's estimated-spend limit (429 daily_cap_reached / rate_limit_exceeded / spend_cap_reached). An administrator's "stop all sending" answers 403 sending_suspended; a new self-service account answers 403 outbound_not_approved until DialerBee approves its outbound messaging.

Parameters

Request body

The message.

JSON: SmsSendRequest

Response

202: Accepted for sending.

Examples

Request example

curl

curl -sS -X POST \
  "https://app.dialerbee.com/api/v1/sms" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY" \
  -H 'Idempotency-Key: 5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a' \
  -H "Content-Type: application/json" \
  --data '{
  "to": "+12125550123",
  "body": "Your appointment is confirmed for Thursday at 2 pm.",
  "client_reference": "order-1001"
}'

Python (SDK)

from dialerbee import DialerBee

db = DialerBee()  # reads DIALERBEE_API_KEY from the environment

result = db.sms.send(
    to="+12125550123",
    body="Your appointment is confirmed for Thursday at 2 pm.",
    client_reference="order-1001",
    idempotency_key="5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a",
)

Response example

202

{
  "id": "msg_0f8fad5b-d9cb-469f-a165-70867728950e",
  "to": "+12125550123",
  "status": "queued",
  "client_reference": "order-1001",
  "created_at": "2026-09-29T09:15:00Z"
}

Error examples

422 on_dnc

{
  "type": "https://docs.dialerbee.com/errors/on-dnc",
  "title": "Destination is on DNC",
  "status": 422,
  "detail": "The number is on the account's Do-Not-Call list, so this action is refused.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "on_dnc",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

422 blocked_country

{
  "type": "https://docs.dialerbee.com/errors/blocked-country",
  "title": "Destination country blocked",
  "status": 422,
  "detail": "The platform does not contact numbers in this country.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "blocked_country",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

422 message_refused

{
  "type": "https://docs.dialerbee.com/errors/message-refused",
  "title": "Message refused by a compliance check",
  "status": 422,
  "detail": "A compliance check refused the message (for example calling hours or missing consent), so nothing was sent.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "message_refused",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

Errors

Objects

SmsSendRequest

SmsMessage