Broadcast

Send the same SMS or MMS message to up to 50,000 recipients in a single API call.

Endpoint

POST /api/v1/messaging/broadcast

Request body

Field	Type	Required	Description
`recipients`	array	Yes	List of recipient objects. Min 100, max 50,000. Each phone number must be unique.
`recipients[].to`	string	Yes	Recipient phone number in E.164 format
`from`	string	Yes	Sender phone number in E.164 format. Must be active and assigned to your account.
`body`	string	Conditional	Message text, up to 640 characters. Required for SMS.
`mediaUrl`	string	No	Publicly accessible media URL. When provided, the broadcast is sent as MMS.
`idempotencyKey`	string	No	Unique key to prevent duplicate broadcasts on retries.

Example

curl -X POST https://platform.textingline.com/api/v1/messaging/broadcast \
  -u "your_key_id:your_key_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {"to": "+18005551001"},
      {"to": "+18005551002"},
      {"to": "+18005551003"}
    ],
    "from": "+18005559876",
    "body": "Flash sale! 20% off all items today only. Reply STOP to opt out."
  }'

Response

{
  "id": "brc_DsAdb4EBYBh3z25sBA1qnv",
  "from": "+18005559876",
  "body": "Flash sale! 20% off all items today only. Reply STOP to opt out.",
  "totalRecipients": 3,
  "status": "queued",
  "createdAt": "2026-03-13T14:30:00.000Z"
}

The broadcast is queued as a background job. The response includes the total recipient count and an initial status of queued.

Duplicate recipients

The recipients array must not contain duplicate phone numbers. If duplicates are found, the request is rejected with error code 33024:

{
  "code": 33024,
  "message": "recipients must not contain duplicate phone numbers",
  "status": 400,
  "moreInfo": "https://docs.smsfactory.com/docs/error-codes"
}

Deduplicate your recipient list before submitting the request.

Credits

Credits are charged per recipient:

SMS broadcast: 2 credits per recipient (1 message + 1 carrier lookup if needed)
MMS broadcast: 1 SMS credits + 1 SMS credit per recipient (1 message + 1 carrier lookup if needed)

For a 10,000-recipient SMS broadcast, you'd need 20,000 SMS credits.

Rate limits

The broadcast endpoint allows 5 requests per 60-second window. See Rate Limits for details.

Common errors

Code	Description
`33024`	Duplicate recipients in the request
`33004`	The `from` number is not assigned to your account
`33012`	Daily messaging quota reached
`33023`	Insufficient credits

See Error Codes for the full reference.