# Activity (Envios)

Consulta el estado de emails enviados — entregas, aperturas, clicks, rebotes y reclamos — por ID o con filtros.

Si necesitas eventos en tiempo real (no en pull), usa [Webhooks](/reallyquickemails-docs/referencia-api/webhooks.md) en su lugar.

## Autenticacion

```
Authorization: Bearer sk_proj_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

***

## Endpoints

### GET /v1/activity/:id

Retorna el detalle de un envio especifico. Usa este endpoint cuando ya conoces el `activity_id` (lo recibes en los webhooks `email.*` o lo guardas al enviar).

**Request:**

```bash
curl https://api.reallyquickemails.com/v1/activity/e5522dde-33c7-4644-bf0a-28ec73830616 \
  -H "Authorization: Bearer sk_proj_..."
```

**Query params:**

| Param   | Valores                         | Descripcion                                                               |
| ------- | ------------------------------- | ------------------------------------------------------------------------- |
| include | `events`, `html`, `events,html` | Incluye el timeline completo de eventos y/o el HTML renderizado del email |

**Response (200):**

```json
{
  "success": true,
  "data": {
    "id": "e5522dde-33c7-4644-bf0a-28ec73830616",
    "created_at": "2026-04-17T16:40:20.623Z",
    "email_type": "automation",
    "campaign_id": null,
    "automation_run_id": "e42c853c-2e28-40cc-aad8-5de7d5395ede",
    "template_id": "bb164399-3ac3-475f-9acb-dc049a20d0d3",
    "message_id": "0100019d9c5098e5-888cac99-cd05-4882-9442-d293c98631fc-000000",
    "subject": "Test",
    "sender_email": "antonia@capitaria.com",
    "sender_name": "Antonia",
    "recipient_primary": "harold@dropout.cl",
    "current_status": "delivered",
    "delivered_at": "2026-04-17T16:40:21.813Z",
    "bounced_at": null,
    "complained_at": null,
    "opened_first_at": "2026-04-17T16:41:55.099Z",
    "clicked_first_at": "2026-04-17T17:30:17.645Z"
  }
}
```

**Campos:**

| Campo              | Tipo            | Descripcion                                                           |
| ------------------ | --------------- | --------------------------------------------------------------------- |
| `id`               | uuid            | `activity_id` — usalo para llamadas posteriores                       |
| `current_status`   | string          | Estado actual: `queued`, `sent`, `delivered`, `bounced`, `complained` |
| `delivered_at`     | ISO8601 \| null | Timestamp de entrega confirmada por SES                               |
| `opened_first_at`  | ISO8601 \| null | Primera apertura (puede haber varias, ver `?include=events`)          |
| `clicked_first_at` | ISO8601 \| null | Primer click (idem)                                                   |
| `bounced_at`       | ISO8601 \| null | Timestamp del rebote (hard o soft)                                    |
| `complained_at`    | ISO8601 \| null | Timestamp cuando el destinatario marco como spam                      |
| `message_id`       | string          | SES MessageId — util para correlacionar con SES logs                  |

**Con `?include=events`** — agrega un array `events` con el timeline completo:

```json
{
  "success": true,
  "data": {
    ... campos base ...,
    "events": [
      {
        "id": "uuid",
        "event_type": "delivered",
        "event_timestamp": "2026-04-17T16:40:21.813Z",
        "user_agent": null,
        "ip_address": null,
        "url_clicked": null,
        "bounce_type": null,
        "bounce_subtype": null,
        "complaint_feedback_type": null,
        "created_at": "2026-04-17T16:40:22.000Z"
      },
      {
        "id": "uuid",
        "event_type": "open",
        "event_timestamp": "2026-04-17T16:41:55.099Z",
        "user_agent": "Mozilla/5.0 ...",
        "ip_address": "66.249.84.135",
        "url_clicked": null,
        ...
      },
      {
        "id": "uuid",
        "event_type": "click",
        "event_timestamp": "2026-04-17T17:30:17.645Z",
        "user_agent": "Mozilla/5.0 ...",
        "ip_address": "190.xx.xx.xx",
        "url_clicked": "https://landing.capitaria.com/masterclass",
        ...
      }
    ]
  }
}
```

`event_type` puede ser: `send`, `delivered`, `bounce`, `complaint`, `reject`, `open`, `click`.

**Con `?include=html`** — agrega el HTML completo renderizado (grande, solo usar cuando se necesite).

**Errores:**

| Codigo | Causa                                              |
| ------ | -------------------------------------------------- |
| 404    | `activity_id` no existe o no pertenece al proyecto |
| 401    | API key invalida                                   |

***

### GET /v1/activity

Lista envios con filtros. Util para jalar datasets de entrenamiento (modelo NBA, scoring, etc.).

**Request:**

```bash
curl "https://api.reallyquickemails.com/v1/activity?email=jane@acme.com&status=delivered&since=2026-04-01" \
  -H "Authorization: Bearer sk_proj_..."
```

**Query params:**

| Param               | Tipo    | Descripcion                                               |
| ------------------- | ------- | --------------------------------------------------------- |
| `email`             | string  | Filtra por `recipient_primary` (se normaliza a lowercase) |
| `status`            | string  | `sent`, `delivered`, `bounced`, `complained`              |
| `automation_run_id` | uuid    | Todos los emails generados por un enrollment especifico   |
| `campaign_id`       | uuid    | Todos los emails enviados como parte de una campana       |
| `since`             | ISO8601 | `created_at >= since`                                     |
| `until`             | ISO8601 | `created_at <= until`                                     |
| `page`              | int     | Default 1                                                 |
| `per_page`          | int     | Default 50, max 200                                       |

**Caso tipico con `automation_run_id`:** despues de llamar `POST /v1/automations/:id/enroll`, guardas el `automation_run_id` devuelto. Mas tarde, cuando el flujo haya ejecutado N emails, podes jalarlos todos con:

```bash
curl "https://api.reallyquickemails.com/v1/activity?automation_run_id=<RUN_ID>" \
  -H "Authorization: Bearer sk_proj_..."
```

**Response (200):**

```json
{
  "success": true,
  "data": [
    { "id": "...", "subject": "...", "current_status": "delivered", ... },
    { "id": "...", "subject": "...", "current_status": "opened", ... }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1423,
    "total_pages": 29
  }
}
```

Orden: `created_at DESC` (mas reciente primero).

***

## Pull vs Webhook

* **Pull** (este endpoint): tu sistema consulta cuando necesite. Simple de integrar, pero con latencia — los `opened_first_at` pueden tardar hasta \~5s en aparecer despues de que el destinatario abre el email (buffer interno).
* **Webhook**: eventos push en tiempo real cuando ocurren. Mejor para triggers reactivos. Ver [Webhooks](/reallyquickemails-docs/referencia-api/webhooks.md).

Para entrenamiento de modelos (batch), pull es el patron correcto. Para automatizaciones reactivas (NBA en tiempo real), usa webhooks.

## Rate limits

* 10,000 requests/minuto por API key.
* Max 200 resultados por pagina en `GET /v1/activity`.


---

# 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://reallyquickemails.gitbook.io/reallyquickemails-docs/referencia-api/activity.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.