> For the complete documentation index, see [llms.txt](https://developers.mobile-text-alerts.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.mobile-text-alerts.com/check-delivery-status.md).

# Check Delivery Status

Learn how to view the Delivery Status of outbound messages

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>

See [Pagination of Large Results](/api-basics/pagination-of-large-results.md) to learn more.

## List Deliveries

> List all deliveries where the \`query\` value matches either the sender or recipient phone number, filtered by the specified \`filters\` categories.

```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"]}},"required":["data"]}]},"IApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"},"data":{}}},"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","blocked"]},"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":"page","in":"query","required":false,"schema":{"type":"number"}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"number"}},{"name":"sortDirection","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc","ASC","DESC"]}},{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string"}},{"name":"filters","in":"query","required":false,"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"status":{"$ref":"#/components/schemas/MTADeliveryLabel"},"type":{"$ref":"#/components/schemas/SentMessageType"}}}}],"description":"List all deliveries where the `query` value matches either the sender or recipient phone number, filtered by the specified `filters` categories."}}}}
```

## 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.