Reading messages

Prerequisites

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.

Quick start

Using the example below, replace “API_NYCKEL” with a bearer token that you create in the user portal, and {batchId} with an actual batch ID.

curl -X GET "https://api.ip1sms.com/v2/batches/{batchId}/messages" \
-H "Authorization: Bearer API_NYCKEL" \
-H "Content-Type: application/json" \

call

Reading a collection of Messages

This endpoint provides you with all messages in a batch with latest associated delivery reports. Sorted by date created, chronological order.

Endpoint: /v2/batches/{batchId}/messages

Methodology: GET

Examples of calls

https://api.ip1sms.com/batches/5bc86b6e85c7209830f96936/messages

Read a Single Message

This endpoint provides you with a single message, with a full history of the message delivery reports.

Endpoint: /v2/batches/{batchId}/messages/{messageId}

Methodology: GET

Examples of calls

https://api.ip1sms.com/batches/5bc86b6e85c7209830f96936/messages/5bcf4324ee47dee41a9dbb13

Fields for calls

Field name Unbloggable Type Description and Conditions Example
batchId Yes String The overall batch identifier 

5bc86b6e85c7209830f96936
messageId Yes, when listing specific message String A unique identifier for a specific message. 

5bcf4324ee47dee41a9dbb13

Response

Example of response data

Below is an example of a response from a successful call to the endpoint /v2/batches/{batchId}/messages/{messageId}, a GET call to list a specific message. See under the heading Fields for response data for a detailed description of all fields in the response.

{
    "id": "5bcf4324ee47dee41a9dbb13",
    "batchId": "5bc86b6e85c7209830f96936",
    "owner": "ip1-XXXXX",
    "sender": "iP1",
    "recipient": "456189040623",
    "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"
}

Fields for response data

Field name Type Description and Conditions Example
id String A unique ID for the specific message. 

"id": "5bcf4324ee47dee41a9dbb13"
batchId String The overall batch identifier 

"batchId": "5bc86b6e85c7209830f96936"
owner String The account ID of the SMS account that owns the message (e.g. you). 

"owner": "ip1-XXXXX"
sender String The sender of the message 

"sender": "iP1"
recipient String Recipient's mobile number 

"recipient": "456189040623"
body String The message itself 

"body": "Hi my name is earl"
direction String Tells you if the message sent or received by our system
  • MT An acronym for Mobile Terminated, a message that was sent to a mobile device.
  • MO An acronym for Mobile Originated, a message that was sent from a mobile device.
 

 "direction": "MT"
segments String In cases where the message consists of more characters than the character limit for one SMS, the message will be split into several SMS, also called concatenated SMS. This property indicates how many SMS are needed to send the message 

"segments": 1
datacoding String Specifies the minimum data encoding scheme needed to send the message in question. If the message body contains characters outside the specified data encoding, the message is not sent, as the latest status code should indicate. This may differ from the batch data encoding. 

"datacoding": "ucs"
priority String The priority of the message. Priority 1 is the default value and also the lowest priority provided. Priority 2 is the highest priority. 

 "priority": 1
price String The price of the whole message. If you want to know the price of an individual SMS in a message, you can divide the message price by the number of segments. 

 "price": 0.0416
currency String Which currency the given price uses. 

  "currency": "EUR",
statuses Array A list of status updates. When retrieving a single message, you get a list of all the statuses of the message. When retrieving a list of several messages, only the latest status of each message is listed. 

 "statuses": [
    {
        "created": "2018-10-23T17:43:21Z",
        "code": 201,
        "duration": 0
    }
],
modified String When the SMS was last updated. 

"modified": "2018-10-23T17:43:19Z",
reference String This is a property that allows the user to set a custom ID or reference if storing the default default generated IDs is disallowed. 

"reference": "A client reference",
mcc String The country part of the leaf operator can be specified here if provided by the upstream carrier. MCC is an acronym for Mobile Country Code 

"mcc": "431",
mnc String The network part of the leaf operator can be specified here if it is provided by the upstream carrier. MNC is an acronym for Mobile Network Code 

"mnc": "20"