Query SMS-MT Details
Purpose
Returns details and current delivery status of Mobile Terminated (MT) SMS messages sent to the SIM specified in the <iccid> element.
This includes messages sent:
- From the SIM Insight Portal
- Via the SIM Insight API
This function is not available for Open-User-Group SIM types (e.g. MultiNET KPN-O).
Endpoint
POST https://api.m2miportal.com
Content-Type: application/xml
Accept: application/xml
Request (XML)
<query-sms-mt-details version="1" api-id="123456">
<authentication>
<username>username</username>
<password>password</password>
</authentication>
<iccid>1234567890123456789</iccid>
<lastx>3</lastx>
</query-sms-mt-details>Response (Success)
<query-sms-mt-details-response api-id="123456">
<api-outcome>Success</api-outcome>
<sms>
<sent-timestamp>09/10/2014 20:08:04</sent-timestamp>
<sms-uid>84ry3h2160</sms-uid>
<status>Delivered</status>
<delivered-timestamp>09/10/2014 20:08:14</delivered-timestamp>
<origin>API</origin>
<message-text>Reset Modem</message-text>
</sms>
<sms>
<sent-timestamp>09/10/2014 16:28:15</sent-timestamp>
<sms-uid>84ry3h2189</sms-uid>
<status>Pending</status>
<delivered-timestamp></delivered-timestamp>
<origin>Portal</origin>
<message-text>Update APN Setting</message-text>
</sms>
</query-sms-mt-details-response>
Request Parameters
Element | Required | Description |
|---|---|---|
<iccid> | Yes | Target SIM ICCID. |
<lastx> | No | Integer between 1 and 20. Number of most recent MT messages to return. |
Behaviour
- If <lastx> is omitted → Only the most recent message is returned.
- Results are returned with the most recently sent message first.
- If no messages are available → A single empty <sms> element is returned.
Response Elements
Each message is enclosed within an <sms> element.
Element | Description |
|---|---|
<sent-timestamp> | UTC date/time message was sent. Format: DD/MM/YYYY HH:MM:SS |
<sms-uid> | Included only if specified when the SMS was sent. |
<status> | Current delivery status: Pending, Delivered or Failed |
<delivered-timestamp> | UTC delivery time. Empty if not delivered. |
<origin> | Indicates message source: Portal or API |
<message-text> | SMS content in plain text (XML substitutions applied). |
Status Values
Status | Meaning |
|---|---|
Pending | Message queued or awaiting delivery |
Delivered | Successfully delivered to device |
Failed | Delivery failed |
Encoding Notes
- Message text is returned in plain text (with standard XML reserved character substitutions).
- Character set is restricted to GSM 7-bit default alphabet (3GPP TS 23.038).
- Other character sets may result in unpredictable outcomes.
- If the SMS was sent using <data-coding>binary</data-coding> (MultiNET KPN-C only), the <message-text> element will be returned encoded as Base64.
Additional Notes
- Historical SMS records sent prior to March 2016 may have an empty <origin> element.
- Delivery status may change over time as operator delivery receipts are received.
- This endpoint returns only Mobile Terminated (MT) messages.
Operational Notes
- SMS can only be delivered to Active SIMs.
- SMS availability depends on SIM type and operator support.
- Delivery is not guaranteed and may be asynchronous.
- Operator limits may result in message rejection.
Response (Failure)
If a request cannot be processed, the response will include:
- api-outcome indicating failure
- An error description explaining the reason
Failure responses may occur due to:
- Invalid authentication credentials
- Invalid or unknown identifiers (for example ICCID or MSISDN)
- Invalid or missing parameters
- Values not permitted for the specified SIM type or account configuration
- Insufficient permissions
Integrating systems should validate input data before submission and implement appropriate error handling and logging.