# Events

Trackea eventos desde tu aplicacion para segmentacion y automatizaciones. Los eventos se asocian automaticamente a leads — si el email no existe, se crea un lead nuevo.

## Autenticacion

```
Authorization: Bearer sk_proj_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

***

## Endpoints

### POST /v1/events

Trackear un evento individual.

**Request:**

```json
{
  "email": "jane@acme.com",
  "event": "bought_stuff",
  "properties": {
    "item": "shoes",
    "total": 89.99,
    "category": "running"
  },
  "timestamp": "2026-04-10T15:00:00Z"
}
```

| Campo      | Tipo     | Requerido | Descripcion                         |
| ---------- | -------- | --------- | ----------------------------------- |
| email      | string   | Si        | Email del lead                      |
| event      | string   | Si        | Nombre del evento (tu nomenclatura) |
| properties | object   | No        | Propiedades custom del evento       |
| timestamp  | ISO 8601 | No        | Cuando ocurrio (default: ahora)     |

**Response (201):**

```json
{
  "success": true,
  "event_id": "uuid",
  "recipient_id": "uuid",
  "created_lead": true
}
```

`created_lead: true` = el email no existia y se creo un lead nuevo automaticamente.

***

### POST /v1/events/bulk

Trackear hasta 1,000 eventos en una sola peticion.

**Request:**

```json
{
  "events": [
    { "email": "jane@acme.com", "event": "signed_up" },
    { "email": "mike@store.co", "event": "bought_stuff", "properties": { "total": 50 } },
    { "email": "sarah@clinic.com", "event": "appt_done", "properties": { "service": "cleaning" } }
  ]
}
```

**Response (201):**

```json
{
  "success": true,
  "total": 3,
  "created_leads": 1
}
```

***

### GET /v1/events

Listar eventos con filtros.

| Parametro | Tipo     | Default | Descripcion                     |
| --------- | -------- | ------- | ------------------------------- |
| email     | string   | —       | Filtrar por email               |
| event     | string   | —       | Filtrar por nombre de evento    |
| since     | ISO 8601 | —       | Eventos desde esta fecha        |
| until     | ISO 8601 | —       | Eventos hasta esta fecha        |
| page      | number   | 1       | Pagina                          |
| per\_page | number   | 50      | Resultados por pagina (max 200) |

**Ejemplo:** `GET /v1/events?email=jane@acme.com&event=bought_stuff&since=2026-04-01`

**Response (200):**

```json
{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "email": "jane@acme.com",
      "event": "bought_stuff",
      "properties": { "item": "shoes", "total": 89.99 },
      "timestamp": "2026-04-10T15:00:00Z",
      "recipient_id": "uuid",
      "created_at": "2026-04-10T15:00:01Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 142,
    "total_pages": 3
  }
}
```

***

## Ejemplos de Integracion

### Node.js / Express

```javascript
// Tu app envia eventos a RQE cuando algo pasa
app.post("/checkout/complete", async (req, res) => {
  await fetch("https://api.reallyquickemails.com/v1/events", {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_proj_xxx",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      email: req.user.email,
      event: "purchase_completed",
      properties: {
        order_id: req.body.orderId,
        total: req.body.total,
        items: req.body.items.length
      }
    })
  });
});
```

### Python

```python
import requests

def on_appointment_done(appointment):
    requests.post(
        "https://api.reallyquickemails.com/v1/events",
        headers={"Authorization": "Bearer sk_proj_xxx"},
        json={
            "email": appointment.patient_email,
            "event": "appt_done",
            "properties": {
                "service": appointment.service_type,
                "provider": appointment.dentist_name
            }
        }
    )
```

***

## Notas

* Los nombres de eventos son **libres** — usa la nomenclatura que tenga sentido en tu app.
* Si el email no existe como lead, se **crea automaticamente** con datos vacios.
* Los eventos se almacenan indefinidamente y se pueden consultar via GET.
* Rate limit: 10,000 requests/minuto por API key.

## Errores

| Codigo | Significado        |
| ------ | ------------------ |
| 400    | Validacion fallida |
| 401    | API key invalido   |
| 500    | Error interno      |


---

# 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/events.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.