Skip to content
SMS/REST API reference/
/
List incoming messages

API Overview | Sinch (v1)

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.

Download OpenAPI description
sms.json
sms.yaml
Overview
URL

https://www.sinch.com

Support

Support@sinch.com

License

MIT

Terms of Service

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

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.

Operations

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.

OperationsWebhooks

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 CodeNameStatusDescription
0UploadedUploadedAttachment successfully uploaded to storage.
1Internal failureFailedInternal exception happened during upload.
2Bucket not foundFailedProvisioned bucket doesn't exist.

List incoming messages

Request

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.

Security
BearerAuth
Path
service_plan_idstringrequired

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
Query
pageinteger>= 0

The page number starting from 0.

Default 0
Example: page=2
page_sizeinteger[ 1 .. 100 ]

Determines the size of a page

Default 30
toArray of strings

Only list messages sent to this destination. Multiple phone numbers formatted as either E.164 or short codes can be comma separated.

Example: to=+14155553421,45607
start_datestring(date-time)

Only list messages received at or after this date/time. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

Default: Now-24

end_datestring(date-time)

Only list messages received before this date/time. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

Example: end_date=2016-10-02T09:34:18.542Z
client_referencestring[ 0 .. 2048 ] characters

Using a client reference in inbound messages requires additional setup on your account. Contact your account manager to enable this feature.

Only list inbound messages that are in response to messages with a previously provided client reference.

Example: client_reference=myReference
curl -i -X GET \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/inbounds?page=2&page_size=30&to=%2B14155553421%2C45607&start_date=2019-08-24T14%3A15%3A22Z&end_date=2016-10-02T09%3A34%3A18.542Z&client_reference=myReference' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK. A successful response , or an Error.

Bodyapplication/json
countinteger(int64)

The total number of inbounds matching the given filters

Example: 2
pageinteger(int32)

The requested page.

Example: 0
inboundsArray of Text MO (object) or Binary MO (object) or Media MO (object)(inbound)

The page of inbounds matching the given filters.

page_sizeinteger(int32)

The number of inbounds returned in this request.

Example: 2
Response
application/json
{
  "count": 2,
  "page": 0,
  "inbounds": [
    { … }
  ],
  "page_size": 2
}

Retrieve inbound message

Request

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

Security
BearerAuth
Path
service_plan_idstringrequired

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
inbound_idstringrequired

The inbound ID found when listing inbound messages.

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

Responses

OK. A successful response , or an Error.

Bodyapplication/json
bodystring[ 0 .. 2000 ] charactersrequired
fromstringrequired

The phone number that sent the message. More info

Example: "+11203494390"
idstringrequired

The ID of this inbound message.

Example: "01FC66621XXXXX119Z8PMV1QPA"
received_atstring(date-time)required

When the system received the message.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

tostringrequired

The Sinch phone number or short code to which the message was sent.

Example: "11203453453"
typestringread-onlyrequired

Regular SMS

ValueDescription
mo_text

Regular SMS

Discriminator
client_referencestring

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.

operator_idstring

The MCC/MNC of the sender's operator if known.

Example: "35000"
sent_atstring(date-time)

When the message left the originating device. Only available if provided by operator.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

Response
application/json
{
  "body": "Test message",
  "client_reference": "ABC123",
  "from": "+11203494390",
  "id": "01FC66621XXXXX119Z8PMV1QPA",
  "operator_id": "35000",
  "received_at": "2019-08-24T14:15:22Z",
  "sent_at": "2019-08-24T14:15:22Z",
  "to": "11203453453",
  "type": "mo_text"
}

Incoming SMSWebhook

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.

Bodyapplication/json

The incoming message to your sinch number

bodystring[ 0 .. 2000 ] charactersrequired
fromstringrequired

The phone number that sent the message. More info

Example: "+11203494390"
idstringrequired

The ID of this inbound message.

Example: "01FC66621XXXXX119Z8PMV1QPA"
received_atstring(date-time)required

When the system received the message.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

tostringrequired

The Sinch phone number or short code to which the message was sent.

Example: "11203453453"
typestringread-onlyrequired

Regular SMS

ValueDescription
mo_text

Regular SMS

Discriminator
client_referencestring

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.

operator_idstring

The MCC/MNC of the sender's operator if known.

Example: "35000"
sent_atstring(date-time)

When the message left the originating device. Only available if provided by operator.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

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"
}

Responses

A 2xx status code indicates that the data was received successfully.

Webhooks

Webhooks