> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindosoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mensajes del envío

> Listar los mensajes individuales de un envío masivo

## Descripción

Devuelve la lista paginada de mensajes individuales de un envío masivo. Permite filtrar por estado para identificar rápidamente mensajes fallidos, entregados o leídos.

## Header de autenticación

<ParamField header="X-API-Key" type="string" required>
  Tu API Key de Mindo. Formato: `mindo_xxxxxxxxxxxxxxxxxxxxxxxx`
</ParamField>

## Parámetros de ruta

<ParamField path="bulk_send_id" type="string (UUID)" required>
  ID del envío masivo obtenido al crear el envío con [Enviar masivo](/api-reference/envio-masivo/enviar-masivo).
</ParamField>

## Parámetros de query

<ParamField query="status" type="string">
  Filtrar por estado del mensaje. Valores posibles: `sent`, `delivered`, `read`, `failed`.
</ParamField>

<ParamField query="page" type="integer">
  Número de página. Por defecto: `1`.
</ParamField>

<ParamField query="page_size" type="integer">
  Cantidad de resultados por página. Por defecto: `20`.
</ParamField>

## Respuesta

<ResponseField name="count" type="integer">
  Total de mensajes que coinciden con los filtros.
</ResponseField>

<ResponseField name="next" type="string | null">
  URL de la siguiente página de resultados. `null` si es la última página.
</ResponseField>

<ResponseField name="previous" type="string | null">
  URL de la página anterior. `null` si es la primera página.
</ResponseField>

<ResponseField name="results" type="array">
  Lista de mensajes individuales.

  <Expandable title="Propiedades de cada mensaje">
    <ResponseField name="id" type="integer">
      ID del mensaje.
    </ResponseField>

    <ResponseField name="recipient_phone" type="string">
      Número de teléfono del destinatario.
    </ResponseField>

    <ResponseField name="status" type="string">
      Estado actual del mensaje. Ver [tabla de estados](#estados-de-mensajes).
    </ResponseField>

    <ResponseField name="meta_message_id" type="string">
      ID del mensaje en Meta/WhatsApp.
    </ResponseField>

    <ResponseField name="variables_used" type="object">
      Variables que se usaron para este destinatario.
    </ResponseField>

    <ResponseField name="sent_at" type="string (ISO 8601)">
      Fecha y hora en que se envió el mensaje.
    </ResponseField>

    <ResponseField name="delivered_at" type="string (ISO 8601) | null">
      Fecha y hora de entrega. `null` si aún no fue entregado.
    </ResponseField>

    <ResponseField name="read_at" type="string (ISO 8601) | null">
      Fecha y hora de lectura. `null` si aún no fue leído.
    </ResponseField>

    <ResponseField name="error_message" type="string | null">
      Mensaje de error si el envío falló. `null` si no hubo error.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.mindosoftware.com/api/v1/meta-templates/bulk-sends/a3f2b8c9-4d5e-6f7a-8b9c-0d1e2f3a4b5c/messages/?status=delivered&page=1&page_size=20" \
    -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```python Python theme={null}
  import requests

  bulk_send_id = "a3f2b8c9-4d5e-6f7a-8b9c-0d1e2f3a4b5c"

  response = requests.get(
      f"https://api.mindosoftware.com/api/v1/meta-templates/bulk-sends/{bulk_send_id}/messages/",
      headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"},
      params={"status": "delivered", "page": 1, "page_size": 20}
  )

  data = response.json()
  print(f"Total mensajes: {data['count']}")
  for msg in data["results"]:
      print(f"  {msg['recipient_phone']}: {msg['status']}")
  ```

  ```javascript JavaScript theme={null}
  const bulkSendId = "a3f2b8c9-4d5e-6f7a-8b9c-0d1e2f3a4b5c";
  const params = new URLSearchParams({
    status: "delivered",
    page: "1",
    page_size: "20"
  });

  const response = await fetch(
    `https://api.mindosoftware.com/api/v1/meta-templates/bulk-sends/${bulkSendId}/messages/?${params}`,
    {
      headers: { "X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  );

  const data = await response.json();
  console.log(`Total mensajes: ${data.count}`);
  data.results.forEach(msg => {
    console.log(`  ${msg.recipient_phone}: ${msg.status}`);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - OK theme={null}
  {
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": 1001,
        "recipient_phone": "+5491112345678",
        "status": "delivered",
        "meta_message_id": "wamid.HBgLNTU0MTE2NzU0Nzg1FQIAERgS...",
        "variables_used": {
          "name": "Juan Perez",
          "code": "ABC123"
        },
        "sent_at": "2025-11-16T21:30:10Z",
        "delivered_at": "2025-11-16T21:30:15Z",
        "read_at": null,
        "error_message": null
      },
      {
        "id": 1002,
        "recipient_phone": "+5491187654321",
        "status": "read",
        "meta_message_id": "wamid.HBgLNTU0MTE2NzU0Nzg1FQIAERgT...",
        "variables_used": {
          "name": "Maria Garcia",
          "code": "DEF456"
        },
        "sent_at": "2025-11-16T21:30:18Z",
        "delivered_at": "2025-11-16T21:30:23Z",
        "read_at": "2025-11-16T21:30:30Z",
        "error_message": null
      },
      {
        "id": 1003,
        "recipient_phone": "+5491199887766",
        "status": "sent",
        "meta_message_id": "wamid.HBgLNTU0MTE2NzU0Nzg1FQIAERgU...",
        "variables_used": {
          "name": "Carlos Lopez",
          "code": "GHI789"
        },
        "sent_at": "2025-11-16T21:30:26Z",
        "delivered_at": null,
        "read_at": null,
        "error_message": null
      }
    ]
  }
  ```

  ```json 404 - No encontrado theme={null}
  {
    "detail": "Not found."
  }
  ```

  ```json 401 - No autenticado theme={null}
  {
    "error": "Este endpoint requiere autenticacion con API Key (header X-API-Key)"
  }
  ```
</ResponseExample>

## Estados de mensajes

| Estado      | Descripción                       |
| ----------- | --------------------------------- |
| `sent`      | Mensaje enviado a la API de Meta  |
| `delivered` | Mensaje entregado al destinatario |
| `read`      | Mensaje leído por el destinatario |
| `failed`    | Error en el envío                 |

<Note>
  Los estados se actualizan automáticamente mediante webhooks de Meta. El estado progresa de `sent` → `delivered` → `read`. Si el envío falla, el estado será `failed` y el campo `error_message` contendrá la descripción del error.
</Note>