Using the REST API

To get started in minutes using our REST API, go to send your first SMS.

Authentication

You will be provided with an authentication token for each service plan.

The token is sent in the Authorization header preceded by Bearer. It is required for all requests made to the REST API.

Example request with token to send a SMS

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "from": "{Number you have on your account}",
          "to": [
              "123456789"
          ],
          "body": "Hi there! How are you?"
      }' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches"

Base URL

The following URLs can be used by the REST API. We have servers in the US and EU. By default, your account will be created in the US environment. If you want access to the European environment, contact your Sinch account manager.

Rate Limits

Each service plan comes with a rate limit which sets the maximum number of messages that can be sent per second. The rate limit is calculated from all messages sent via the API. A batch with 10 recipients will count as 10 messages for rate limiting purposes.

Each service plan gets its own message queue served in First-In-First-Out order. This means that new batches will be accepted immediately but might be delayed if earlier batches are still in the queue.

SMS REST formats and conventions

Let's take a brief look at some of the formats used in the REST API.

JSON

JSON (application/json) is the content type of both requests and responses if not otherwise specified.

Requests with invalid JSON will be rejected.

Null values can be omitted in requests and will be omitted in responses. In some cases, explicitly setting null will overwrite a previously set value with null. See Update a group for an example.

New features might result in additional request and response parameters. New request parameters will either have a default value or be considered optional to retain backwards compatibility. It is highly recommended to ignore any unexpected parameters when reading JSON in API responses and in callback handlers.

Phone numbers (MSISDN)

Only MSISDNs in international format are accepted by the API.

MSISDNs can be sent in with or without a leading + (i.e. +123456789 or 123456789) or with a leading 00. Any space, dash or bracket will also be ignored by the API.

All MSISDNs returned by the REST API will be without a + or 00 prefix, even if they were sent in with one.

Timestamps

Timestamps are used for expressing a moment in time. They are represented using the ISO-8601 standard. Examples of those are the fields send_at and expire_at in the Send a batch message operation.

A time offset can be specified in accordance with ISO-8601 time offsets from UTC. If no time offset is specified (local time in ISO-8601) then UTC will be used.

All timestamps returned by the API will be represented in UTC time, with millisecond precision.

HTTP Status Codes

The REST API returns an HTTP status and code each time a request is made.

HTTP Statuses

The following HTTP status codes are used by the API. Additional codes might be added in the future and if you encounter a code not in this list please consult the HTTP specification for a definition.

HTTP Errors

Responses with status 400 Bad Request and 403 Forbidden will present a JSON object in the body explaining the error. It has the following structure:

Error codes

The following error codes can be returned as values for the code field:

Send SMS Messages

Send a batch message

The following operation will send a batch message.

Depending on the length of the body, one message might be split into multiple parts and charged accordingly. The operation to dry run a batch will return the number of parts for all messages in the batch without actually sending any messages.

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.

Request

POST /xms/v1/{service_plan_id}/batches

JSON body fields:

Send message to one recipient

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "from": "12345",
          "to": [
              "123456789"
          ],
          "body": "Hi there! How are you?"
      }' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches"

Send message to two recipients

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "from": "12345",
          "to": [
              "123456789",
              "987654321"
          ],
          "body": "Hi there! How are you?"
      }' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches"

Response

201 Created

The batch was successfully created. The JSON response object contains the request parameters as well as the following additional parameters:

400 Bad Request

There was an error with your request. The body is a JSON object described in rest_http_errors. Possible error codes include syntax_invalid_json, syntax_invalid_parameter_format and syntax_constraint_violation.

403 Forbidden

The system was not able to fulfill your request. The body is a JSON object described in rest_http_errors. Possible error codes include unknown_group, unknown_campaign and missing_callback_url.

Response for a successfully created batch message.

JSON

{
    "from": "12345",
    "to": [
        "123456789",
        "987654321"
    ],
    "body": "Hi there! How are you?",
    "id": "{batch_id}",
    "created_at": "2014-10-02T09:34:28.542Z",
    "modified_at": "2014-10-02T09:34:28.542Z",
    "canceled": "False"
}

Send scheduled batch message with expiry.

Scheduled batch message

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "from": "12345",
          "to": [
              "123456789",
              "987654321"
          ],
          "body": "Hi there! How are you?",
          "send_at": "2014-10-02T09:30Z",
          "expire_at": "2014-10-02T12:30Z"
      }' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches"

Batch message with custom delivery report URL

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "from": "12345",
          "to": [
              "123456789",
              "987654321"
          ],
          "body": "Hi there! How are you?",
          "delivery_report": "summary",
          "callback_url": "http://www.example.com"
      }' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches"

Parameterized message

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
      "from": "12345",
      "to": [
          "123456789",
          "987654321"
       ],
      "body": "Hi ${name}! How are you?",
      "parameters": {
          "name": {
              "123456789": "Joe",
              "default": "there"
           }
      }
  }' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches"

Cancel batch message

A batch can be canceled at any point. If a batch is canceled while it's 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. Canceling an already sent batch would result in no change to the completed delivery report.

Request

DELETE /xms/v1/{service_plan_id}/batches/{batch_id}

Response

200 OK

The response is a JSON object described in send_batch_msg.

Cancel a batch message

curl-X DELETE \
   -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches/{batch_id}"

List batch messages

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

Batches are returned in reverse chronological order.

Request

GET /xms/v1/{service_plan_id}/batches

Query parameters:

Response

200 OK

Dry run a batch

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.

Request

POST /xms/v1/{service_plan_id}/batches/dry_run

The request body is a JSON object described in send_batch_msg request.

Query parameters:

Response

200 OK

The number of recipients in the batch, the number of messages in the batch and an array containing detail for each recipient:

400 Bad request

There was an error with your request. The body is a JSON object described in rest_http_errors. Possible error codes include syntax_invalid_json, syntax_invalid_parameter_format and syntax_constraint_violation.

Dry run a batch

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
      "from": "12345",
      "to": [
          "123456789",
          "987654321"
       ],
      "body": "Hi ${name}! How are you?",
      "parameters": {
          "name": {
              "123456789": "Joe",
              "default": "there"
           }
      }
  }' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches/dry_run"

Retrieve a batch message

This operation retrieves a specific batch with the provided batch ID.

Request

GET /xms/v1/{service_plan_id}/batches/{batch_id}

Response

200 OK

The response is a JSON object described in send_batch_msg response.

404 Not Found

If the batch ID is unknown to the system.

Retrieve a batch

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches/{batch_id}"

Retrieve the first 30 batches from the last 24 hours

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches"

Retrieve the third page of batches with a page size of 50 from the last 24 hours

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches?page=2&page_size=50"

Retrieve batches created on June 23rd, 2014 UTC

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches?start_date=2014-06-23&end_date=2014-06-24"

Retrieve the batches sent from 12345 or 54321

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches?from=12345,54321"

Update a batch message

This operation will update all provided parameters of a batch for the given batch ID.

Request

POST /xms/v1/{service_plan_id}/batches/{id}

JSON body fields:

Response

200 OK

The response is a JSON object described in send_batch_msg response.

400 Bad request

There was an error with your request. The body is a JSON object described in rest_http_errors. Possible error codes include syntax_invalid_json, syntax_invalid_parameter_format and syntax_constraint_violation.

403 Forbidden

The system was not able to fulfill your request. The body is a JSON object described in rest_http_errors. Possible error codes include batch_already_dispatched.

Update batch

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
      "from": "12345",
      "toAdd": [
          "123456789",
          "987654321"
       ],
      "toRemove": [
          "111111111",
          "999999999"
       ],
      "body": "Hi ${name}! How are you?"

  }' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches/{id}"

Replace a batch

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

Request

PUT /xms/v1/{service_plan_id}/batches/{id}

The request body is a JSON object described in send_batch_msg request.

Response

200 OK

The response is a JSON object described in send_batch_msg response.

400 Bad request

There was an error with your request. The body is a JSON object described in rest_http_errors. Possible error codes include syntax_invalid_json, syntax_invalid_parameter_format and syntax_constraint_violation.

Replace batch

curl -X PUT \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
      "from": "12345",
      "to": [
          "123456789",
          "987654321"
       ],
      "body": "Hi ${name}! How are you?",
      "parameters": {
          "name": {
              "123456789": "Joe",
              "default": "there"
           }
      }
  }' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches/{id}"

Retrieve a delivery report

Delivery reports can be retrieved even if no callback was requested. The difference between a summary and a full report is only that the full report contains the actual MSISDNs for each status code.

Request

GET /xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report

Query parameters:

Response

200 OK

The response is a JSON object with the following fields:

404 Not Found

The batch ID is not known to the system or the delivery report type is not recognized.

Request summary report

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report"

Summary report response

{
    "type": "delivery_report_sms",
    "batch_id": "{batch_id}",
    "total_message_count": 3,
    "statuses": [
        {
            "code": 400,
            "status": "Queued",
            "count": 1
        },
        {
            "code": 0,
            "status": "Delivered",
            "count": 2
        }
    ]
}

Request full report

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report?type=full"

Full report response

{
    "type": "delivery_report_sms",
    "batch_id": "{batch_id}",
    "total_message_count": 3,
    "statuses": [
        {
            "code": 400,
            "status": "Queued",
            "count": 1,
            "recipients": [
                "123456789"
            ]
        },
        {
            "code": 0,
            "status": "Delivered",
            "count": 2,
            "recipients": [
                "987654321",
                "123459876"
            ]
        }
    ]
}

Retrieve a recipient delivery report

A recipient delivery report contains the message status for a single recipient MSISDN.

Request

GET /xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report/{recipient_msisdn}

Request report for 123456789

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report/123456789"

Response

Recipient delivery report for 123456789

{
    "type": "recipient_delivery_report_sms",
    "batch_id": "{batch_id}",
    "recipient": "123456789",
    "code": "0",
    "status": "Delivered",
    "at": "2016-10-02T09:34:18.542Z",
    "operator_status_at": "2016-10-02T09:34:18.101Z"
}

200 OK

The response is a JSON object with the following fields:

404 Not Found

The batch ID is not known to the system or the recipient is not a target of this batch.

Receiving delivery report callbacks

Delivery report callbacks will be received for batches where delivery_report parameter is set to summary, full or per_recipient.

If no callback_url was specified for the batch then the default callback URL for the given service plan will be used.

Summary and full

If a batch was created with a request for full or summary delivery report then one callback will be made to the specified callback URL when all messages in the batch, which may be one message, are either delivered, failed or expired. If you want to know the delivery status for a message before all messages are completed then you can always use retrieve_delivery_report at any time.

The format for summary and full reports is the same as the retrieve_delivery_report response. The difference being that when full is requested a list of phone numbers / recipients per delivery status is provided.

Per recipient

If a batch was created with a request for per_recipient delivery_report then a callback will be made for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

Callbacks

A callback is a HTTP POST request with a notification made by the Sinch SMS REST API to an URI of your choosing. The REST API expects the receiving server to respond with a response code within the 2xx Success range. If no successful response is received, the REST API will either schedule a retry if the error is expected to be temporary or discard the callback if the error seems permanent. The first initial retry will happen 5 seconds after the first try. The next attempt is after 10 seconds, then after 20 seconds, after 40 seconds, after 80 seconds and so on, doubling on every attempt. The last retry will be at 81920 seconds (or 22 hours 45 minutes) after the initial failed attempt.

The REST API offers the following callback options which can be configured for your account upon request to your account manager.

• Callback with mutual authentication over TLS (HTTPS) connection by provisioning the callback URL with client keystore and password.
• Callback with basic authentication by provisioning the callback URL with username and password.
• Callback with OAuth 2.0 by provisioning the callback URL with username, password and the URL to fetch OAuth access token.
• Callback using AWS SNS by provisioning the callback URL with an Access Key ID, Secret Key and Region.

Delivery report callback

A delivery report contains the status and status code for each recipient of a batch. To get a delivery report callback for a message or batch of messages you need to set the delivery_report field accordingly when creating a batch. The formats of the different types of delivery reports are described in Retrieve a delivery report and in Retrieve a recipient delivery report.

The callback URL can either be provided for each batch in the Send a batch message operation or provisioned globally for your account.

Inbound message callback

An inbound message or MO (Mobile Originated) is a message sent to one of your shortcodes or long numbers from a mobile phone. The format of an inbound callback is described in Inbounds Endpoint.

To receive inbound message callbacks, a URL needs to be provisioned for your account. This URL can be specified in the Sinch dashboard.

Message Body

When specifying the message body in the request, the characters used as well as the length of the message affect how many actual SMS messages are sent out. When using parameterization, the length of each message may also vary depending on the recipient-specific data.

Supported Characters

Individual characters used in the message determine the type of encoding that will ultimately be used to send the SMS message. The API automatically detects the encoding required from the characters used, which allows us to support the delivery of SMS in any language.

Basic Character Set

You can send up to 160 characters in a single SMS message if all characters in your message are part of the GSM 7-bit character set:

GSM 7 bit default alphabet and extension table

3GPP TS 23.038 / GSM 03.38

LF is the Line Feed character - for JSON format, provide it as \n
SP is the Space character

Extended Character Set

The following characters are also available, but they are counted as two characters in the SMS message rather than one:

| , ^ , € , { , } , [ , ] , ~ , \

Other Characters

If other characters are required for different languages, 16-bit Unicode (UCS-2) encoding will be used. When using UCS-2 encoding, each character will take 2 bytes, which means up to 70 characters can be sent per UCS-2 encoded SMS message. Here is more information on this topic, including billing implications.

Long Messages

The message body in a request can contain up to 2000 characters. Longer messages will be split and sent as multiple distinct SMS messages. In most cases, those messages will be re-assembled on the handset and displayed to the end-user as a single long message. You can use the tables below to determine the actual number of SMS messages your message will use depending on its length and encoding.

Using only 7-bit Characters

Each SMS in a multi-part 7-bit encoded message, has a maximum length of 153 characters.

Using Unicode Characters

Each SMS in a multi-part Unicode encoded message, has a maximum length of 67 characters.

Parameterization

Parameterization enables you to customize parts of a message for each recipient.

This is done by defining a parameter key and placing it in the message body. For each parameter key, a recipient and parameter value must be provided. The position of a parameter in a message is defined by specifying placeholders in the format ${parameter_key} in the message body, where parameter_key is the name of the parameter to replace with its corresponding value.

For example, the message body Hi ${name}! How are you? contains the parameter name and will be replaced according to the rules specified in the parameters field in the Send a batch message operation.

A default parameter value can be specified that will be used when an MSISDN is not listed for a particular parameter. To set this, identify a recipient as default for each parameter key.

If a target MSISDN is missing in the parameters object and no default value has been defined for that parameter, the message will fail for that MSISDN but not for other recipients.

Parameter keys are case sensitive.

Delivery Reports

The REST API uses message statuses and error codes in delivery reports, which refer to the state of the SMS batch and can be present in either Retrieve a delivery report or sent to a callback.

This section describes the statuses and codes returned in those delivery reports.

Delivery Report Statuses

The status field describes which state a particular message is in. Note that statuses of type Intermediate will only be reported if you request a status per recipient (Retrieve a recipient delivery report), no callback will be made to report them.

The following statuses are available when using the REST API:

Delivery Report Error Codes

The delivery report status code provides a more detailed view of what happened with a message. The REST API shares most of its error codes with other SMS services.

These are defined here.

In addition to these standard error codes, the REST API provides an additional set of error codes, all within the 4xx range (vendor specific errors in the range of 0x400 to 0x4FF as referenced in the SMPP specification). These are listed below:

Note

New error codes may be added over time.

Inbounds Endpoint

Inbounds, or Mobile Originated messages, are incoming messages. Inbound messages can be listed and retrieved like batch messages and they can also be delivered by callback requests like delivery reports.

NB: The operator is only available for MOs sent to short codes.

Mobile Originating Callback Report

{
    "id":"{batch_id}",
    "from":"123456789","to":"12345",
    "body":"Help",
    "type":"mo_text",
    "received_at":"2016-07-19T13:09:02.972Z" 
    }

List inbound messages

Retrieve the first 30 inbound messages from the last 24 hours.

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/inbounds"

Retrieve the third page of inbound messages with a page size of 50 from the last 24 hours

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/inbounds?page=2&page_size=50"

Retrieve inbound messages received on June 23rd, 2014 UTC

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/inbounds?start_date=20140623TZ&end_date=20140624TZ"

Retrieve the batches sent to 12345 or 54321

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/inbounds?to=12345,54321"

With the list operation, you can list all inbound messages that you have received. This operation supports pagination.

Inbounds are returned in reverse chronological order.

Request

GET /xms/v1/{service_plan_id}/inbounds

Query parameters:

Response

200 OK

Retrieve inbound message

This operation retrieves a specific inbound message with the provided inbound ID.

Request

GET /xms/v1/{service_plan_id}/inbounds/{inbound_id}

Response

200 OK

The response is a JSON object described in inbounds_endpoint response.

404 Not Found

If the inbound ID is unknown to the system

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/inbounds/{inbound_id}"

Groups endpoint

A group is a set of MSISDNs that can be used as a target in the send_batch_msg operation. An MSISDN can only occur once in a group and any attempts to add a duplicate would be ignored but not rejected.

Create a group

Request

POST /xms/v1/{service_plan_id}/groups

JSON object parameters:

Response

201 Created

The response body is a JSON object with the following
parameters:

400 Bad Request

There was an error with your request. The body is a JSON object described in rest_http_errors. Possible error codes include syntax_invalid_json, syntax_invalid_parameter_format and syntax_constraint_violation.

403 Forbidden

The system was not able to fulfill your request. The body is a JSON object described in rest_http_errors. Possible error codes include conflict_group_name.

Create a group named My group with two members.

Create Group

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "members": [
              "123456789",
              "987654321"
          ],
          "name": "My group"
}' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups"

Create auto update group for members sending MOs to `443456789012`: keyword JOIN will add them to the group, keyword STOP will remove them from the group.

Create Auto Update Group

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "name": "My auto group",
          "auto_update": {
                "to": "443456789012",
                    "add": {
                        "first_word": "join"
                    },
                    "remove": {
                        "first_word": "stop"
                    }
                }
}' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups"

Create an auto update group for shared short code 54321 with keyword SINCH: if followed by JOIN will add them to the group, if followed by LEAVE will remove them from the group. Note that keywords are not case sensitive so Sinch , SInCh , SINCH and other permutations will all be treated the same.

Create Auto Update Group For Shared Short Code

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "name": "My auto group 2",
          "auto_update": {
                "to": "54321",
                    "add": {
                        "first_word": "Sinch",
                        "second_word": "Join"
                    },
                    "remove": {
                        "first_word": "SINCH",
                        "second_word": "leave"
                    }
                }
}' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups"

Create a parent group that includes all members of groups with ID dxCJTlfb1UsF and yiinTKVNAEAu.

Create Parent Group

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "name": "My groups collection",
          "child_groups": [
                "dxCJTlfb1UsF",
                "yiinTKVNAEAu"
          ]
}' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups"

List groups

With the list operation you can list all groups that you have created. This operation supports pagination.

Groups are returned in reverse chronological order.

Request

GET /xms/v1/{service_plan_id}/groups

Query parameters:

Response

200 OK

Retrieve the first 30 groups

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups"

Retrieve the third page of groups with a page size of 50

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups?page=3&page_size=50"

Retrieve a group

This operation retrieves a specific group with the provided group ID.

Request

GET /xms/v1/{service_plan_id}/groups/{group_id}

Response

200 OK

The response is a JSON object described in create_group response.

404 Not Found

If the group ID is unknown to the system.

Retrieve a group

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups/{group_id}"

Retrieve the members of a group

This operation retrieves the members of the group with the provided group ID.

Request

GET /xms/v1/{service_plan_id}/groups/{group_id}/members

Response

200 OK

The response is a JSON array with MSISDNs.

404 Not Found

If the group ID is unknown to the system.

Retrieve group members

curl -H "Authorization: Bearer {token}" \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups/{group_id}/members"

Update a group

With the update group operation, you can add and remove members to an existing group as well as rename the group.

The request will not be rejected for duplicate adds or unknown removes.

The adds will be done before the deletes so if an MSISDN is in both lists, then it will not be part of the resulting group.

To remove an existing name, set name explicitly to the JSON value null. Omitting name from the JSON body will leave the name unchanged.

Updating a group targeted by a batch message scheduled in the future is allowed and changes will be reflected until the batch is sent.

Request

POST /xms/v1/{service_plan_id}/groups/{group_id}

The request is a JSON object with the following fields:

Response

200 OK

The response is a JSON object described in create_group response.

400 Bad Request

There was an error with your request. The body is a JSON object described in rest_http_errors. Possible error codes include syntax_invalid_json, syntax_invalid_parameter_format and syntax_constraint_violation.

403 Forbidden

One or more groups referenced in your request could not be found.

404 Not Found

If the group ID is unknown to the system.

Update a group by adding two new members and removing one existing

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "add": [
              "123456789",
              "987654321"
          ],
          "remove": [
              "432156789"
          ]
}' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups/{group_id}"

Rename a group without changing its members

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "name": "New group name"
}' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups/{group_id}"

Remove the current name of a group without changing its members

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "name": null
}' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups/{group_id}"

Replace a group

The replace operation will replace all parameters, including members, of an existing group with new values.

Replacing a group targeted by a batch message scheduled in the future is allowed and changes will be reflected when the batch is sent.

Request

PUT /xms/v1/{service_plan_id}/groups/{group_id}

JSON object
parameters:

Response

200 OK

The response is a JSON object described in create_group response.

400 Bad Request

There was an error with your request. The body is a JSON object described in rest_http_errors. Possible error codes include syntax_invalid_json, syntax_invalid_parameter_format and syntax_constraint_violation.

403 Forbidden

The system was not able to fulfill your request. The body is a JSON object described in rest_http_errors. Possible error codes include conflict_group_name.

404 Not Found

If the group ID is unknown to the system.

Replace a group

curl -X PUT \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json"  -d '
      {
          "members": [
              "123456789",
              "987654321"
          ],
      "name": "New name"
}' \
  "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups/{group_id}"

Delete a group

Deletes a group from the system. Any message created for a deleted group will be rejected. If a group is deleted that's part of the to-array of a message scheduled for the future, then the group will be considered empty at the time of sending.

Request

DELETE /xms/v1/{service_plan_id}/groups/{group_id}

Response

200 OK

The group was successfully deleted.

404 Not Found

If the group ID is unknown to the system.

Delete a group

curl -X DELETE \
     -H "Authorization: Bearer {token}" \
     "https://us.sms.api.sinch.com/xms/v1/{service_plan_id}/groups/{group_id}"

Automatic Default Originator

Default originator pool of an account is the set of originators for different countries configured by the account manager. If requested, it will be used when a batch message has no originator specified (missing "from" parameter).

For each MSISDN, the originator will be auto selected from its default originator pool based on the country/region of the MSISDN when submitting a batch with missing originator as in send_batch_msg operation, if a default originator pool configured for your account. A batch with multiple recipients of different countries can get different originators based on the configured originator pool of that account.

If no default originator exists for the target MSISDN, then the message will be failed only for that MSISDN and not for the rest of the batch.

Limiting Message Parts

With max number of message parts you can specify whether the message should be dispatched. If a message is split into more parts than max_number_of_message_parts then it will not be delivered and the status code will be 411.

A default max_number_of_message_parts can be configured at the account level by your account manager. If the max_number_of_message_parts parameter is specified when creating a batch, it will override the default value configured by your account manager.

When max_number_of_message_parts parameter is set or the default value is configured, number_of_message_parts parameter will be included in recipient delivery report.

URL Link Previews

Some mobile devices are capable of displaying previews for links contained in SMS or MMS messages. When messages that contain a URL are received on these devices, they may be rendered in the messaging application with a preview of the linked page. This behavior is controlled from the phone or its software, and can not be affected by Sinch or the carrier.

Behaviour on iOS

There are multiple factors that affect whether an iPhone shows a preview for a link received in a message, and what the preview looks like.

Is the sender saved in the recipient's contacts list?

According to our testing, iOS will only render a preview for links sent in SMS or MMS if the sender is saved in the recipient's contact list. Otherwise, the URL will be displayed in the body of the message.

Is the URL at the very beginning or the very end of the message?

iPhones will only display a link preview if the URL is at the beginning or the end of the message. iOS will not render a preview for a URL in the middle of a message, or even just surrounded by periods or quotation marks.

Behavior on Android

Depending on the device but, if the recipient has Google's Messages app or Samsung you should be able to see previews if the phone has been updated after June 2018.

Edit on GitHub