Sending and managing messages

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

This article details commonly used API operations. Each section corresponds to an operation and includes a brief overview, a sample request and response payload, and schema information pulled directly from the API reference. Additionally, each section will include links to the corresponding API reference entry and any tutorials (if available).

The SMS REST API enables users to send, retreive, update and delete messages to one or more recipient(s) using batches. In simple terms, a batch consists of the message you want to send, your Sinch mobile number, and a list of recipients. With batches, you can do everything from appointment scheduling to marketing campaigns.

Sending a message

This endpoint enables you to send messages. As well as sending messages to multiple recipients, it allows users to schedule messages and even set an expiry date. This is useful for applications which require messages to be sent at particular times, such as appointment scheduling or marketing campaigns.

Send message request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

curl -i -X POST \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "YOUR_Sinch_virtual_number",
    "to": [
      "YOUR_recipient_number"
    ],
    "body": "YOUR_message_body",
    "type": "mt_text"
  }'

For all possible request body schemas that correspond to this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

For all possible response schemas that correspond to this API call, see the corresponding entry in the API reference.

Performing a dry run for a batch of recipients

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. If you are a new Sinch user, the Dry Run operation is perfect for testing how to send a message as it incurrs no costs. For existing users, the Dry Run operation is very useful for testing SMS marketing campaigns designed to engage high volumes of users and making sure there are no errors.

Dry run request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

curl -i -X POST \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/dry_run?per_recipient=true&number_of_recipients=500' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "YOUR_virtual_number",
    "to": [
      "YOUR_numbers_sending_to",
      "another_number"
    ],
    "body": "YOUR body text here",
    "parameters": {
      "name": {
        "Phone_number_of_recipient": "recipient_name",
        "default": "default_in_place_of_name"
      }
    }
  }'

For all possible request body schemas that correspond to this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference.

Retrieving a list of batches

The list operation enables you to list batch messages that you have created in the last 14 days. This operation is highly customizable. Users can filter results by date range and from number. If there is a high volume of batches, results can be paginated. Pagination is flexible, with the page and page_size query parameters enabling users to set the number of pages and the number of results per page.

Retrieve a list of batches request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

curl -i -X GET \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches?page=2&page_size=50&start_date=2019-08-24T14%3A15%3A22Z&end_date=2019-08-24T14%3A15%3A22Z&from=44345%2C45607&client_reference=myReference' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

For the full schema of this API call, see the corresponding entry.

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference.

Retrieving a message

This operation enables users to retrieve a message they created, by returning a specific batch that matches the batch_id provided in the path parameters. This is useful if you want to review messages to check for mistakes.

Retrieve a message request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

curl -i -X GET \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/01FC66621XXXXX119Z8PMV1QPQ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

For the full schema of this API call, see the corresponding entry.

For all possible response schemas that correspond to this API call, see the corresponding entry in the API reference.

Update a batch message

The upate operation works by updating all specified parameters of a batch that matches the batch_id provided in the path parameters. This gives users plenty of flexibility, they can change everything from the recipients and groups the message gets sent to, to the type of delivery report. This means users can tweak campaigns they have scheduled in response to new requirements.

Update a batch message request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

curl -i -X POST \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/01FC66621XXXXX119Z8PMV1QPQ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "to_remove": [
      "YOUR_numbers",
      "to_remove",
      "as_strings_in_array",
      "with_country_code",
      "16267890123"
    ],
    "to_add": [
      "YOUR_numbers",
      "to_add"
    ]
  }'

For all possible request body schemas that correspond to this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

For all possible response schemas that correspond to this API call, see the corresponding entry in the API reference.

Replace a message batch

This operation enables a users to replace a batch wholesale. It works by replacing all the parameters of a batch with the provided values. It is the same as cancelling a batch and sending a new one instead. This is useful in situations where simply modifying an existing batch isn't enough.

Replace a message batch request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

curl -i -X PUT \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/01FC66621XXXXX119Z8PMV1QPQ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": [
      15551231234,
      15551256344
    ],
    "body": "Hi ${name}! How are you?"
  }'

For all possible request body schemas that correspond to this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

For all possible response schemas that correspond to this API call, see the corresponding entry in the API reference.

Cancel a batch message

This endpoint allows users to cancel a batch by batch_id provided in the path parameters. This enables a message to be cancelled before all the intended recipients receive it.

Cancel a batch request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

curl -i -X DELETE \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/01FC66621XXXXX119Z8PMV1QPQ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

For the full schema of the request that corresponds to this API call, see the corresponding entry in the API reference.

For all possible response schemas that correspond to this API call, see the corresponding entry in the API reference.

Send delivery feedback for a message

When a parameter called feedback_enabled is set in a send batch message call, the SMS API can provide feedback on whether the message was delivered successfully using this send delivery feedback API call. By providing the batch_id in the path parameter of this operation, users can get delivery feedback for the recipients in the corresponding batch. This is useful in for any user that needs to confirm that their messages are being received. For example, if you're running a marketing campaign, it's essential to have some measure of how successful it was.

Send delivery feedback request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

curl -i -X POST \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/01FC66621XXXXX119Z8PMV1QPQ/delivery_feedback \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipients": [
      "+15551231234",
      "+15551256344"
    ]
  }'

For the full schema of the request that corresponds to this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

Response 202 if successful.