This SDK is currently available for preview purposes only. It should not be used in production environments.

Python SDK reference for SMS batches category

Batches are sets of SMS messages. You can send a single message or many. Batches are queued and sent at the rate limit in first-in-first-out order. Any calls to this category will have the form [client].batches.[method].

The methods are described below.

send

Send a message or a batch of messages.

Depending on the length of the body, one message might be split into multiple parts and charged accordingly.

Any groups targeted in a scheduled batch will be evaluated at the time of sending. If a group is deleted between batch creation and scheduled date, it will be considered empty.

Parameter	Type	Description
`body`	string	Required. The message content
`delivery_report`	string	Required. Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.
`to`	list	Required. List of Phone numbers and group IDs that will receive the batch. More information can be found in this article on MSISDN.
`from_`	string	Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.
`parameters`	dictionary	Contains the parameters that will be used for customizing the message for each recipient.
`type_`	string	Regular SMS
`send_at`	string	If set in the future, the message will be delayed until send_at occurs. Must be before expire_at. If set in the past, messages will be sent immediately. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
`expire_at`	string	If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
`callback_url`	string	Override the default callback URL for this batch. Must be a valid URL.
`client_reference`	string	The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
`feedback_enabled`	boolean	If set to `true`, then feedback is expected after successful delivery.
`flash_message`	boolean	Shows message on screen without user interaction while not saving the message to the inbox.
`truncate_concat`	boolean	If set to `true` the message will be shortened when exceeding one part.
`max_number_of_message_parts`	integer	Message will be dispatched only if it is not split to more parts than Max Number of Message Parts
`from_ton`	integer	The type of number for the sender number. Use to override the automatic detection.
`from_npi`	integer	Number Plan Indicator for the sender number. Use to override the automatic detection.

Example:

Copy

Copied

from sinch import Client

sinch_client = Client(key_id="YOUR_key_id", key_secret="YOUR_key_secret",
project_id="YOUR_project_id")

SMS_response = sinch_client.sms.batches.send(
                                        body = "Hello from Sinch!",
                                        to = ["YOUR_to_number"],
                                        from_ = "YOUR_Sinch_number",
                                        delivery_report = "none"
                                    )

print(SMS_response)

list

With the list operation you can list batch messages created in the last 14 days that you have created. This operation supports pagination.

Parameter	Type	Description
`page`	integer	The page number starting from 0.
`page_size`	integer	Determines the size of a page.
`from_`	string	Only list messages sent from this sender number. Multiple originating numbers can be comma separated. Must be phone numbers or short code.
`start_date`	string	Only list messages received at or after this date/time. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
`end_date`	string	Only list messages received before this date/time. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
`client_reference`	string	Client reference to include.

Example:

Copy

Copied

from sinch import Client

sinch_client = Client(key_id="YOUR_key_id", key_secret="YOUR_key_secret",
project_id="YOUR_project_id")

SMS_response = sinch_client.sms.batches.list()

print(SMS_response)

The response to the method is returned in a Paginator object. The Paginator allows you to view and iterate over the pages returned in the response. Usually, the number of pages is determined by a field provided in the method itself. By default, the displayed response will also include the contents of the first page.

In order to iterate over every page in the response, you can use the auto_paging_iter method. For example:

Copy

Copied

for page in response.auto_paging_iter():
    print(page.result)

get

This operation returns a specific batch that matches the provided batch ID.

Parameter	Type	Description
`batch_id`	string	The batch ID you received from sending a message.

Example:

Copy

Copied

from sinch import Client

sinch_client = Client(key_id="YOUR_key_id", key_secret="YOUR_key_secret",
project_id="YOUR_project_id")

SMS_response = sinch_client.sms.batches.get(
                                        batch_id = "YOUR_batch_id"
                                    )

print(SMS_response)

send_dry_run

This operation will perform a dry run of a batch which calculates the bodies and number of parts for all messages in the batch without actually sending any messages.

Parameter	Type	Description
`per_recipient`	boolean	Whether to include per recipient details in the response
`number_of_recipients`	integer	Max number of recipients to include per recipient details for in the response
`body`	string	Required. The message content
`delivery_report`	string	Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.
`to`	list	Required. List of Phone numbers and group IDs that will receive the batch. More information can be found in this article on MSISDN.
`from_`	string	Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.
`parameters`	dictionary	Contains the parameters that will be used for customizing the message for each recipient.
`type_`	string	Regular SMS
`udh`	string	The UDH header of a binary message. Max 140 bytes together with body. Required if `type_` is set to `mt_binary`.
`send_at`	string	If set in the future, the message will be delayed until send_at occurs. Must be before expire_at. If set in the past, messages will be sent immediately. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
`expire_at`	string	If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
`callback_url`	string	Override the default callback URL for this batch. Must be a valid URL.
`client_reference`	string	The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
`flash_message`	boolean	Shows message on screen without user interaction while not saving the message to the inbox.
`max_number_of_message_parts`	integer	Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Example:

Copy

Copied

from sinch import Client

sinch_client = Client(key_id="YOUR_key_id", key_secret="YOUR_key_secret",
project_id="YOUR_project_id")

SMS_response = sinch_client.sms.batches.send_dry_run(
                                        body = "Hello from Sinch!",
                                        to = ["YOUR_to_number"],
                                        from_ = "YOUR_Sinch_number",
                                        delivery_report = "none"
                                    )

print(SMS_response)

cancel

A batch can be canceled at any point. If a batch is canceled while it's currently being delivered some messages currently being processed might still be delivered. The delivery report will indicate which messages were canceled and which weren't.

Canceling a batch scheduled in the future will result in an empty delivery report while canceling an already sent batch would result in no change to the completed delivery report.

Parameter	Type	Description
`batch_id`	string	Required. The batch ID you received from sending a message.

Example:

Copy

Copied

from sinch import Client

sinch_client = Client(key_id="YOUR_key_id", key_secret="YOUR_key_secret",
project_id="YOUR_project_id")

SMS_response = sinch_client.sms.batches.cancel(
                                        batch_id = "YOUR_batch_id"
                                    )

print(SMS_response)

update

This operation updates all specified parameters of a batch that matches the provided batch ID.

Parameter	Type	Description
`batch_id`	string	Required. The batch ID you received from sending a message.
`from_`	dictionary	Sender number. Must be valid phone number, short code or alphanumeric.
`body`	string	The message content. Normal text string for `mt_text` (max 1600 chars) and Base64 encoded for `mt_binary` (max 140 bytes together with udh).
`to_add`	list	List of phone numbers and group IDs to add to the batch.
`to_remove`	list	List of phone numbers and group IDs to remove from the batch.
`delivery_report`	string	Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.
`send_at`	string	If set in the future, the message will be delayed until send_at occurs. Must be before expire_at. If set in the past, messages will be sent immediately. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
`expire_at`	string	If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
`callback_url`	string	Override the default callback URL for this batch. Must be a valid URL.

Example:

Copy

Copied

from sinch import Client

sinch_client = Client(key_id="YOUR_key_id", key_secret="YOUR_key_secret",
project_id="YOUR_project_id")

SMS_response = sinch_client.sms.batches.update(
                                        batch_id = "YOUR_batch_id",
                                        body = "NEW_body_content"
                                    )

print(SMS_response)

replace

This operation will replace all the parameters of a batch with the provided values. It is the same as cancelling a batch and sending a new one instead.

Parameter	Type	Description
`batch_id`	string	Required. The batch ID you received from sending a message.
`body`	string	Required. The message content
`delivery_report`	string	Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.
`to`	list	Required. List of Phone numbers and group IDs that will receive the batch. More information can be found in this article on MSISDN.
`from_`	dictionary	Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.
`parameters`	dictionary	Contains the parameters that will be used for customizing the message for each recipient.
`type_`	string	Regular SMS
`udh`	string	The UDH header of a binary message. Max 140 bytes together with body. Required if `type_` is set to `mt_binary`.
`send_at`	string	If set in the future, the message will be delayed until send_at occurs. Must be before expire_at. If set in the past, messages will be sent immediately. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
`expire_at`	string	If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
`callback_url`	string	Override the default callback URL for this batch. Must be a valid URL.
`client_reference`	string	The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
`flash_message`	boolean	Shows message on screen without user interaction while not saving the message to the inbox.
`max_number_of_message_parts`	integer	Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Example:

Copy

Copied

from sinch import Client

sinch_client = Client(key_id="YOUR_key_id", key_secret="YOUR_key_secret",
project_id="YOUR_project_id")

SMS_response = sinch_client.sms.batches.replace(
                                        batch_id = "YOUR_batch_id",
                                        to = ["YOUR_to_number"],
                                        body = "REPLACEMENT_body_content",
                                        from_ = "YOUR_Sinch_number"
                                    )

print(SMS_response)

send_delivery_feedback

Send feedback if your system can confirm successful message delivery.

Feedback can only be provided if feedback_enabled was set when batch was submitted.

Batches: It is possible to submit feedback multiple times for the same batch for different recipients. Feedback without specified recipients is treated as successful message delivery to all recipients referenced in the batch. Note that the recipients key is still required even if the value is empty.

Groups: If the batch message was creating using a group ID, at least one recipient is required. Excluding recipients (an empty recipient list) does not work and will result in a failed request.

Parameter	Type	Description
`batch_id`	string	Required. The batch ID you received from sending a message.
`recipients`	list	Required. A list of phone numbers (MSISDNs) that have successfully received the message. The key is required, however, the value can be an empty array (`[]`) for a batch. If the feedback was enabled for a group, at least one phone number is required.

Example:

Copy

Copied

from sinch import Client

sinch_client = Client(key_id="YOUR_key_id", key_secret="YOUR_key_secret",
project_id="YOUR_project_id")

SMS_response = sinch_client.sms.batches.send_delivery_feedback(
                                        batch_id = "YOUR_batch_id",
                                        recipients = []
                                    )

print(SMS_response)