Send text messages in bulk

This guide sends the same one-way text to many people. A text message batch holds up to 1,000 recipients, one sender number, and one message body. Resia sends from a queue at the pace your rate limits allow.

For two-way conversations, use a Chat Agent instead.

Before you start

• Complete Get access, and keep the terminal open.
• Own a Resia number that is on an active 10DLC campaign. Without one, carriers filter or block the texts. See Register for 10DLC texting.
• Resia texts numbers in the United States only.
• Only send texts that match the campaign you registered, to people who agreed to receive them.

Submit the batch

read -r -p 'Your sending number, including + and country code: ' FROM_PHONE_NUMBER
TEXT_BATCH_KEY=$(uuidgen)

jq -n --arg from "$FROM_PHONE_NUMBER" '{
  from_phone_number: $from,
  text: "Reminder: your appointment at Midtown Eye Care is tomorrow at 3:30 PM. Reply STOP to opt out.",
  text_messages: [
    {to_phone_number: "+12125550142", client_reference: "patient-1001"},
    {to_phone_number: "+13125550187", client_reference: "patient-1002"}
  ]
}' > text-batch.json

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/text-message-batches" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $TEXT_BATCH_KEY" \
  --data-binary @text-batch.json \
  --output text-batch-response.json

jq '{id, status, total, rejected_text_messages}' text-batch-response.json

Expected result: HTTP 202. Nothing is sent yet. The response lists one text_message_id for each accepted recipient, in the order you sent them.

Resia sends the text exactly as you wrote it. Every recipient gets the same body.

Rejected recipients

Resia checks each recipient on its own. It rejects a recipient when it cannot text the destination, or when the destination already appears earlier in the batch. Each entry in rejected_text_messages has its position, the number, its client_reference, and a reason.

Follow delivery

TEXT_BATCH_ID=$(jq -er '.id' text-batch-response.json)

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/text-message-batches/$TEXT_BATCH_ID/text-messages" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  | jq '.items[] | {text_message_id, client_reference, status}'

A text moves from queued to sent, and then to delivered, delivery_unconfirmed, or failed. Read one text with GET /v1/text-messages/{text_message_id} for its delivery detail and charge.

Stop a batch

curl --fail-with-body --silent --show-error \
  --request POST "$RESIA_API_BASE/v1/text-message-batches/$TEXT_BATCH_ID/cancel" \
  --header "Authorization: Bearer $RESIA_API_KEY"

Cancel stops the texts that are still queued. Texts that were already sent are not recalled.

API reference: Text Message Batches · Text Messages