# API Publica v1

La API publica v1 expone endpoints autenticados mediante Secret Key para integraciones externas. Los endpoints bajo `/v1/` validan la clave de API y reenvian la solicitud a la funcion Edge de Supabase correspondiente, donde se aplica la logica de negocio (supresion, CAN-SPAM, renderizado de plantillas).

**Base URL:** `https://api.reallyquickemails.com`

***

## Autenticacion

Todos los endpoints de la API publica requieren autenticacion mediante Bearer token con una clave de proyecto:

```
Authorization: Bearer sk_proj_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Las claves de proyecto (`sk_proj_...`) se generan desde el panel de administracion del proyecto. Si la clave es invalida o no se proporciona, el servidor responde con `401 Unauthorized`.

### Respuesta de error de autenticacion

```json
{
  "success": false,
  "error": "Unauthorized: Invalid or missing API key"
}
```

***

## POST /v1/send-email

Envia un correo electronico individual. Este endpoint valida la API Key y reenvia la solicitud al pipeline interno de envio (BullMQ → SES) aplicando la logica correspondiente a este flujo: validacion de remitente verificado, lista de supresion y tracking. Los headers de unsubscribe / footer CAN-SPAM se aplican automaticamente solo en envios de campana; para envios individuales podes pasarlos via `custom_headers` en el endpoint interno o usar `/v1/send-batch`.

### Headers

| Header          | Tipo   | Requerido | Descripcion          |
| --------------- | ------ | --------- | -------------------- |
| `Authorization` | string | Si        | `Bearer sk_proj_...` |
| `Content-Type`  | string | Si        | `application/json`   |

### Request Body

| Campo             | Tipo                | Requerido | Descripcion                                                                                                                   |
| ----------------- | ------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `recipient_email` | string \| string\[] | Si        | Direccion(es) del destinatario. Acepta string (1 destinatario) o array (max 50). Para volúmenes mayores usa `/v1/send-batch`. |
| `sender_email`    | string              | Si        | Direccion del remitente (dominio verificado).                                                                                 |
| `sender_name`     | string              | No        | Nombre visible del remitente. Si se omite, el inbox muestra solo `sender_email`.                                              |
| `html_body`       | string              | Si        | Contenido HTML del correo.                                                                                                    |
| `text_body`       | string              | No        | Versión plain text del correo (multipart fallback). Recomendado para mejorar deliverability y accessibility.                  |
| `subject`         | string              | No        | Asunto del correo.                                                                                                            |
| `cc`              | string \| string\[] | No        | Direccion(es) en copia. Max 10.                                                                                               |
| `bcc`             | string \| string\[] | No        | Direccion(es) en copia oculta. Max 10.                                                                                        |
| `attachments`     | array               | No        | Lista de adjuntos (max 10, max 10MB cada uno). Estructura: `{ filename, url \| content (base64), contentType? }`.             |

### Ejemplo simple

```bash
curl -X POST https://api.reallyquickemails.com/v1/send-email \
  -H "Authorization: Bearer sk_proj_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_email": "usuario@ejemplo.com",
    "sender_email": "hola@miapp.com",
    "sender_name": "Mi Empresa",
    "subject": "Bienvenido a nuestra plataforma",
    "html_body": "<h1>Bienvenido!</h1><p>Gracias por registrarte.</p>"
  }'
```

### Ejemplo con múltiples destinatarios + cc + adjunto

```bash
curl -X POST https://api.reallyquickemails.com/v1/send-email \
  -H "Authorization: Bearer sk_proj_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_email": ["a@empresa.com", "b@empresa.com"],
    "cc": "supervisor@empresa.com",
    "sender_email": "notificaciones@miapp.com",
    "sender_name": "Mi Empresa",
    "subject": "Reporte diario",
    "html_body": "<h1>Reporte</h1><p>Adjunto encontrarás el detalle.</p>",
    "attachments": [
      {
        "filename": "reporte.pdf",
        "url": "https://storage.miapp.com/reportes/2026-04-28.pdf",
        "contentType": "application/pdf"
      }
    ]
  }'
```

### Respuesta exitosa (200)

```json
{
  "message": "Email sent successfully",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

### Respuesta cuando el destinatario esta suprimido (200)

```json
{
  "message": "Email skipped — recipient is suppressed",
  "skipped": true,
  "suppression_reason": "bounce",
  "recipient": "usuario@ejemplo.com"
}
```

### Codigos de Error

| Codigo | Descripcion                                                         |
| ------ | ------------------------------------------------------------------- |
| `400`  | `Missing required fields: recipient_email, sender_email, html_body` |
| `401`  | API Key invalida o no proporcionada.                                |
| `500`  | Error interno del servidor.                                         |

***

## POST /v1/send-template-email

Envia un correo electronico utilizando una plantilla pre-configurada con sustitucion de variables. Ideal para integraciones donde el contenido HTML se gestiona desde el editor de ReallyQuickEmails y tu sistema solo proporciona los datos dinamicos.

### Headers

| Header          | Tipo   | Requerido | Descripcion          |
| --------------- | ------ | --------- | -------------------- |
| `Authorization` | string | Si        | `Bearer sk_proj_...` |
| `Content-Type`  | string | Si        | `application/json`   |

### Request Body

| Campo                  | Tipo   | Requerido | Descripcion                                                         |
| ---------------------- | ------ | --------- | ------------------------------------------------------------------- |
| `template_id`          | string | Si\*      | UUID de la plantilla.                                               |
| `template_internal_id` | number | Si\*      | ID interno de la plantilla (alternativa a `template_id`).           |
| `recipient_email`      | string | Si        | Direccion de correo del destinatario.                               |
| `sender_email`         | string | Si        | Direccion de correo del remitente (dominio verificado).             |
| `subject`              | string | No        | Asunto del correo. Si no se proporciona, se usa el de la plantilla. |
| `variables`            | object | No        | Variables para sustitucion en la plantilla.                         |

> \*Debes enviar `template_id` O `template_internal_id` (uno de los dos).

### Ejemplo con template UUID

```bash
curl -X POST https://api.reallyquickemails.com/v1/send-template-email \
  -H "Authorization: Bearer sk_proj_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "550e8400-e29b-41d4-a716-446655440000",
    "recipient_email": "nuevo.usuario@ejemplo.com",
    "sender_email": "onboarding@miapp.com",
    "variables": {
      "nombre": "Carlos",
      "plan": "Pro",
      "trial_days": 14,
      "dashboard_url": "https://miapp.com/dashboard"
    }
  }'
```

### Ejemplo con template internal ID

Cada template tiene un ID interno auto-incrementado dentro del proyecto. Util para integraciones que prefieren IDs numericos:

```bash
curl -X POST https://api.reallyquickemails.com/v1/send-template-email \
  -H "Authorization: Bearer sk_proj_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "template_internal_id": 5,
    "recipient_email": "cliente@ejemplo.com",
    "sender_email": "noreply@miapp.com",
    "variables": {
      "nombre": "Maria"
    }
  }'
```

### Respuesta exitosa (200)

```json
{
  "message": "Email sent successfully",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "template_id": "550e8400-e29b-41d4-a716-446655440000",
  "template_internal_id": 5,
  "variables_used": ["nombre", "plan", "trial_days", "dashboard_url"],
  "used_cached_html": true
}
```

### Respuesta cuando el destinatario esta suprimido (200)

Si el destinatario se ha dado de baja o ha rebotado, el email se omite automaticamente:

```json
{
  "message": "Email skipped — recipient is suppressed",
  "skipped": true,
  "suppression_reason": "unsubscribed",
  "recipient": "cliente@ejemplo.com"
}
```

### Codigos de Error

| Codigo | Descripcion                                                                          |
| ------ | ------------------------------------------------------------------------------------ |
| `400`  | `Missing required fields: recipient_email, sender_email, html_body (or template_id)` |
| `400`  | `template_internal_id requires valid project context`                                |
| `401`  | API Key invalida o no proporcionada.                                                 |
| `404`  | Plantilla no encontrada para el proyecto asociado a la API Key.                      |
| `500`  | Error interno del servidor.                                                          |

***

## Reply-To Automatico (Inbound Email)

Todos los correos enviados via la API publica incluyen automaticamente un header `Reply-To` con el nombre del remitente:

```
Reply-To: "Mi Empresa" <r-x7K9mP2q@rqe.inbound.reallyquickemails.com>
```

Los clientes de correo (Gmail, Outlook, Apple Mail) muestran el **nombre del remitente**, no la direccion tecnica. Cuando el destinatario responde, la respuesta se enruta automaticamente a ReallyQuickEmails y se asocia al hilo de conversacion original.

Este comportamiento es automatico y no requiere configuracion. Para recibir notificaciones de respuestas entrantes, configura un [webhook de inbound email](/reallyquickemails-docs/referencia-api/webhooks.md#post-apiinboundses).

***

## POST /v1/send-batch

Envia correos masivos en un solo request. Ideal para newsletters, promociones y notificaciones a multiples destinatarios. Maximo **12,500 destinatarios** por llamada.

Cada destinatario puede tener variables personalizadas a traves del campo `data`.

### Headers

| Header          | Tipo   | Requerido | Descripcion          |
| --------------- | ------ | --------- | -------------------- |
| `Authorization` | string | Si        | `Bearer sk_proj_...` |
| `Content-Type`  | string | Si        | `application/json`   |

### Request Body

| Campo          | Tipo   | Requerido | Descripcion                                             |
| -------------- | ------ | --------- | ------------------------------------------------------- |
| `sender`       | string | Si        | Direccion de correo del remitente (dominio verificado). |
| `senderName`   | string | No        | Nombre visible del remitente.                           |
| `subject`      | string | Si\*      | Asunto del correo. Requerido si no se usa `templateId`. |
| `html`         | string | Si\*      | Contenido HTML. Requerido si no se usa `templateId`.    |
| `templateId`   | string | Si\*      | UUID del template. Alternativa a `subject` + `html`.    |
| `email_type`   | string | No        | Tipo de correo. Default: `"marketing"`.                 |
| `scheduled_at` | string | No        | Fecha ISO 8601 para envio programado.                   |
| `recipients`   | array  | Si        | Lista de destinatarios (maximo 12,500).                 |

> \*Debes enviar `templateId` O ambos `subject` + `html`.

**Estructura de cada recipient:**

| Campo   | Tipo   | Requerido | Descripcion                            |
| ------- | ------ | --------- | -------------------------------------- |
| `email` | string | Si        | Direccion de correo del destinatario.  |
| `data`  | object | No        | Variables personalizadas (Handlebars). |

### Ejemplo con HTML directo

```bash
curl -X POST https://api.reallyquickemails.com/v1/send-batch \
  -H "Authorization: Bearer sk_proj_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "noreply@tudominio.com",
    "senderName": "Mi Empresa",
    "subject": "Oferta especial para ti, {nombre}",
    "html": "<h1>Hola {nombre}!</h1><p>Tenemos una oferta especial en {producto}.</p>",
    "recipients": [
      {
        "email": "juan@ejemplo.com",
        "data": { "nombre": "Juan", "producto": "Plan Pro" }
      },
      {
        "email": "maria@ejemplo.com",
        "data": { "nombre": "Maria", "producto": "Plan Business" }
      }
    ]
  }'
```

### Ejemplo con template

```bash
curl -X POST https://api.reallyquickemails.com/v1/send-batch \
  -H "Authorization: Bearer sk_proj_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "noreply@tudominio.com",
    "senderName": "Mi Empresa",
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "recipients": [
      { "email": "juan@ejemplo.com", "data": { "nombre": "Juan" } },
      { "email": "maria@ejemplo.com", "data": { "nombre": "Maria" } }
    ]
  }'
```

### Ejemplo con envio programado

```bash
curl -X POST https://api.reallyquickemails.com/v1/send-batch \
  -H "Authorization: Bearer sk_proj_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "noreply@tudominio.com",
    "subject": "Newsletter semanal",
    "html": "<h1>Newsletter</h1><p>Las noticias de esta semana...</p>",
    "scheduled_at": "2026-03-25T10:00:00Z",
    "recipients": [
      { "email": "sub1@ejemplo.com" },
      { "email": "sub2@ejemplo.com" }
    ]
  }'
```

### Respuesta exitosa (200)

```json
{
  "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "total": 2,
  "queued": 2,
  "scheduled": false,
  "scheduled_for": null,
  "activities": [
    { "email": "juan@ejemplo.com", "activity_id": "uuid-1" },
    { "email": "maria@ejemplo.com", "activity_id": "uuid-2" }
  ]
}
```

| Campo           | Tipo           | Descripcion                                                      |
| --------------- | -------------- | ---------------------------------------------------------------- |
| `batch_id`      | string         | UUID unico del batch para referencia.                            |
| `total`         | number         | Cantidad total de destinatarios.                                 |
| `queued`        | number         | Cantidad de emails encolados para envio.                         |
| `scheduled`     | boolean        | `true` si el batch fue programado para envio futuro.             |
| `scheduled_for` | string \| null | Fecha UTC de envio programado, o `null` si es inmediato.         |
| `activities`    | array          | Lista con `email` y `activity_id` por destinatario para rastreo. |

El `activity_id` de cada destinatario permite rastrear el estado de entrega mediante webhooks.

### Codigos de Error

| Codigo | Descripcion                                            |
| ------ | ------------------------------------------------------ |
| `400`  | `sender is required`                                   |
| `400`  | `subject or templateId is required`                    |
| `400`  | `html or templateId is required`                       |
| `400`  | `recipients array is required and must not be empty`   |
| `400`  | `Too many recipients: X. Maximum is 12,500 per batch.` |
| `400`  | `recipients[N].email is required`                      |
| `401`  | API Key invalida o no proporcionada.                   |
| `500`  | `Failed to process batch`                              |

### Limites

| Limite                      | Valor   |
| --------------------------- | ------- |
| Destinatarios por request   | 12,500  |
| Emails por dia (SES)        | 106,000 |
| Emails por segundo (SES)    | 16      |
| Emails por mes (plataforma) | 500,000 |

> **Tip:** Para envios superiores a 12,500 destinatarios, usa multiples llamadas o crea una campana desde el Dashboard de ReallyQuickEmails que maneja automaticamente lotes, rate limiting y reintentos.

***

## APIs de Gestion de Datos

Ademas de los endpoints de envio, la API v1 incluye endpoints para gestionar leads, eventos, tags y atributos. Consulta la documentacion completa en:

* [**Leads API**](/reallyquickemails-docs/referencia-api/leads.md) — CRUD de leads, segmentos, tags y atributos
* [**Events API**](/reallyquickemails-docs/referencia-api/events.md) — Tracking de eventos custom desde tus apps

### Resumen rapido

| Categoria     | Endpoint                                   | Descripcion                                        |
| ------------- | ------------------------------------------ | -------------------------------------------------- |
| **Leads**     | `POST /v1/leads`                           | Crear/actualizar leads (single o bulk hasta 1,000) |
|               | `GET /v1/leads`                            | Listar con paginacion y filtros                    |
|               | `GET /v1/leads/:id`                        | Detalle de un lead con segmentos                   |
|               | `PUT /v1/leads/:id`                        | Actualizar lead                                    |
|               | `DELETE /v1/leads/:id`                     | Eliminar lead                                      |
| **Segmentos** | `POST /v1/leads/:id/segments`              | Agregar lead a segmentos                           |
|               | `DELETE /v1/leads/:id/segments/:segmentId` | Quitar de segmento                                 |
| **Tags**      | `POST /v1/leads/:email/tags`               | Agregar tags                                       |
|               | `DELETE /v1/leads/:email/tags`             | Quitar tags                                        |
|               | `GET /v1/leads/:email/tags`                | Listar tags                                        |
| **Atributos** | `POST /v1/leads/:email/attributes`         | Set/merge atributos custom                         |
|               | `GET /v1/leads/:email/attributes`          | Obtener atributos                                  |
| **Eventos**   | `POST /v1/events`                          | Trackear un evento                                 |
|               | `POST /v1/events/bulk`                     | Trackear hasta 1,000 eventos                       |
|               | `GET /v1/events`                           | Listar eventos con filtros                         |


---

# 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/public-api.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.