> ## Documentation Index
> Fetch the complete documentation index at: https://onextel-09023014.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Status

> Look up delivery status for one or more messages by message ID or mobile number.

The Message Status endpoint returns delivery status for messages you've sent, looked up
either by `messageId` or by `mobileNumber` with a date range.

## Endpoint

```
POST https://api.onexaura.com/status
```

## Headers

<ParamField header="apikey" type="string" required>
  API key issued by OneXtel, used for authentication.
</ParamField>

## Choosing a lookup

You must supply **either** `messageId` **or** `mobileNumber` — never both.

| Lookup by | Date range |
| - | - |
| `messageId` | Optional |
| `mobileNumber` | **Required** — `from` and `to` must both be supplied |

<Warning>
  Passing `messageId` and `mobileNumber` in the same request returns an error. Supplying neither
  does too — one of the two is always required.
</Warning>

## Request body

The request body is a JSON object.

<ParamField body="channel" type="string" required>
  Channel to query — `whatsapp`, `rcs`, or `sms`.
</ParamField>

<Note>
  **Verified against the live API (Aug 2026):** when looking up by `messageId`, the `channel`
  value is not validated — `whatsapp`, `wa`, `sms`, an arbitrary string, and omitting the field
  entirely all return the same record. A message ID is already unique, so the channel adds
  nothing. It is still worth sending the correct value: it is likely to matter for `mobileNumber`
  lookups, where the same number can appear on more than one channel.
</Note>

<ParamField body="taId" type="integer">
  Tenant administrator ID. Scopes the query to a tenant.
</ParamField>

<ParamField body="tucId" type="integer">
  TUC ID. Scopes the query to a specific account under the tenant.
</ParamField>

<Note>
  **Verified:** `taId` and `tucId` are optional. Requests omitting both return the same result,
  because the API key already identifies the account. They appear in requests from tenant-level
  callers, where they scope the lookup to one account under the tenant.
</Note>

<ParamField body="messageId" type="array">
  Array of message IDs to look up. Required unless `mobileNumber` is supplied, and mutually
  exclusive with it.
</ParamField>

<ParamField body="mobileNumber" type="array">
  Array of recipient mobile numbers, with country code. Required unless `messageId` is
  supplied, and mutually exclusive with it.
</ParamField>

<ParamField body="from" type="string">
  Start of date range, formatted `YYYY-MM-DD HH:mm:ss` — for example
  `"2025-12-17 00:00:00"`. Mandatory when querying by `mobileNumber`.
</ParamField>

<ParamField body="to" type="string">
  End of date range, formatted `YYYY-MM-DD HH:mm:ss` — for example
  `"2025-12-17 23:59:59"`. Mandatory when querying by `mobileNumber`.
</ParamField>

<ParamField body="pageNo" type="integer" default="0">
  Page number for paginated results.
</ParamField>

<ParamField body="limit" type="integer" default="10">
  Number of records to return per page.
</ParamField>

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.onexaura.com/status \
    --header 'apikey: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "taId": 10,
    "tucId": 2002,
    "channel": "whatsapp",
    "messageId": [
      "3I7dnaYRaiTVj8f5EgxsoiJrT5R"
    ],
    "pageNo": 0,
    "limit": 100
  }'
  ```

  ```json Request body (by messageId) theme={null}
  {
    "taId": 10,
    "tucId": 2002,
    "channel": "whatsapp",
    "messageId": [
      "3I7dnaYRaiTVj8f5EgxsoiJrT5R"
    ],
    "pageNo": 0,
    "limit": 100
  }
  ```

  ```json Request body (by mobileNumber) theme={null}
  {
    "channel": "whatsapp",
    "mobileNumber": ["919999999999"],
    "from": "2025-12-17 00:00:00",
    "to": "2025-12-17 23:59:59",
    "pageNo": 0,
    "limit": 10
  }
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "data": [
    {
      "uuid": "3I7dnaYRaiTVj8f5EgxsoiJrT5R",
      "mobileNumber": "919999999999",
      "status": "DELIVERED",
      "failedErrorCode": "000",
      "failedErrorMessage": "Delivered",
      "onexReceivedTs": 1786517520081,
      "credit": 1,
      "buttonClick": 0,
      "urlClick": 0,
      "customParam1": "",
      "customParam2": "",
      "customParam3": "",
      "customParam4": "",
      "customParam5": ""
    }
  ],
  "pagination": {
    "totalRecords": 1
  }
}
```

<ResponseField name="data" type="array">
  One object per matching message.
</ResponseField>

<ResponseField name="pagination.totalRecords" type="integer">
  Total number of records matching the query, across all pages.
</ResponseField>

### Record fields

<ResponseField name="uuid" type="string">
  Unique message identifier — the same value returned when the message was sent.
</ResponseField>

<ResponseField name="mobileNumber" type="string">
  Recipient number.
</ResponseField>

<ResponseField name="status" type="string">
  Current delivery state.
</ResponseField>

<ResponseField name="failedErrorCode" type="string">
  Outcome code. `000` is delivered; anything else is a failure reason — see
  [SMS error codes](/api-reference/sms/error-codes).
</ResponseField>

<ResponseField name="failedErrorMessage" type="string">
  Human-readable description of `failedErrorCode`.
</ResponseField>

<ResponseField name="onexReceivedTs" type="integer">
  Timestamp in epoch milliseconds at which the platform received the status.
</ResponseField>

<ResponseField name="credit" type="integer">
  Credits consumed by the message.
</ResponseField>

<ResponseField name="buttonClick" type="integer">
  Whether a button in the message was clicked.
</ResponseField>

<ResponseField name="urlClick" type="integer">
  Whether a tracked URL in the message was clicked.
</ResponseField>

<ResponseField name="customParam1" type="string">
  Custom reference set on the original send, echoed back. `customParam1` through
  `customParam5`.
</ResponseField>

<Note>
  `failedErrorCode` here is the same code set as the [SMS error codes](/api-reference/sms/error-codes)
  table, despite the field name — it carries `000` on success too, not only on failure.
</Note>

## Errors

An invalid or missing API key returns **HTTP 400** with the body:

```
"NO VALID AUTH_KEY FOUND!"
```

## Related

* [RCS delivery notification](/api-reference/rcs/callback-delivery-notification) — push delivery status instead of polling for it
* [WhatsApp callback events](/api-reference/whatsapp/callback-events)
* [Message history](/api-reference/omnichannel/message-history)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.