# API Overview | Sinch Sinch SMS API is one of the easiest APIs we offer and enables you to add fast and reliable global SMS to your applications. Send single messages, scheduled batch messages, use available message templates and more. Version: v1 License: MIT ## Servers Global API ``` https://{region}.sms.api.sinch.com ``` Variables: - `region` Default: "us" Enum: "us", "eu", "au", "br", "ca" ## Security ### BearerAuth Your API token is sent in the `Authorization` header preceded by `Bearer`. You'll have an API token per `service_plan_id`. Both can be found in the [Sinch Customer Dashboard](https://dashboard.sinch.com/sms/api/rest). Double check that you're using the correct region in your base URL. Type: http Scheme: bearer ## Download OpenAPI description [API Overview | Sinch](https://developers.sinch.com/_spec/docs/sms/api-reference/sms.yaml) ## Delivery reports The REST API uses message statuses and error codes in delivery reports, which refer to the state of the batch and can be present in either [Retrieve a delivery report](/docs/sms/api-reference/sms/delivery-reports/getdeliveryreportbybatchid) or sent as a callback. ## 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 of `per_recipient` ([Retrieve a recipient delivery report](/docs/sms/api-reference/sms/delivery-reports/getdeliveryreportbyphonenumber)). The following statuses are available when using the SMS REST API: | Status | Type | Description | | ------------ | ------------ | --------------------------------------------- | | `Queued` | Intermediate | Message is queued within REST API system and will be dispatched according to the rate of the account. | | `Dispatched` | Intermediate | Message has been dispatched and accepted for delivery by the SMSC. Note that, in certain scenarios, the `Dispatched` status may be skipped if a more `Final` status is reached prior to sending the delivery report. For example, if a delivery report is not sent prior to the corresponding message's successful delivery, you may only get a delivery report with a `Delivered` status.| | `Aborted` | Final | Message was aborted before reaching the SMSC. | | `Cancelled` | Final | Message was cancelled by user before reaching SMSC. | | `Rejected` | Final | Message was rejected by the SMSC. | | `Deleted` | Final | Message has been deleted. Message was deleted by a remote SMSC. This may happen if the destination is an invalid MSISDN or opted out subscriber. | | `Delivered` | Final | Message has been delivered. | | `Failed` | Final | Message failed to be delivered. | | `Expired` | Final | Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short. | | `Unknown` | Final | Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received. | ## Delivery report error codes The delivery report status code provides a more detailed view of what happened with a message. The REST API error codes are a combination of [SMPP error codes](/docs/sms/smpp/error-codes/#status-reports-error-codes), [MMS error codes](/docs/mms/7-service/mms-status-codes/) and custom codes. The REST API custom error codes are all within the 4xx range. These are listed below: | Status Code | Name | Status | Description | | ----------------- | ---------------------------- | ------------ | --------------------------------------------------------- | | 400 | Queued | `Queued` | Message is queued within REST API system and will be dispatched according to the rate of the account. | | 401 | Dispatched | `Dispatched` | Message has been dispatched to SMSC. | | 402 | Message unroutable | `Aborted` | SMSC rejected message. Retrying is likely to cause the same error. | | 403 | Internal error | `Aborted` | An unexpected error caused the message to fail. | | 404 | Temporary delivery failure | `Aborted` | Message failed because of temporary delivery failure. Message can be retried. | | 405 | Unmatched Parameter | `Aborted` | One or more parameters in the message body has no mapping for this recipient. See [Message Parameterization](../../../../resources/message-info/message-parameterization/) | | 406 | Internal Expiry | `Aborted` | Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short. | | 407 | Cancelled | `Cancelled` | Message was cancelled by user before reaching SMSC. | | 408 | Internal Reject | `Aborted` | SMSC rejected the message. Retrying is likely to cause the same error. | | 410 | Unmatched default originator | `Aborted` | No default originator exists/configured for this recipient when sending message without originator. | | 411 | Exceeded parts limit | `Aborted` | Message failed as the number of message parts exceeds the defined max number of message parts. | | 412 | Unprovisioned region | `Aborted` | SMSC rejected the message. The account hasn't been provisioned for this region. | | 413 | Blocked | `Aborted` | The account is blocked. Reach out to support for help. Potentially out of credits. | | 414 | Bad Media | `Aborted` | MMS only, the request failed due to a bad media URL. It is possible that the URL was unreachable, or sent a bad response. | | 415 | Delivery report Rejected | `Failed` | MMS only, message reached MMSC but was rejected by MMS gateway or mobile network. | | 416 | Delivery report Not Supported| `Failed` | MMS only, message reached MMSC but it is not supported. | | 417 | Delivery report Unreachable | `Failed` | MMS only, message reached MMSC but the destination network or the mobile subscriber cannot be reached. | | 418 | Delivery report Unrecognized | `Failed` | MMS only, message reached MMSC but the handset of the mobile subscriber does not recognize the message content. | ### Retrieve a list of delivery reports - [GET /xms/v1/{service_plan_id}/delivery_reports](https://developers.sinch.com/docs/sms/api-reference/sms/delivery-reports/getdeliveryreports.md): Get a list of finished delivery reports. This operation supports pagination. ### Retrieve a delivery report - [GET /xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report](https://developers.sinch.com/docs/sms/api-reference/sms/delivery-reports/getdeliveryreportbybatchid.md): 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 phone numbers in E.164 format for each status code. ### Retrieve a recipient delivery report - [GET /xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report/{recipient_msisdn}](https://developers.sinch.com/docs/sms/api-reference/sms/delivery-reports/getdeliveryreportbyphonenumber.md): A recipient delivery report contains the message status for a single recipient phone number. ### Delivery Report - [POST deliveryReport](https://developers.sinch.com/docs/sms/api-reference/sms/delivery-reports/deliveryreport.md): 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, set the field accordingly when creating a batch. The following is provided so you can better understand our webhooks/callbacks. Configuration of both webhooks and the type of delivery report requested happens when sending a batch. #### Callback URL The callback URL can either be provided for each batch or provisioned globally for your account in your Sinch Customer Dashboard. Learn how to configure a webhook/callback here. #### Type The is the type of delivery report webhook. The response will vary depending on the webhook delivery report you selected when the batch was sent, so choose the appropriate selection under "One of". - The and types are documented under Delivery report. These are reports containing either a full report or summary report, depending on your selection at the time the batch was sent. - The and delivery report types are documented under Recipient delivery report. These are delivery reports for recipient phone numbers. If you set for the parameter when sending the batch, a recipient report gets sent to you for each status change for each recipient in your batch. If you set , a recipient report gets sent to you for the final status of each recipient in your batch. ### Delivery Report - [POST deliveryReport](https://developers.sinch.com/docs/sms/api-reference/sms/webhooks/deliveryreport.md): 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, set the field accordingly when creating a batch. The following is provided so you can better understand our webhooks/callbacks. Configuration of both webhooks and the type of delivery report requested happens when sending a batch. #### Callback URL The callback URL can either be provided for each batch or provisioned globally for your account in your Sinch Customer Dashboard. Learn how to configure a webhook/callback here. #### Type The is the type of delivery report webhook. The response will vary depending on the webhook delivery report you selected when the batch was sent, so choose the appropriate selection under "One of". - The and types are documented under Delivery report. These are reports containing either a full report or summary report, depending on your selection at the time the batch was sent. - The and delivery report types are documented under Recipient delivery report. These are delivery reports for recipient phone numbers. If you set for the parameter when sending the batch, a recipient report gets sent to you for each status change for each recipient in your batch. If you set , a recipient report gets sent to you for the final status of each recipient in your batch. ## Webhooks ## Callbacks A callback is an HTTP POST request with a notification made by the Sinch SMS REST API to a URI of your choosing. The REST API expects the receiving server to respond with a response code within the `2xx` success range. For `5xx` the callback will be retried. For `429` the callback will be retried and the throughput will be lowered. For other status codes in the `4xx` range the callback will not be retried. 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, doubling on every attempt. The last retry will be at 81920 seconds (or 22 hours 45 minutes) after the initial failed attempt. Note that, with these callbacks, the Sinch SMS REST API will make a request to the URI of your choosing. This means that Sinch will be authenticating against **your system**. By making a request to your account manager, SMS REST API callbacks may be configured with the following options: - **Basic authentication** is the simplest form of authentication. It enables access to the SMS API via a username and password. Basic Auth can be utilised in a callback by provisioning the callback URL with the appropriate username and password. Note that, because callbacks are made by Sinch to a URI of your choosing (rather than a call made by your system to Sinch's endpoints), the username and password must be accepted by **your system**. - **OAuth 2.0** is a standard form of authentication that provides enhanced security when compared to Basic Authentication. It uses access tokens to reduce the risk of credentials being intercepted. OAuth 2.0 can be utilised in a callback by provisioning the callback URL with username, password, response, scope, and the URL to fetch OAuth access token. Note that, because callbacks are made by Sinch to a URI of your choosing (rather than a call made by your system to Sinch's endpoints), the username, password, response, scope, and access token URL must be accepted by **your system**. - **HMAC** Hash-based message authentication code (HMAC) is a cryptographic authentication technique that uses a hash function and a secret key. HMAC can also be configured alongside Basic Auth and OAuth. HMAC authentication can be assigned to a specific URL or an entire Service Plan. In either case, reach out to your account manager to configure HMAC authentication. - **AWS SNS** is a managed service that provides message delivery from publishers to subscribers by routing messages through SNS topics. Users can utilise AWS SNS in a callback by provisioning the callback URL with an Access Key ID, Secret Key and Region. Additionally, the SMS REST API supports customized headers in callbacks. Reach out to your account manager to configure customized callback headers.Your account manager will be able to configure callbacks associated with your account so that they include the header and value pairs you provide. ### Delivery Report - [POST deliveryReport](https://developers.sinch.com/docs/sms/api-reference/sms/delivery-reports/deliveryreport.md): 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, set the field accordingly when creating a batch. The following is provided so you can better understand our webhooks/callbacks. Configuration of both webhooks and the type of delivery report requested happens when sending a batch. #### Callback URL The callback URL can either be provided for each batch or provisioned globally for your account in your Sinch Customer Dashboard. Learn how to configure a webhook/callback here. #### Type The is the type of delivery report webhook. The response will vary depending on the webhook delivery report you selected when the batch was sent, so choose the appropriate selection under "One of". - The and types are documented under Delivery report. These are reports containing either a full report or summary report, depending on your selection at the time the batch was sent. - The and delivery report types are documented under Recipient delivery report. These are delivery reports for recipient phone numbers. If you set for the parameter when sending the batch, a recipient report gets sent to you for each status change for each recipient in your batch. If you set , a recipient report gets sent to you for the final status of each recipient in your batch. ### Incoming SMS - [POST incomingSMS](https://developers.sinch.com/docs/sms/api-reference/sms/inbounds/incomingsms.md): An inbound message is a message sent to one of your short codes or long numbers from a mobile phone. To receive inbound message callbacks, a URL needs to be added to your REST API. This URL can be specified in your Dashboard. ### Incoming SMS - [POST incomingSMS](https://developers.sinch.com/docs/sms/api-reference/sms/webhooks/incomingsms.md): An inbound message is a message sent to one of your short codes or long numbers from a mobile phone. To receive inbound message callbacks, a URL needs to be added to your REST API. This URL can be specified in your Dashboard. ### Delivery Report - [POST deliveryReport](https://developers.sinch.com/docs/sms/api-reference/sms/webhooks/deliveryreport.md): 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, set the field accordingly when creating a batch. The following is provided so you can better understand our webhooks/callbacks. Configuration of both webhooks and the type of delivery report requested happens when sending a batch. #### Callback URL The callback URL can either be provided for each batch or provisioned globally for your account in your Sinch Customer Dashboard. Learn how to configure a webhook/callback here. #### Type The is the type of delivery report webhook. The response will vary depending on the webhook delivery report you selected when the batch was sent, so choose the appropriate selection under "One of". - The and types are documented under Delivery report. These are reports containing either a full report or summary report, depending on your selection at the time the batch was sent. - The and delivery report types are documented under Recipient delivery report. These are delivery reports for recipient phone numbers. If you set for the parameter when sending the batch, a recipient report gets sent to you for each status change for each recipient in your batch. If you set , a recipient report gets sent to you for the final status of each recipient in your batch. ## Groups A group is a set of phone numbers (or [MSISDNs](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)) that can be used as a target when sending an SMS. An phone number (MSISDN) can only occur once in a group and any attempts to add a duplicate are ignored but not rejected. ### Retrieve a group - [GET /xms/v1/{service_plan_id}/groups/{group_id}](https://developers.sinch.com/docs/sms/api-reference/sms/groups/retrievegroup.md): This operation retrieves a specific group with the provided group ID. ### Replace a group - [PUT /xms/v1/{service_plan_id}/groups/{group_id}](https://developers.sinch.com/docs/sms/api-reference/sms/groups/replacegroup.md): 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. ### Update a group - [POST /xms/v1/{service_plan_id}/groups/{group_id}](https://developers.sinch.com/docs/sms/api-reference/sms/groups/updategroup.md): With the update group operation, you can add and remove members in an existing group as well as rename the group. This method encompasses a few ways to update a group: 1. By using and arrays containing phone numbers, you control the group movements. Any list of valid numbers in E.164 format can be added. 2. By using the object, your customer can add or remove themselves from groups. 3. You can also add or remove other groups into this group with and . #### Other group update info - The request will not be rejected for duplicate adds or unknown removes. - The additions will be done before the deletions. If an phone number is on both lists, it will not be apart of the resulting group. - Updating a group targeted by a batch message scheduled in the future is allowed. Changes will be reflected when the batch is sent. ### Delete a group - [DELETE /xms/v1/{service_plan_id}/groups/{group_id}](https://developers.sinch.com/docs/sms/api-reference/sms/groups/deletegroup.md): This operation deletes the group with the provided group ID. ### List Groups - [GET /xms/v1/{service_plan_id}/groups](https://developers.sinch.com/docs/sms/api-reference/sms/groups/listgroups.md): With the list operation you can list all groups that you have created. This operation supports pagination. Groups are returned in reverse chronological order. ### Create a group - [POST /xms/v1/{service_plan_id}/groups](https://developers.sinch.com/docs/sms/api-reference/sms/groups/creategroup.md): This endpoint allows you to create a group of recipients. A new group must be created with a group name. This is represented by the field which can be up to 20 charecters. In addition, there are a number of optional fields: - field enables groups to be created with an initial list of contacts - allows customers to auto subscribe to a new group. This contains three fields. The field contains the group creator's number. (This number .) The and fields are objects containing the keywords that customers need to text to join or leave a group. ### Get phone numbers for a group - [GET /xms/v1/{service_plan_id}/groups/{group_id}/members](https://developers.sinch.com/docs/sms/api-reference/sms/groups/getmembers.md): This operation retrieves the members of the group with the provided group ID. ## Batches 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. ### Get a batch message - [GET /xms/v1/{service_plan_id}/batches/{batch_id}](https://developers.sinch.com/docs/sms/api-reference/sms/batches/getbatchmessage.md): This operation returns a specific batch that matches the provided batch ID. ### Replace a batch - [PUT /xms/v1/{service_plan_id}/batches/{batch_id}](https://developers.sinch.com/docs/sms/api-reference/sms/batches/replacebatch.md): 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. ### Update a Batch message - [POST /xms/v1/{service_plan_id}/batches/{batch_id}](https://developers.sinch.com/docs/sms/api-reference/sms/batches/updatebatchmessage.md): This operation updates all specified parameters of a batch that matches the provided batch ID. ### Cancel a batch message - [DELETE /xms/v1/{service_plan_id}/batches/{batch_id}](https://developers.sinch.com/docs/sms/api-reference/sms/batches/cancelbatchmessage.md): 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. ### List Batches - [GET /xms/v1/{service_plan_id}/batches](https://developers.sinch.com/docs/sms/api-reference/sms/batches/listbatches.md): With the list operation you can list batch messages created in the last 14 days that you have created. This operation supports pagination. ### Send - [POST /xms/v1/{service_plan_id}/batches](https://developers.sinch.com/docs/sms/api-reference/sms/batches/sendsms.md): 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. Be sure to use the correct region in the server URL. ### Send delivery feedback for a message - [POST /xms/v1/{service_plan_id}/batches/{batch_id}/delivery_feedback](https://developers.sinch.com/docs/sms/api-reference/sms/batches/deliveryfeedback.md): Send feedback if your system can confirm successful message delivery. Feedback can only be provided if was set when batch was submitted. : 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 key is still required even if the value is empty. : If the batch message was created 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. ### Dry run - [POST /xms/v1/{service_plan_id}/batches/dry_run](https://developers.sinch.com/docs/sms/api-reference/sms/batches/dry_run.md): 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. ## Inbounds Inbounds, or Mobile Originated (MO) 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. ## MMS Media error codes The REST API handles MO media messages by uploading them to specified s3 storage location and providing the URL to download the attachment. On a successful upload, the code will be `0`. If the upload fails, the code will be a value other than `0`. | Status Code | Name | Status | Description | | --------------- | ---------------------------- | ------------ | --------------------------------------------------------- | | 0 | Uploaded | `Uploaded` | Attachment successfully uploaded to storage. | | 1 | Internal failure | `Failed` | Internal exception happened during upload. | | 2 | Bucket not found | `Failed` | Provisioned bucket doesn't exist. | ### List incoming messages - [GET /xms/v1/{service_plan_id}/inbounds](https://developers.sinch.com/docs/sms/api-reference/sms/inbounds/listinboundmessages.md): 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. ### Retrieve inbound message - [GET /xms/v1/{service_plan_id}/inbounds/{inbound_id}](https://developers.sinch.com/docs/sms/api-reference/sms/inbounds/retrieveinboundmessage.md): This operation retrieves a specific inbound message using the provided inbound ID. ### Incoming SMS - [POST incomingSMS](https://developers.sinch.com/docs/sms/api-reference/sms/inbounds/incomingsms.md): An inbound message is a message sent to one of your short codes or long numbers from a mobile phone. To receive inbound message callbacks, a URL needs to be added to your REST API. This URL can be specified in your Dashboard. ### Incoming SMS - [POST incomingSMS](https://developers.sinch.com/docs/sms/api-reference/sms/webhooks/incomingsms.md): An inbound message is a message sent to one of your short codes or long numbers from a mobile phone. To receive inbound message callbacks, a URL needs to be added to your REST API. This URL can be specified in your Dashboard.