Reading messages

When you're reading messages it's always in the context of a batch. A message can not exist without a batch and therefore messages are placed below batches hierarchically.

Reading a collection of Messages

Endpoint: GET /v2/batches/{batch}/messages

This endpoint will provide you with the documents of all messages in a batch with their latest delivery report like the response data type below. Ordered chronologically by creation date.

Read a Single Message

Endpoint: GET /v2/batches/{batch}/messages/{messageId}

This endpoint will provide you with the document of a single message with a full history of delivery reports like the data type below.

Response data type

Apart from reading the batch as a whole you may also look at specific messages.

{
    "id": "5bc86b6e85c7209830f96936",
    "batchId": "5bcf4324ee47dee41a9dbb13",
    "owner": "ip1-XXXXX",
    "sender": "TestNOS",
    "recipient": "175368927054",
    "body": "Hi my name is earl",
    "direction": "mt",
    "segments": 1,
    "type":"SMS",
    "datacoding": "ucs",
    "priority": 1,
    "price": 0.0416,
    "currency": "EUR",
    "statuses": [
        {
            "created": "2018-10-23T17:43:21Z",
            "code": 201,
            "duration": 0
        }
    ],
    "modified": "2018-10-23T17:43:19Z",
    "reference": "A client reference",
    "mcc": "431",
    "mnc": "20"
}

id

A unique ID for the specific message.

batchId

An ID for all the messages sent in the same request as this message.

owner

The account ID of the SMS account that owns the message (e.g. you).

sender

The sender ID of the message's originator.

recipient

The sender ID of the message's receiver.

direction

Determines whether the message was sent or received by our systems.

mt an acronym for mobile terminated (Outgoing)

mo an acronym for mobile originated (Incoming),

segments

In case the message contains more characters than one sms can hold the message will be split into multiple sms also known as concatenated sms. This property indicates how many sms the message needs to be sent.

datacoding

Specifies the smallest datacoding scheme needed to send the message in question. If characters outside of the specified datacoding are present in the message body the message is not sent, which the latest status code should reflect. This may differ from the batch's datacoding.

priority

The price for the entire message. In case you want to get the price for a single sms you can divide the number of segments by the price.

price

The price for the entire message. In case you want to get the price for a single sms you can divide the number of segments by the price.

currency

Which currency the given price uses.

statuses

An array of status updates.

  • status[].created
    • when the status was added
  • status[].code
    • The specific status code. More may be added in the future
  • status[].duration
    • Tells whether this is the last status update or if there may be more status updates to come.

In the case that you're requesting a collection messages only the most recent status will be provided. However when requesting one specific message the entire status history will be provided. For more information regarding our status codes for messages please see our section about status codes. Status codes.

modified

When the SMS was last updated.

reference

This is a property that allows the user to set a custom ID or credential if storing the default generated IDs is deprecated.

mcc

The country part of the leaf operator may be specified here if it's provided by the upstream carrier.

MCC is an acronym for Mobile Country Code

mnc

The network part of the leaf operator may be specified here if it's provided by the upstream carrier.

MCC is an acronym for Mobile Network Code