Send text messages in bulk
A text message batch sends the same text and media to up to 1,000 people from one of your numbers. Resia sends from a queue at the pace your rate limits allow. In this guide, you will submit a batch, follow delivery, and stop a batch. For human replies, connect a human-text receiver. For AI replies, use a Chat Agent.
Before you start
- Complete Get access. Keep that terminal open, with
RESIA_API_BASEandRESIA_API_KEYset. - 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.
- Write every phone number in E.164 form, such as
+12125550142. See Number format.
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.
Every recipient gets the same text and ordered media_urls. For SMS without media, Resia checks its size first: a text above 10 SMS parts gets HTTP 422 and nothing is queued. See Text size limits.
In the portal: no page submits a batch. To do it without code, ask Butler, for example "Text these numbers from +1 212 555 0199: Reminder, your appointment is tomorrow at 3:30 PM". Butler asks you to confirm before it sends a text message batch.
Idempotency-Key is optional, but send one. Without a key, Resia records each request as a new batch. If you send the request again, for example after a timeout, Resia queues the recipients again, and each one can get the text twice. With a key, repeat a request with the same key and body to retry it safely. Resia returns the original batch and sends nothing twice. A changed body with the same key gets 409.
API reference: Submit a batch of text messages.
Include media
MMS uses a price per carrier part. See Billing.
Set media_urls to an ordered array of HTTPS URLs. Every recipient receives the same media.
Keep the media accessible to the carrier until each queued message leaves the queue.
For media-only MMS, send text: "" and a nonempty media_urls array.
Nonempty text must not contain only whitespace. Carrier media support and size rules also apply.
Text size limits
Resia limits text to 1,600 characters. Exactly "" is valid only with at least one media URL.
For SMS without media, Resia also checks the SMS part count before it accepts the batch.
A text can use at most 10 SMS parts. An SMS part, also called a segment, is one unit of transmission over the mobile network.
The number of characters that fit in 10 parts depends on the characters in the text:
| The text contains | Limit |
|---|---|
| Only characters from GSM-7, the standard SMS character set | 1,530 characters |
| One or more characters outside GSM-7 | 670 characters |
One character outside GSM-7, at any position, makes the whole text use Unicode. Thus that one character sets the limit for the whole text.
- GSM-7 has the English letters, the digits, and common punctuation. It also has some accented letters and marks, such as
é,è,à,ñ,ü,Ñ,¿, and¡. - The Spanish letters
á,í,ó, andúare not in GSM-7. Thus most Spanish texts have the 670 limit, and most English texts have the 1,530 limit. - Most emoji count as 2 characters.
- In a GSM-7 text,
€ ^ { } [ ] ~ \ |count as 2 characters. - The carrier replaces some punctuation with plain characters before it counts. For example, it replaces the curly quotes
“ ” ‘ ’and the quotation marks« » „with straight quotes, the dashes– —with-, and a no-break space with a space. Resia makes the same replacements when it counts. The recipient sees the plain characters. - The carrier keeps many other characters as they are. For example, it keeps
…,•, and½. These are outside GSM-7, so one of them makes the whole text use Unicode. Write...in place of…to keep the 1,530 limit.
| Example text | Characters | Parts | Result |
|---|---|---|---|
| An English text | 1,200 | 8 | Accepted |
The same English text with one ó added |
1,201 | 18 | Refused |
A Spanish text with ó |
650 | 10 | Accepted |
A Spanish text with ó |
700 | 11 | Refused |
| An English text with curly quotes | 1,530 | 10 | Accepted |
A text above the limit gets HTTP 422 with the code invalid_request. Resia creates no batch and sends nothing. The message gives the part count and names the characters outside GSM-7:
{
"error": {
"code": "invalid_request",
"message": "text: This text needs 23 SMS parts; the maximum is 10. Characters outside GSM-7 (ó, í) make the limit 670 characters, not 1,530, and most emoji count as 2. Shorten the text or send it as separate texts.",
"request_id": "01K3..."
}
}
To fix it, shorten the text, or send it as separate batches.
Resia does not shorten your text, remove accents, or divide it into separate messages.
The text field also has an input cap of 1,600 characters. A longer text gets HTTP 422 with the field name and that cap.
Any notice that Resia adds uses the same space. For example, an SMS chat opener can include an opt-out notice.
HTTP 202 means that Resia accepted the batch. It does not confirm carrier acceptance or delivery.
A text within the size limit can still fail for other carrier restrictions.
If the carrier refuses a text for its size, the result uses failure.code: "carrier_rejected" with this explanation:
Message too long. The maximum is 10 SMS parts. Some characters, such as ó, í, and emoji, reduce the available space. Shorten the text or send separate messages.
Send a longer text in separate batches
You can divide a longer text into separate batches. Each text needs to fit the carrier's size limit. Each text has its own delivery result and charge. Resia charges per segment.
Submission order alone does not guarantee delivery order. To submit text B after the carrier reports text A as delivered:
- Submit the first section as batch A.
- Read each recipient's
text_message_idthroughGET /v1/text-messages/{text_message_id}. - Wait for that recipient's result to show
delivered. - Submit section B for that recipient with a new
Idempotency-Key.
Use a new key for each new section. Repeat these steps for more sections.
If A fails or shows delivery_unconfirmed, its result does not confirm delivery.
A carrier delivery report does not guarantee the order of display or the order of reading on the phone.
Resia does not perform this sequence automatically.
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.
A failed text has a failure with a code and a message. The code is recipient_opted_out, destination_invalid, destination_unreachable, sender_not_registered, carrier_rejected, submission_failed, or unknown.
API reference: List the text messages in a batch and Read one text message.
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: Cancel a text message batch.
If something fails
422fortext: the text is above the size limit or the 1,600-character input cap. Read the message for the part count and the characters outside GSM-7. Shorten the text, or send it as separate batches. See Text size limits.409: you reused anIdempotency-Keywith a different body. Use a new key for a new batch.429: the batch is larger than your queued-text limit. See Rate limits.- A text fails with the size explanation: shorten it or use separate batches. A retry with the same key does not send a revised text.
- A text
failedwithsender_not_registered: the sending number is not yet on an active 10DLC campaign. Put it on one, wait until it shows as assigned, then send again. See Register for 10DLC texting. - A recipient is in
rejected_text_messages: read itsreason, fix the entry, and send it in a new batch.
Next steps
- Answer texts to your number: answer the replies with a Chat Agent.
- Call a list of numbers: the same pattern for calls.
- Chats and text messages: every text message status.

