Message Status API

In addition to obtaining SMS Delivery Receipts (DLR) via the Callback mechanism, the PaaSoo platform also supports synchronous querying. This allows you to call the API to check the delivery results of specific messages whenever needed. This query API is particularly useful when you want to actively poll or manually trigger a query without relying on passive callbacks.

1. Invocation Method

Invocation Method

• HTTP Method: GET
• Endpoint: https://api.paasoo.com/dlr
• Usage Scenario: You can call this API when you need to manually retrieve or periodically review the SMS delivery status based on the Message ID. In some countries or regions, the reliability of Operator DLRs is limited, so this query can be used to further confirm the delivery status.

---

2. Request Example

GET https://api.paasoo.com/dlr?key=API_KEY&secret=API_SECRET&messageid=MESSAGE_ID

---

3. Request Parameters

Parameter	Type	Required	Description	Example
key	string	Yes	API Key (composed of 8 alphanumeric characters), used to uniquely identify your account. Can be obtained in the PaaSoo dashboard.	Abcdefgh
secret	string	Yes	API Secret (composed of 8 alphanumeric characters), used in conjunction with key for authentication. Can be obtained in the PaaSoo dashboard.	Abc123EF
messageid	string	Yes	The Message ID to be queried, used to uniquely identify an SMS request.	015bd4-d6dfa7-58w

---

4. Response Example

Upon a successful query, you will receive detailed Delivery Receipt data; if the query fails, an error code and corresponding message will be returned.

4.1 Response Parameters

4.1.1 Success Parameters

Returns an array list, array item descriptions:

Parameter	Type	Description	Example
price	number	Single SMS billing price (unit: USD or determined by the account Billing currency).	0.03
network	string	The Operator network of the Destination Number, such as an MCC+MNC combination.	23420
status	string	Sending status. 1 - In progress 0 - Submitted to Carrier successfully 400 - Submitted to Carrier failed	1 - In progress
to	string	Destination Number, in the format of Country Code + phone number (without leading 00 or +).	12025550199
drTime	string	Report time (UTC+0), format (yyyy-MM-dd HH:mm:ss.ZZZ)	2025-08-12 09:01:17.676
drStatus	integer	Delivery Receipt status value: 0 - Normal status 400 - Abnormal status	0
type	string	Result data type; the Message Status API returns dlr.	dlr
messageid	string	The queried Message ID, used to uniquely identify an SMS request.	015bd4-d6dfa7-58w
counts	integer	Billing Count (may exceed 1 depending on factors like SMS length or splitting).	1
drStatuscode	string	Detailed Delivery Receipt status code: delivered - SMS Delivered, corresponds to drStatus=0 accepted - Accepted by Operator, corresponds to drStatus=0 rejected - Rejected by Operator, corresponds to drStatus=400 failed - Send Failed, corresponds to drStatus=400 expired - Operator Expired, corresponds to drStatus=400 deleted - Deleted by Operator, corresponds to drStatus=400 unknown - Unknown error, corresponds to drStatus=400	delivered
drErrcode	string	The error code returned by the Operator, corresponding to drStatuscode: 0 - Normal 1 - Unknown error 2 - Message Unreachable (suspended, powered off, no signal, etc.) 3 - Number deactivated or invalid 4 - User rejected SMS 5 - Rejected by Operator 6 - Operator timeout 7 - Deleted by Operator 8 - User Do Not Disturb (DND) 10 - Invalid title / Sender ID 11 - Invalid Template 12 - Entity ID mismatch 99 - Other Operator error	0 - Normal

4.1.2 Failure Parameters

Parameter	Type	Description	Example
code	integer	Status code. 2 - Missing parameters: Required parameters are missing 3 - Invalid parameters: Parameter format error 4 - Invalid credentials: Key or Secret error 5 - Unauthorized IP: IP Whitelist restriction 9 - Quota exceeded: Insufficient balance or credit limit 11 - System error: System error 20 - Dlr search not support: DLR query not supported	2
descr	string	Status code description.	Invalid credentials

4.2 Success Response Example

[
    {
        "type": "dlr",
        "messageid": "00041d-23fefc-c000",
        "to": "12025550199",
        "status": 0,
        "drStatus": 400,
        "drStatuscode": "failed",
        "drErrcode": "5",
        "price": 0.001,
        "counts": 1,
        "drTime": "2025-12-16 15:51:20.055",
        "network": "405840"
    }
]

4.3 Failure Response Example

{
    "code": 2,
    "descr": "Missing parameters"
}

---

5. Best Practices and Precautions

1. Signature and Security:
   • Authentication is performed via key and secret; please keep them safe to avoid leakage.
   • It is recommended to call the API using HTTPS to prevent sensitive information from being stolen during transmission.
2. Polling Strategy:
   • If you have configured the DLR Callback mechanism, you may use this query API only when the Callback fails or the message status has not been updated for a long time.
   • To avoid putting too much pressure on the server, you should set a reasonable query frequency.
3. Data Parsing:
   • Determine whether the query request is successful based on status; 0 indicates a successful query and detailed fields like drStatus can be obtained.
   • The explanation for drStatus / drStatuscode is consistent with the DLR Callback. Please combine this with your front-end or system logic for reconciliation and status mapping.
4. Compatibility:
   • Similar to the DLR Callback, Operators in certain countries or regions may not be able to provide accurate or real-time Delivery Receipts.
   • If the query result does not match the actual delivery status, you can contact the relevant Operator or PaaSoo technical support for further troubleshooting.

---

6. Summary

Through the Message Status API above, you can proactively obtain the delivery status of specified SMS at any time. Combining both DLR Callbacks and manual queries can effectively improve your ability to monitor and manage the SMS delivery link.

Support

If you encounter any technical issues or have business inquiries during the API integration, please do not hesitate to contact our Support team at support@paasoo.com. We are always here to assist you.