Send SMS with cURL

Send a fixed reminder to a simulated recipient, then read the resulting message. This uses the same send endpoint as the SDK examples.

1. Prepare your workspace

Complete first SMS setup: enable the US destination, fund your workspace and prepare an owned US-eligible sender with the required registration. The recipient +15005550006 simulates delivery without reaching a handset. The send still incurs the normal destination charge.

Install cURL, jq, and Python 3 (used below to create a request key). Set the API host to match your key: https://us1.platform.bird.com for bk_us1_, or https://eu1.platform.bird.com for bk_eu1_.

Ejemplo de código

export BIRD_API_KEY="YOUR_API_KEY"
export BIRD_API_BASE="https://us1.platform.bird.com"
export BIRD_SMS_FROM="YOUR_ELIGIBLE_US_NUMBER"
export BIRD_SMS_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')"

Generate this operation key once. Retain it with the request while resolving this attempt; do not generate a new key to retry an uncertain send.

2. Prepare and send the request

Build sms-request.json once. jq handles JSON escaping for the configured sender.

Ejemplo de código

jq -n --arg from "$BIRD_SMS_FROM" '{
  from: $from,
  to: "+15005550006",
  text: "Your studio visit is tomorrow at 14:00.",
  category: "transactional",
  metadata: {booking: "FN-1042"}
}' > sms-request.json

Send that file and save the response:

Ejemplo de código

curl --fail-with-body --silent --show-error \
  "$BIRD_API_BASE/v1/sms/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Idempotency-Key: $BIRD_SMS_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @sms-request.json > sms-response.json

A successful request returns 202 and a body containing the accepted message id and status. If cURL exits nonzero, inspect sms-response.json before continuing. A timeout may leave that file empty; it does not establish that no message was accepted.

3. Inspect the same message

After a successful send, extract its ID and read the current state:

Ejemplo de código

BIRD_SMS_ID="$(jq -er '.id' sms-response.json)"
curl --fail-with-body --silent --show-error \
  "$BIRD_API_BASE/v1/sms/messages/$BIRD_SMS_ID" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  | jq '{id, status, segments}'

The simulated recipient progresses from acceptance through its delivery outcome. If it is still pending, read again later. Do not send another message to check whether the first arrived. For real traffic, subscribe to the relevant SMS events; acceptance, carrier handoff and delivery are separate observations.

Recover a failed or uncertain attempt

Result	Next action
401 or 403	Check the key, its workspace, regional host and SMS permissions.
402	Inspect the balance requirement and fund the intended workspace.
422	Correct the named field, sender eligibility or destination setting.
429	Respect the retry information and preserve the original operation identity.
Lost response or 5xx	Inspect the SMS log. If retrying, resend the same file with the same key under the idempotency rules.
Accepted without a final receipt	Keep the outcome unresolved and inspect the message or events.

A changed body represents a changed request. Do not reuse an existing key with new content, and do not assume that response retention supplies indefinite deduplication. Store message IDs with the application record that caused the send.

Continue the integration

SMS in Next.js or Express.
SMS in FastAPI or Django.
Sender setup, delivery events and SMS resources.

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Ver la guíaSending your first SMS Comprender el conceptoOne-way and two-way SMS Explorar la funcionalidadTwo-way SMS Seguir la ruta de aprendizajeBuild your first integration

Obtener un resumen de implementación