# Exportación asíncrona de estadísticas de mensajes

`exportMessagesStatistics` exporta el historial de mensajes y las estadísticas a un archivo CSV en el servidor. Utilícelo para extracciones grandes o de toda la cuenta que [`messages:list`](/es/developer/api-reference/statistics-api/message-statistics-api/#messageslist) no puede manejar.

## Cuándo usar la exportación en lugar de messages:list

Utilice `messages:list` para búsquedas en vivo y paginadas de un período delimitado. Utilice `exportMessagesStatistics` cuando el resultado excedería el límite de paginación profunda de `messages:list` (`page × per_page > 100000`), o cuando el objetivo es un único archivo descargable en lugar de un JSON paginado. La exportación no tiene límite en `date_range` o en el número de filas, porque transmite el resultado a un archivo en el disco en lugar de mantenerlo en una sola respuesta.

<span id="how-the-export-flow-works" />

## Cómo funciona el flujo de exportación

1.  Llame a [`export`](#export) con los mismos filtros que `messages:list`. La respuesta devuelve un identificador de tarea `uid` inmediatamente, antes de que se genere el archivo.
2.  Sondee [`status`](#status) con ese `uid` hasta que informe `STATUS_SUCCESS` (o `STATUS_FAILED`).
3.  Llame a [`result`](#result) con el mismo `uid` para obtener el `file` generado y una `file_url` lista para usar.
4.  [Descargue](#download) el archivo. Utilice `file_url` tal cual, o consulte [`result`](#result) para construir la URL a partir de `file` si esta llegó vacía.

Utilice [`lastTasks`](#lasttasks) para buscar tareas de exportación recientes para una aplicación, y [`delete`](#delete) para cancelar una tarea o eliminar su archivo antes de tiempo.

## Métodos

El ciclo de vida de la exportación tiene cinco métodos, más un punto de conexión de descarga simple:

| Método | Descripción |
|---|---|
| [`exportMessagesStatistics/export`](#export) | Pone en cola una exportación y devuelve un `uid` de tarea. |
| [`exportMessagesStatistics/status`](#status) | Comprueba el progreso de la tarea. |
| [`exportMessagesStatistics/result`](#result) | Devuelve el nombre del archivo generado una vez que la tarea ha finalizado. |
| [`exportMessagesStatistics/lastTasks`](#lasttasks) | Enumera las tareas de exportación recientes para una aplicación. |
| [`exportMessagesStatistics/delete`](#delete) | Cancela una tarea o elimina su archivo antes de que expire el período de retención. |
| [Descargar](#download) | Descarga el archivo CSV generado por su nombre. |

### export

Pone en cola una exportación del historial de mensajes y devuelve un identificador de tarea de inmediato.

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export`

##### Cabeceras

La solicitud necesita un token de la API del servidor:

| Nombre | Requerido | Descripción |
|---|---|---|
| `Authorization` | Sí | [Token de la API del servidor](/es/developer/api-reference/api-access-token/#server-api-token). Debe proporcionarse en el siguiente formato: `Authorization: Api <Server Key>`. |

##### Parámetros del cuerpo de la solicitud

El cuerpo de la solicitud acepta los siguientes campos:

| Nombre | Requerido | Tipo | Descripción |
|---|---|---|---|
| `type` | Sí | String | Debe ser <code>"TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"</code>. |
| <code>export_messages<wbr/>_v2</code> | Sí | Object | Parámetros de exportación, descritos a continuación. |
| <code>export_messages<wbr/>_v2.application<wbr/>_code</code> | Ver nota | String | [Código de aplicación de Pushwoosh](/es/developer/api-reference/api-identifiers/#application-code). Requerido si no se establece `app_group_code`. |
| <code>export_messages<wbr/>_v2.app<wbr/>_group_code</code> | Ver nota | String | Código de grupo de aplicaciones, exporta a través de cada aplicación del grupo. Requerido si no se establece `application_code`. |
| <code>export_messages<wbr/>_v2.search</code> | No | String | Búsqueda de texto libre en el título y contenido del mensaje. |
| <code>export_messages<wbr/>_v2.filters</code> | No | Object | Filtros de mensajes, descritos a continuación. Omitir para exportar todo el historial de la cuenta. |
| <code>export_messages<wbr/>_v2.properties</code> | No | Array | Columnas a incluir en el CSV, descritas a continuación. |

`export_messages_v2.filters` acepta:

| Nombre <div style="width:150px"></div> | Tipo | Descripción |
|---|---|---|
| `statuses` | Array | Estados de los mensajes a incluir. <details><summary>Valores posibles</summary><ul><li><code>"MESSAGE_STATUS_CANCELED"</code></li><li><code>"MESSAGE_STATUS_CREATING"</code></li><li><code>"MESSAGE_STATUS_DONE"</code></li><li><code>"MESSAGE_STATUS_FAIL"</code></li><li><code>"MESSAGE_STATUS_PENDING"</code></li><li><code>"MESSAGE_STATUS_PROCESSING"</code></li><li><code>"MESSAGE_STATUS_WAITING"</code></li></ul></details> |
| `platforms` | Array | [Códigos de plataforma](/es/developer/api-reference/messages-api/api-prerequisites/#platforms) (numéricos, p. ej., `1` para iOS), no las cadenas de nombres de plataforma utilizadas por `messages:list`. |
| `sent_date` | Object | Período de informe filtrado por fecha de envío: `{"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}`. |
| `created_date` | Object | Período de informe filtrado por fecha de creación del mensaje, mismo formato que `sent_date`. |
| `created_via` | Array | Origen del mensaje. <details><summary>Valores posibles</summary><ul><li><code>"AB_TEST"</code></li><li><code>"API"</code></li><li><code>"AUTO_PUSH"</code></li><li><code>"CP"</code></li><li><code>"CSV"</code></li><li><code>"CUSTOMER_JOURNEY"</code></li><li><code>"EMAIL_API"</code></li><li><code>"EMAIL_CP"</code></li><li><code>"GEO_ZONE"</code></li><li><code>"PUSH_ON_EVENT"</code></li><li><code>"RSS"</code></li><li><code>"SYSTEM"</code></li></ul></details> |
| `segments` | Array | [Códigos de filtro](/es/developer/api-reference/api-identifiers/#segment--filter-code) a los que se envió el mensaje. |
| `campaigns` | Array | [Códigos de campaña](/es/developer/api-reference/api-identifiers/#campaign-code). A diferencia de `messages:list`, este toma una lista, no un único código. |
| `message_id` | String (uint64) | Un único ID de mensaje numérico, entre comillas. A diferencia de `messages:list`, la exportación toma un ID, no un array. |
| `message_code` | String | Un único [código de mensaje](/es/developer/api-reference/api-identifiers/#message-code). |

`export_messages_v2.properties` selecciona qué columnas contiene el CSV.

<details>
<summary>Valores posibles</summary>

- `"EXPORT_MESSAGE_PROPERTY_ID"`
- `"EXPORT_MESSAGE_PROPERTY_TIMESTAMP"`
- `"EXPORT_MESSAGE_PROPERTY_CONTENT"`
- `"EXPORT_MESSAGE_PROPERTY_TITLE"`
- `"EXPORT_MESSAGE_PROPERTY_CAMPAIGN_NAME"`
- `"EXPORT_MESSAGE_PROPERTY_APPLICATIONS"`
- `"EXPORT_MESSAGE_PROPERTY_STATUS"`
- `"EXPORT_MESSAGE_PROPERTY_PLATFORMS"`
- `"EXPORT_MESSAGE_PROPERTY_SOURCE"`
- `"EXPORT_MESSAGE_PROPERTY_FILTER"`
- `"EXPORT_MESSAGE_PROPERTY_SUBSCRIPTION_SEGMENTS"`
- `"EXPORT_MESSAGE_PROPERTY_SENT"`
- `"EXPORT_MESSAGE_PROPERTY_OPENED"`
- `"EXPORT_MESSAGE_PROPERTY_ERRORS"`
- `"EXPORT_MESSAGE_PROPERTY_RECIPIENTS"`
- `"EXPORT_MESSAGE_PROPERTY_DELIVERED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_DELIVERED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_OPENED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_CLICKS"`
- `"EXPORT_MESSAGE_PROPERTY_CLICKS"`
- `"EXPORT_MESSAGE_PROPERTY_UNSUBSCRIBED"`

</details>

<Aside type="caution" title="properties no es solo un filtro">
Una propiedad que no figure en `properties` no aparecerá en el archivo en absoluto, incluidas las columnas base (ID, fecha de envío, contenido, estado). Dejar `properties` vacío produce un CSV sin columnas. Enumere todas las columnas que la exportación debe contener, no solo las métricas que desea agregar sobre un conjunto predeterminado.
</Aside>

##### Solicitud de ejemplo

```json
{
  "type": "TASK_TYPE_EXPORT_MESSAGES_V2",
  "export_messages_v2": {
    "application_code": "XXXXX-XXXXX",
    "filters": {
      "created_date": {
        "date_from": "2026-01-01",
        "date_to": "2026-06-30"
      },
      "statuses": ["MESSAGE_STATUS_DONE"],
      "platforms": [1, 3]
    },
    "properties": [
      "EXPORT_MESSAGE_PROPERTY_ID",
      "EXPORT_MESSAGE_PROPERTY_TIMESTAMP",
      "EXPORT_MESSAGE_PROPERTY_STATUS",
      "EXPORT_MESSAGE_PROPERTY_PLATFORMS",
      "EXPORT_MESSAGE_PROPERTY_SENT",
      "EXPORT_MESSAGE_PROPERTY_OPENED"
    ]
  }
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "uid": "177458"
}
```
</TabItem>
<TabItem label="401: Token de acceso a la API incorrecto">
```json
{
  "error": "account not found"
}
```
</TabItem>
</Tabs>

### status

Devuelve el progreso de una tarea de exportación.

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/status`

##### Parámetros del cuerpo de la solicitud

Pase el identificador de tarea devuelto por `export`:

| Nombre | Requerido | Tipo | Descripción |
|---|---|---|---|
| `uid` | Sí | String (int64) | Identificador de tarea de la respuesta de `export`, p. ej., `"177458"`. |

##### Solicitud de ejemplo

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "status": "STATUS_SUCCESS",
  "progress": 1
}
```
</TabItem>
</Tabs>

`status` es uno de `"STATUS_PENDING"`, `"STATUS_SUCCESS"`, o `"STATUS_FAILED"`. `progress` es una fracción entre `0` y `1`; sondee `status` hasta que alcance `"STATUS_SUCCESS"` antes de llamar a `result`.

### result

Devuelve el nombre del archivo generado una vez que la tarea ha finalizado.

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/result`

##### Parámetros del cuerpo de la solicitud

Pase el mismo identificador de tarea devuelto por `export`:

| Nombre | Requerido | Tipo | Descripción |
|---|---|---|---|
| `uid` | Sí | String (int64) | Identificador de tarea de la respuesta de `export`, p. ej., `"177458"`. |

##### Solicitud de ejemplo

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv",
    "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}
```
</TabItem>
</Tabs>

Llamar a `result` antes de que `status` informe `"STATUS_SUCCESS"` devuelve un resultado vacío. `file_url` es un enlace listo para usar al [punto de conexión de descarga](#download) en el centro de datos correcto para la cuenta; úselo tal cual en lugar de construir la URL a partir de `file` usted mismo. `file_url` está vacío si el centro de datos de la cuenta no tiene una URL base configurada. En ese caso, solo puede recurrir a construir la URL a partir de `file` si la cuenta está en el centro de datos predeterminado `app.pushwoosh.com`; una cuenta en otro centro de datos o un dominio de marca blanca no tiene forma de derivar el host correcto solo a partir de `file`.

### lastTasks

Enumera las tareas de exportación recientes para una aplicación, de la más reciente a la más antigua.

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/lastTasks`

##### Parámetros del cuerpo de la solicitud

Cada parámetro es un filtro opcional; omítalos todos para enumerar todas las tareas a las que el token tiene acceso:

| Nombre | Requerido | Tipo | Descripción |
|---|---|---|---|
| `application` | No | String | [Código de aplicación de Pushwoosh](/es/developer/api-reference/api-identifiers/#application-code). Omitir para listar tareas en todas las aplicaciones a las que el token tiene acceso. |
| `types` | No | Array | Restringir a tipos de tareas específicos. Use <code>["TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"]</code> para ver solo las exportaciones de mensajes. |
| `campaign` | No | String | Filtrar por [código de campaña](/es/developer/api-reference/api-identifiers/#campaign-code). |
| `message_id` | No | String (uint64) | Filtrar por un único ID de mensaje numérico, entre comillas. |
| `message_code` | No | String | Filtrar por un único [código de mensaje](/es/developer/api-reference/api-identifiers/#message-code). |
| `limit` | No | Integer | Número máximo de tareas a devolver. |
| `timestamp_from` | No | String | Solo devolver tareas creadas después de esta marca de tiempo (RFC 3339). |

<Aside type="note">
Las tareas se conservan durante 30 días, independientemente de si su archivo ya ha sido eliminado tras el período de retención de 7 días. `lastTasks` aún puede mostrar una tarea cuyo `result` ya no se resuelve en un archivo descargable.
</Aside>

##### Solicitud de ejemplo

```json
{
  "application": "XXXXX-XXXXX",
  "types": ["TASK_TYPE_EXPORT_MESSAGES_V2"],
  "limit": 10
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "tasks": [
    {
      "id": "177458",
      "timestamp": "2026-08-13T12:00:00Z",
      "status": "STATUS_SUCCESS",
      "requested_by_user": "user@example.com",
      "export_messages_v2": {
        "application_code": "XXXXX-XXXXX"
      },
      "export_messages_v2_result": {
        "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv",
        "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
      }
    }
  ]
}
```
</TabItem>
</Tabs>

### delete

Elimina una tarea y su archivo antes de que expire el período de retención de 7 días.

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/delete`

##### Parámetros del cuerpo de la solicitud

Pase el identificador de tarea devuelto por `export`:

| Nombre | Requerido | Tipo | Descripción |
|---|---|---|---|
| `uid` | Sí | String (int64) | Identificador de tarea de la respuesta de `export`, p. ej., `"177458"`. |

##### Solicitud de ejemplo

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{}
```
</TabItem>
</Tabs>

<span id="download" />

### Descargar

Descarga el archivo CSV generado por `result`, por su nombre.

`GET` `https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/<file>`

##### Cabeceras

Autentícate de la misma manera que los otros métodos, o confía en una sesión activa del Panel de Control:

| Nombre | Requerido | Descripción |
|---|---|---|
| `Authorization`| Sí | [Token de la API del servidor](/es/developer/api-reference/api-access-token/#server-api-token), en el mismo formato que los otros métodos `exportMessagesStatistics`: `Authorization: Api <Server Key>` (el esquema `Api` no distingue entre mayúsculas y minúsculas). Una solicitud sin cabecera `Authorization` y sin una sesión iniciada en el Panel de Control obtiene un `401 Unauthorized`. |

Reemplace `<file>` con el valor exacto de `file` de la respuesta de `result`, por ejemplo:

```
https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv
```

<Aside type="caution">
Construir esta URL manualmente solo funciona para cuentas que inician sesión en `app.pushwoosh.com`, porque el host no se puede deducir solo a partir de `file`. Usa en su lugar el `file_url` de [`result`](#result) o [`lastTasks`](#lasttasks), porque ya apunta al host del centro de datos de la cuenta. Consulta [`result`](#result) para saber qué hacer si `file_url` llega vacío.
</Aside>

El archivo es un CSV que contiene las columnas seleccionadas en `properties`. Permanece disponible durante 7 días después de que finalice la exportación, luego el trabajo de limpieza lo elimina y la URL deja de resolverse.

### Exportación de destinatarios de un mensaje

Los mismos métodos `export`, `status`, `result`, `lastTasks`, `delete` y `download` también exportan los destinatarios individuales de un mensaje. Use `"type": "TASK_TYPE_EXPORT_MESSAGE_RECIPIENTS"` y un objeto `export_message_recipients` en lugar de `export_messages_v2`.

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export`

<Aside type="note" title="No es el Holdout Split de Customer Journey">
Esto exporta los destinatarios que un **mensaje** excluyó. Un punto [Holdout Split](/es/product/customer-journey/journey-elements/flow-controls/holdout-split/) de Customer Journey es un mecanismo distinto. Excluye usuarios del resto de un *journey* antes de que se envíe cualquier mensaje, y su tarea `exportJourneyPointUsers` (los mismos métodos `export`/`status`/`result`, con otro `type`) informa de la pertenencia a ramas, no de los resultados de envío.
</Aside>

##### Campos de la solicitud export_message_recipients

| Nombre <div style="width:150px"></div> | Requerido | Tipo    | Descripción                                                                                          |
|---------------------------------------|----------|---------|-------------------------------------------------------------------------------------------------------|
| `message_id`                          | Véase la nota | String (uint64) | Un único ID numérico de mensaje. Obligatorio si no se define `campaign`.                              |
| `campaign`                             | Véase la nota | String  | Un único [código de campaña](/es/developer/api-reference/api-identifiers/#campaign-code). Obligatorio si no se define `message_id`. Si se definen ambos, se limita a las filas del mensaje dentro de esa campaña. |
| `application`                         | Sí      | String  | [Código de aplicación](/es/developer/api-reference/api-identifiers/#application-code) al que pertenece el mensaje. |
| `type`                                | Sí      | String  | Qué destinatarios exportar. Uno de `"sends"`, `"deliveries"`, `"opens"`, `"holdout"` (véase más abajo).    |
| `date_from` / `date_to`               | No       | String (date-time) | Limita las filas a esta ventana. Omita ambos para obtener todo el historial del mensaje.                  |

Si se omiten tanto `message_id` como `campaign`, o se omite `application`, la solicitud falla con un error que nombra el campo que falta. Un `message_id` de otra cuenta falla con `NotFound: message not found`, comprobado antes de ejecutar la exportación. Un `message_id` o `campaign` que pertenece a otra aplicación de la misma cuenta no se rechaza. No coincide con ninguna fila, y el CSV se descarga solo con la fila de encabezado.

`type` selecciona el conjunto de destinatarios:

| Valor         | Filas devueltas                                                                                                    |
|----------------|--------------------------------------------------------------------------------------------------------------------|
| `"sends"`      | Todos los destinatarios para los que se aceptó el mensaje.                                                                     |
| `"deliveries"` | Destinatarios de `sends` cuya entrega confirmó el proveedor.                                                    |
| `"opens"`      | Destinatarios de `sends` que abrieron el mensaje.                                                                   |
| `"holdout"`    | Destinatarios que este mensaje excluyó, no cualquier otro mensaje. No se les envió nada. Tanto un [grupo de control](/es/product/audience-data-and-segmentation/control-groups/) de toda la cuenta como el `holdout_percentage` propio del mensaje (véase [Messaging API v2](/es/developer/api-reference/messaging-api-v2/notify/)) pueden producir esta fila. |

##### Ejemplo de solicitud

```json
{
  "type": "TASK_TYPE_EXPORT_MESSAGE_RECIPIENTS",
  "export_message_recipients": {
    "message_id": "22875465358",
    "application": "6D382-5ADFE",
    "type": "holdout",
    "date_from": "2026-08-01T00:00:00Z",
    "date_to": "2026-09-30T00:00:00Z"
  }
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "uid": "29820"
}
```
</TabItem>
</Tabs>

Consulte [`status`](#status) y llame a [`result`](#result) igual que en una exportación del historial de mensajes. `result` devuelve `export_message_recipients_result` en lugar de `export_messages_v2_result`:

```json
{
  "export_message_recipients_result": {
    "file": "Message_22875465358_Holdout_29820-fe5d8ba468df25b7.csv",
    "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Message_22875465358_Holdout_29820-fe5d8ba468df25b7.csv"
  }
}
```

`sends`, `deliveries` y `opens` comparten un mismo conjunto de columnas: `hwid, user_id, platform, send_timestamp, delivery_timestamp, open_timestamp, send_error, pae, send_status`. `pae` es `false` cuando la plataforma aceptó el envío pero no mostró ninguna alerta visible para él, el mismo caso que cuenta [`unshowable_sends`](/es/developer/api-reference/statistics-api/message-statistics-api/) en las estadísticas agregadas. `holdout` tiene su propio conjunto, más corto: `hwid, user_id, platform, holdout_timestamp`.