Send SMS Batch

About

This API method allows you to programmatically send or schedule a batch of SMS messages. Each SMS may be sent to any destination and can be sent using an E164, alphanumeric or "leased" sender ID.

Your account and property must be enabled for SMS. Please contact client services to have SMS enabled.

Alphanumeric Sender IDs

Alphanumeric sender IDs are supported in many regions, notably excluding US and Canada. If a recipient operator does not support alphanumeric sender IDs, a leased sender ID will be applied. The following rules apply for alphanumeric sender IDs:

• Length between 1 and 11 characters
• Valid characters include A-Z, a-z, 0-9 and spaces
• Must include at least one letter

Leased Sender IDs

Leased sender IDs are automatically assigned sender IDs that are unique to the recipient and that are valid for 30 days. Leased sender IDs allow you to specify response options on a per message basis, such as forwarding responses to a mobile or email or forwarding responses and delivery receipts to a webhook URI.

Note that you may only have 5 leases to a specific recipient at any one time.

Resource URI

SMS messages are sent using the following call.

POST
/v2/Properties/[PropertySid]/BatchMessages

Request

URI Parameters

Parameter	Type	Description
PropertySid	string	The secure identifier of the property from which to send the SMS.

Resource Parameters

This request only supports JSON formatted parameters. The batch of messages to be sent is specified as an array of individual messages:

Example: Sending a batch of simple SMS messages.

{
	"Messages": [
		{
			"From": "+61499009990",
			"To": "+61488023555",
			"Text": "You win again, gravity!"
		},
		{
			"From": "+61499009991",
			"To": "+61488023556",
			"Text": "You call that an antenna?"
		}
	]
}

For each individual message included in the batch, the following properties are available:

Required message properties

Parameter	Type	Description
From	string	The sender ID. This can be a mobile phone number in E164 format (including + prefix), an alphanumeric string, or blank or omitted to send from a leased number.
To	string	The recipient of the SMS message in E164 format (including + prefix).
Text	string	The content of the SMS message.

Optional message properties

Parameter	Type	Description
Schedule	integer	The UTC time in seconds since Unix Epoch to send the message. This can be at most 14 days in the future. If the value is in the past, the request will fail, unless the value is less than 1 hour in the past, in which case the request will succeed and the message will be sent immediately.
DeliveryReceipt	boolean	Whether to request a delivery receipt. Valid options are: true – request a delivery receipt (default) false – do not request a delivery receipt
DeliveryReceiptWebhookUri	string	The callback URI to invoke when a delivery receipt is received. Note that DeliveryReceipt must be set to true for this to be triggered.
DeliveryReceiptWebhookMethod	string	The method to use for delivery receipt callbacks. Valid options are POST and GET. Default is POST.

Lease-Specific Optional message properties

The following optional parameters may be used when sending from a leased number (when From is blank or unspecified). When a response to the sent message is received, the following parameters define how the response is treated.

Parameter	Type	Description
ForwardToSms	string	When a response is received, forward it to this number in E164 format.
ForwardFromSms	string	When forwarding via SMS, send from this E164 formatted number or alphanumeric sender ID. By default the sender ID will be the sender ID of the responding party.
ForwardToEmail	string	When a response is received, forward it over email to this email address.
ForwardFromEmail	string	When forwarding via email, send from this email address. By default this is a "no reply" email address.
WebhookUri	string	The callback URI to invoke when a response is received.
WebhookMethod	string	The method to use for response callbacks. Valid options are POST and GET. Default is POST.
ExternalId	string	User-defined arbitrary id which is attached to the message and can be retrieved later.

Example: Sending a batch of SMS messages from a lease with all properties specified.

{
	"Messages": [
		{
			"From": "",
			"To": "+61488023555",
			"Text": "You call that an antenna?",
			"Schedule": 1321009871,
			"DeliveryReceipt": true,
			"DeliveryReceiptWebhookUri": "https://callback.2.me/for/delivery_receipt",
			"DeliveryReceiptWebhookMethod": "POST",
			"ForwardToSms": "+61499333222",
			"ForwardFromSms": "",
			"ForwardToEmail": "[email protected]",
			"ForwardFromEmail": "[email protected]",
			"WebhookUri": "https://callback.2.me/for/sms_responses",
			"WebhookMethod": "POST",
			"ExternalId": "test123"
		},
		{
			"From": "",
			"To": "+61488023556",
			"Text": "You win again, gravity!",
			"Schedule": 1321009871,
			"DeliveryReceipt": true,
			"DeliveryReceiptWebhookUri": "https://callback.2.me/for/delivery_receipt",
			"DeliveryReceiptWebhookMethod": "POST",
			"ForwardToSms": "+61499333222",
			"ForwardFromSms": "",
			"ForwardToEmail": "[email protected]",
			"ForwardFromEmail": "[email protected]",
			"WebhookUri": "https://callback.2.me/for/sms_responses",
			"WebhookMethod": "POST",
			"ExternalId": "test456"
		}
	]
}

Response

200 – OK

On successful acknowledgment of the SMS message batch, a 200 OK is returned with a JSON-formatted array of response objects, one per message. If the message has been processed successfully, the response object is a JSON formatted message resource.

If the message has not been processed successfully, the response object contains an error code and a descriptive error message.

Please note that the response code is related to the processing of the message batch as a whole, not individual messages. This means that if some or all messages of the batch fail, the processing of the batch is still deemed successful if all messages have been processed.

Message Resource Parameters

Parameter	Type	Description
MessageSid	string	The message secure identifier which uniquely identifies this message.
AccountSid	string	The account secure identifier associated with the message.
PropertySid	string	The property secure identifier associated with the message.
From	string	The alphanumeric or E164 formatted sender ID of the message. If the message was sent using a leased sender ID, this field will be populated with the actual E164 sender ID that was allocated to the SMS message.
To	string	The E164 formatted recipient of the SMS message.
Text	string	The content of the SMS message.

Example: An example response where the first message was processed successfully and the second message failed validation.

[
	{
		"MessageSid": "M87DMNHSDJHSD48DMNSDS6VJCNKD9MD0",
		"AccountSid": "AG5T3HFR5ASD54FS5GB3SDAFJAKSH6DS",
		"PropertySid": "S7DNJ9KJDS0MDS23DKS9QMZ8DKJSD9KL",
		"From": "+6199111222",
		"To": "+61488023555",
		"Text": "You call that an antenna?",
		"DeliveryReceipt": true,
		"NumSegments": 0,
		"Status": "Processing",
		"Direction": "Transmit",
		"Created": 1506568010,
		"ErrorCode": "",
		"ExternalId": "testid123"
	},
	{
		"ErrorCode": "INVALID_PHONENUMBER_FORMAT",
		"Message": "To parameter is not in E.164 format",
		"Errors": [
			{
				"FieldName": "To"
			}
		]
	}
]

If the batch request failed as a whole, the response only contains information about the request as a whole.

Example: An example response where the request as a whole failed.

{
	"ResponseStatus": {
		"ErrorCode": "FormatException",
		"Message": "Invalid length for a Base-64 char array or string."
	}
}

400 - Error

For error codes and messages, please refer to the REST API Error Codes page.