# Check Delivery Status

There are two ways to check the delivery status of your message sends with Mobile Text Alerts:

* [#call-the-list-deliveries-api-endpoint](#call-the-list-deliveries-api-endpoint "mention")
  * Best for reporting and analytics on settled message data. This includes only the most recent status for a message.
* [#configure-the-delivery-status-webhook](#configure-the-delivery-status-webhook "mention")
  * Best for real-time status updates. This webhook can send the full status history from the moment of send to the final result (delivered, rejected, etc.).

## Call the List Deliveries API endpoint

With the [<mark style="color:green;">`GET`</mark> `/deliveries`](#get-deliveries) endpoint of the Mobile Text Alerts API, you can list all messages sent to subscribers, or use query parameters to filter results. The message status shows the most recent status for each message.

### Example request to filter the delivery status

See below how to filter messages that have delivery status of  `delivered` :&#x20;

{% tabs %}
{% tab title="cURL" %}
{% code overflow="wrap" %}

```bash
curl --location 'https://api.mobile-text-alerts.com/v3/deliveries?filters%5Bstatus%5D=delivered' \
  --header 'Authorization: Bearer <APIKey>' 
```

{% endcode %}

*Note: the `[]` brackets are escaped characters*
{% endtab %}

{% tab title="Node.js" %}

```javascript
// Get only delivered messages
const response = await fetch(
  'https://api.mobile-text-alerts.com/v3/deliveries?filters[status]=delivered',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MTA_API_KEY}`
    }
  }
);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

# Get only delivered messages
response = requests.get(
    'https://api.mobile-text-alerts.com/v3/deliveries',
    params={'filters[status]': 'delivered'},
    headers={'Authorization': f'Bearer {os.getenv("MTA_API_KEY")}'}
)

```

{% endtab %}
{% endtabs %}

#### Query Parameters

<table><thead><tr><th width="198.5">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>page</code></td><td><code>number</code></td><td>Specific page number to retrieve.</td></tr><tr><td><code>pageSize</code></td><td><code>number</code></td><td>Number of results per page.</td></tr><tr><td><code>sortBy</code></td><td><code>date</code></td><td>Field to sort results by date.</td></tr><tr><td><code>sortDirection</code></td><td><code>ASC</code>|<code>DESC</code></td><td>Direction to sort results by, choose either <code>ASC</code> for ascending or <code>DESC</code> for descending.</td></tr><tr><td><code>query</code></td><td><code>string</code></td><td>The <code>query</code> string will return all subscribers with this value in either <code>firstName</code>, <code>lastName</code>, <code>number</code>, or <code>email</code>.</td></tr><tr><td><code>filters[startDate]</code></td><td><code>date</code> in format: YYYY-MM-DD</td><td>Filter results to only show results after a specified start date.</td></tr><tr><td><code>filters[endDate]</code></td><td><code>date</code> in format: YYYY-MM-DD</td><td>Filter results to only show results before a specified end date.</td></tr><tr><td><code>filters[type]</code></td><td><code>string enum</code>:<code>sms</code>|<code>mms</code>|<code>tts</code></td><td>Filter results by message type, choose one of the following type codes: <code>sms</code>|<code>mms</code>|<code>tts</code>.</td></tr><tr><td><code>filters[status]</code></td><td><code>string enum</code>:<code>sent</code>|<code>delivered</code>|<code>undelivered</code>|<code>undeliverable</code>|<code>unknown</code>|<code>rejected</code></td><td>Filter results by delivery status, choose one of the following status codes: <code>sent</code>|<code>delivered</code>|<code>undelivered</code>|<code>undeliverable</code>|<code>unknown</code>|<code>rejected</code>.</td></tr></tbody></table>

## List Deliveries

> List all subscribers and query for subscribers. Includes all subscribers with \`query\` value in either first name, last name, number, email, or custom subscriber fields and with \`filters\` values in respective categories.\
> \
> \
> undefined

```json
{"openapi":"3.0.0","info":{"title":"Mobile Text Alerts API","version":"8.0.0"},"servers":[{"url":"https://api.mobile-text-alerts.com/v3"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"apiKey"}},"schemas":{"ListDeliveries.Response":{"allOf":[{"$ref":"#/components/schemas/IApiResponsePaginated"},{"type":"object","properties":{"data":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/IDeliveryRecord"}},"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"}},"required":["rows","page","pageSize","total"]}},"required":["data"]}]},"IApiResponsePaginated":{"allOf":[{"$ref":"#/components/schemas/IApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"rows":{"type":"array","items":{}},"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"}},"required":["rows","page","pageSize","total"],"description":"PaginationData"}},"required":["data"]}]},"IApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"},"data":{}},"required":[]},"IDeliveryRecord":{"type":"object","properties":{"messageId":{"type":"number"},"externalId":{"type":"string","nullable":true},"message":{"type":"string"},"attachment":{"type":"string"},"status":{"$ref":"#/components/schemas/MTADeliveryLabel"},"date":{"type":"string"},"carrier":{"type":"string","nullable":true},"to":{"type":"string"},"from":{"type":"string"},"type":{"$ref":"#/components/schemas/SentMessageType"}},"required":["messageId","externalId","status","date","carrier","to","from","type"]},"MTADeliveryLabel":{"type":"string","enum":["sent","delivered","undelivered","undeliverable","unknown","rejected"]},"SentMessageType":{"type":"string","enum":["sms","mms","tts","phone-call","email","survey"]}},"responses":{"BadRequestError":{"description":"BadRequestError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[400]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["bad_request_error"]},"name":{"type":"string","enum":["MTABadRequestError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"UnauthorizedError":{"description":"UnauthorizedError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[401]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["unauthorized_error"]},"name":{"type":"string","enum":["MTAUnauthorizedError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"ForbiddenError":{"description":"ForbiddenError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[403]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["forbidden_error"]},"name":{"type":"string","enum":["MTAForbiddenError"]},"requestId":{"type":"string","format":"uuid"},"reason":{}}}}}},"InternalServerError":{"description":"InternalServerError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[500]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["internal_server_error"]},"name":{"type":"string","enum":["MTAInternalServerError"]},"requestId":{"type":"string","format":"uuid"}}}}}}}},"paths":{"/deliveries":{"get":{"tags":["Deliveries"],"summary":"List Deliveries","operationId":"deliveries_list_deliveries","responses":{"200":{"description":"Success","headers":{"RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds to wait before retrying the request","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"X-Request-ID":{"description":"A unique identifier for the request","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListDeliveries.Response"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}},"parameters":[{"name":"filters","in":"query","required":false,"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"type":{"$ref":"#/components/schemas/SentMessageType"},"status":{"$ref":"#/components/schemas/MTADeliveryLabel"}},"required":[]}}],"description":"List all subscribers and query for subscribers. Includes all subscribers with `query` value in either first name, last name, number, email, or custom subscriber fields and with `filters` values in respective categories.\n\n\nundefined"}}}}
```

## Configure the `delivery-status` webhook

A `delivery-status` webhook event is triggered when Mobile Text Alerts receives an updated [delivery status code](/tutorials/webhooks.md#mta-delivery-status-codes) from a provider for a sent message. This is best for real-time status updates, since you can receive the full status history from the moment of send to the final result (delivered, rejected, etc.).

If you haven't configured webhooks for your account, see [Setting up your first webhook](/tutorials/webhooks/setting-up-your-first-webhook.md).

Also see the [Delivery Status payload](/tutorials/webhooks.md#delivery-status) to learn which fields are sent as part of this webhook.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.mobile-text-alerts.com/check-delivery-status.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.