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.
API Overview | Sinch (v1)
Overview
Languages
Servers
Global API
https://{region}.sms.api.sinch.com/
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 or sent as a callback.
OperationsWebhooks
Groups
A group is a set of phone numbers (or MSISDNs) 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.
Operations
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.
Request
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.
The incoming message to your sinch number
If this inbound message is in response to a previously sent message that contained a client reference, then this field contains that client reference.
Utilizing this feature requires additional setup on your account. Contact your account manager to enable this feature.
When the system received the message.
Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
When the message left the originating device. Only available if provided by operator.
Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
The Sinch phone number or short code to which the message was sent.
Example: "11203453453"
- Global API
https://us.sms.api.sinch.com/incomingSMS
application/json
{ "body": "This is a test message.", "from": "16051234567", "id": "01XXXXX21XXXXX119Z8P1XXXXX", "operator_id": "string", "received_at": "2022-08-24 14:15:22+00:00", "sent_at": "2022-08-24 14:15:22+00:00", "to": "13185551234", "type": "mo_text" }
Request
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 delivery_report 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.
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.
The type 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
delivery_report_smsanddelivery_report_mmstypes 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
recipient_delivery_report_smsandrecipient_delivery_report_mmsdelivery report types are documented under Recipient delivery report. These are delivery reports for recipient phone numbers. If you setper_recipientfor thedelivery_reportparameter when sending the batch, a recipient report gets sent to you for each status change for each recipient in your batch. If you setper_recipient_final, a recipient report gets sent to you for the final status of each recipient in your batch.
One of:
The ID of the batch this delivery report belongs to.
Example: "01FC66621XXXXX119Z8PMV1QPQ"
The client identifier of the batch this delivery report belongs to, if set when submitting batch.
Array with status objects. Only status codes with at least one recipient will be listed.
The detailed status code.
| Enum Value | Description |
|---|---|
| 400 | Queued. Message is queued within REST API system and will be dispatched according to the rate of the account. |
| 401 | Dispatched. Message has been dispatched to SMSC. |
| 402 | Message unroutable. SMSC rejected message. Retrying is likely to cause the same error. |
| 403 | Internal error. An unexpected error caused the message to fail. |
| 404 | Temporary delivery. failure` Message failed because of temporary delivery failure. Message can be retried. |
| 405 | Unmatched Parameter. One or more parameters in the message body has no mapping for this recipient. See Message Parameterization |
| 406 | Internal Expiry. Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short. |
| 407 | Cancelled. Message was cancelled by user before reaching SMSC. |
| 408 | Internal Reject. SMSC rejected the message. Retrying is likely to cause the same error. |
| 410 | Unmatched default originator. No default originator exists/configured for this recipient when sending message without originator. |
The number of messages that currently has this code.
Example: 2
Only for full report. A list of the phone number recipients which messages has this status code.
Example: ["15551231234","15551256344"]
The simplified status as described in Delivery Report Statuses.
| Enum Value | Description |
|---|---|
| Queued | Intermediate type. Message is queued within REST API system and will be dispatched according to the rate of the account. |
| Dispatched | Intermediate type. Message has been dispatched and accepted for delivery by the SMSC. |
| Aborted | Final type. Message was aborted before reaching the SMSC. |
| Cancelled | Final type. Message was cancelled by user before reaching SMSC. |
| Failed | Final type. Message failed to be delivered. |
| Delivered | Final type. Message has been delivered. |
| Expired | Final type. Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short. |
| Rejected | Final type. Message was rejected by the SMSC. |
| Deleted | Final type. Message was deleted by the SMSC. |
| Unknown | Final type. Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received. |
- Global API
https://us.sms.api.sinch.com/deliveryReport
application/json
{ "batch_id": "01FC66621XXXXX119Z8PMV1QPQ", "statuses": [ { … } ], "total_message_count": 1, "type": "delivery_report_sms" }