# API de Mailko

Versión `2026-10-01` · URL base `https://api.mailko.co/v1` · JSON · autenticación `Authorization: Bearer <API key>`.

## Introducción

La API de Mailko conecta tu aplicación con el envío de correos transaccionales de tu empresa y te avisa al instante de lo que pasa con los webhooks.

Es una API REST que habla JSON. Cada petición se autentica con una **API key** de tu empresa y actúa sobre los datos de esa empresa.

- **Fechas ISO.** `2026-10-01` para fechas y `2026-10-01T10:02:19-05:00` para fecha y hora. Mailko responde en hora de Bogotá (UTC−5), siempre con el desfase; una hora que envías con desfase se respeta, y una sin desfase (como el `send_at` de una campaña) se lee en la zona horaria de tu empresa.
- **Montos como texto** con dos decimales (`"394800.00"`) para no perder centavos.

## Autenticación

Crea una API key en **Configuración → Desarrolladores → API keys**. Elige solo los permisos (scopes) que la integración necesita y, si puedes, un vencimiento. Mailko te muestra la key **una sola vez**: guárdala en el gestor de secretos de tu servidor, nunca en el código de una página web ni en una app móvil.

Envíala en cada petición en la cabecera `Authorization`:

```
Authorization: Bearer mk_live_…
```

También se acepta `Authorization: Api-Key mk_live_…`. Las keys empiezan por `mk_live_` para que los escáneres de secretos las reconozcan si llegan a filtrarse.

- Una key **revocada** o **vencida** responde `401` con el código `api_key_revoked` o `api_key_expired`.
- Una key **sin el permiso** de la ruta responde `403 missing_scope` y dice cuál le falta en `required_scope`.
- Si se filtra, **regenérala** (el secreto anterior deja de servir al instante) o **revócala**.
- Si tu plan no incluye la API, responde `403 module_not_active`. Sin suscripción, `402 no_active_subscription`.
- Si la suscripción de la empresa queda en solo lectura (prueba vencida, pago atrasado o cancelada), puedes consultar pero cualquier escritura responde `402 subscription_read_only`.
- Las keys son **de la empresa**, no de la persona que las creó: siguen funcionando si esa persona sale del equipo o cambia de rol. Quien crea o regenera una key solo puede darle los permisos que tiene en la app; revisa y revoca las keys cuando alguien se va.
- Peticiones al mes: las que trae tu plan (`api_requests_per_month`, 100.000 con el adicional); las rechazadas por key inválida o por límite no cuentan.

Cada escritura queda en el historial de cambios de Mailko a nombre de «API key <nombre>», y cada petición en **Desarrolladores → Uso**.

## Errores

Mailko usa los códigos HTTP de siempre: `2xx` salió bien, `4xx` algo de la petición hay que corregir, `5xx` falló de nuestro lado (reintenta con la misma `Idempotency-Key`). Todo error tiene la misma forma:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "url: Debe ser una dirección HTTPS pública.",
    "fields": {
      "url": [
        "Debe ser una dirección HTTPS pública."
      ]
    },
    "request_id": "req_6f1c2a9b8e7d4c3b2a1f0e9d"
  }
}
```

- `type` es la familia del error (qué hacer con él).
- `code` es estable: tu programa decide con él. Nunca compares `message`, que puede mejorar.
- `message` está en español y se puede mostrar a una persona.
- `fields` aparece en errores de validación, con la ruta del campo (`topics[0]`).
- `request_id` es el mismo de la cabecera `X-Request-Id`: inclúyelo si escribes a soporte.

## Paginación y filtros

Los listados se piden por páginas con `page` (desde 1) y `page_size` (de 1 a 100, por defecto 20) y responden:

```json
{
  "data": [
    "…"
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 57,
    "total_pages": 3,
    "has_more": true
  }
}
```

Recorre hasta que `has_more` sea `false`. Una página más allá del final responde `data` vacío, no un error.

Casi todos los listados aceptan `search` (texto libre), filtros propios del recurso y `ordering` (por ejemplo `ordering=-created_at`). Para sincronizar, usa `updated_after` con la fecha de tu última lectura.

## Idempotencia

Las redes fallan: una petición puede llegar a Mailko y la respuesta perderse. Para reintentar sin ejecutar dos veces la misma operación, envía una cabecera `Idempotency-Key` con un valor único por operación (un UUID v4) en cada `POST`, `PATCH` y `DELETE`.

- Misma key y misma petición en las siguientes **24 horas** → Mailko no la ejecuta otra vez: repite la respuesta guardada, con la cabecera `Idempotent-Replayed: true`.
- Misma key mientras la primera todavía se procesa → `409 idempotency_key_in_progress`. Espera y reintenta.
- Misma key con otra petición (otro método, ruta o cuerpo) → `422 idempotency_key_reused`. Genera una key nueva por operación.
- Un error `5xx` no se guarda: el reintento se ejecuta de verdad.

## Límites de uso

Cada API key puede hacer **120 peticiones por minuto**, con ráfagas de hasta **20 por segundo**. Cada empresa tiene además un cupo de **100.000 peticiones al mes** (mes calendario, hora de Bogotá, UTC−5). Todas las respuestas traen:

| Cabecera | Qué dice |
|---|---|
| `X-RateLimit-Limit` | Peticiones por minuto de la key |
| `X-RateLimit-Remaining` | Las que le quedan en este minuto |
| `X-RateLimit-Reset` | Cuándo empieza el siguiente minuto (tiempo Unix, segundos) |

Al pasarte, Mailko responde `429` con `Retry-After` (segundos): `rate_limited` por minuto o por segundo, `monthly_quota_exceeded` por el mes. Reintenta con espera exponencial.

## Versionado

La versión va en la ruta: `/v1/`. Dentro de una versión solo agregamos — campos nuevos en las respuestas, rutas nuevas, eventos nuevos —, así que tu código debe ignorar los campos que no conoce. Un cambio que rompa algo sale en una versión nueva, anunciada con tiempo.

Cada respuesta trae la cabecera `Mailko-Version` (la fecha de la versión, hoy `2026-10-01`) y cada webhook su `api_version`. Los cambios están en el **Registro de cambios**.

## Permisos (scopes)

| Permiso | Qué permite |
|---|---|
| `send` | Enviar correos (POST /v1/emails y /v1/emails/batch). Nada más. |
| `read` | Ver correos y sus eventos, dominios, supresiones, plantillas, webhooks y el uso del mes. |
| `admin` | Agregar, verificar y eliminar dominios; manejar supresiones y webhooks. |
| `marketing` | Contactos, listas, segmentos e importaciones; crear campañas y, con confirmación, enviarlas. |

Los catálogos de referencia, `/me` y `/webhook-events` los lee cualquier API key válida.

## Errores: códigos

| Código | HTTP | Tipo | Qué significa |
|---|---|---|---|
| `validation_error` | 400 | `invalid_request_error` | Un campo no es válido; el detalle está en `fields`. |
| `invalid_parameter` | 400 | `invalid_request_error` | Un parámetro de la URL no es válido. |
| `invalid_page` | 400 | `invalid_request_error` | `page` no es un número mayor que cero. |
| `invalid_page_size` | 400 | `invalid_request_error` | `page_size` fuera de 1 a 100. |
| `idempotency_key_required` | 400 | `invalid_request_error` | Esta operación exige `Idempotency-Key`. |
| `idempotency_key_invalid` | 400 | `idempotency_error` | La key tiene más de 255 caracteres o caracteres no imprimibles. |
| `authentication_required` | 401 | `authentication_error` | Falta la cabecera Authorization. |
| `api_key_missing` | 401 | `authentication_error` | Falta la API key. |
| `authorization_header_invalid` | 401 | `authentication_error` | La cabecera no es «Bearer <key>». |
| `api_key_invalid` | 401 | `authentication_error` | La key no existe o no es de Mailko (un token de sesión no sirve aquí). |
| `api_key_revoked` | 401 | `authentication_error` | La key fue revocada. |
| `api_key_expired` | 401 | `authentication_error` | La key venció. |
| `partner_key_missing` | 401 | `authentication_error` | Apps socias: falta la llave de socio. |
| `partner_key_invalid` | 401 | `authentication_error` | Apps socias: la llave no existe o no es de socio (una key de proyecto no sirve en `/partner`). |
| `partner_key_revoked` | 401 | `authentication_error` | Apps socias: la llave de socio fue revocada. |
| `subscription_read_only` | 402 | `billing_error` | La cuenta está en solo lectura: se puede consultar, no escribir. |
| `subscription_limit_exceeded` | 402 | `billing_error` | Llegaste a un límite de tu plan. |
| `no_active_subscription` | 402 | `billing_error` | La empresa no tiene una suscripción activa. |
| `missing_scope` | 403 | `permission_error` | La key no tiene el permiso de esta ruta (`required_scope`). |
| `domain_not_verified` | 403 | `permission_error` | El dominio del remitente no está verificado en este proyecto. |
| `workspace_paused` | 403 | `permission_error` | El proyecto está pausado o suspendido por su reputación. |
| `marketing_disabled` | 403 | `permission_error` | Mailko envía por ahora solo correo transaccional: `stream: marketing` no está disponible. |
| `workspace_in_review` | 403 | `permission_error` | El proyecto está en revisión: usa una key de prueba. |
| `insufficient_balance` | 402 | `billing_error` | Sin cupo del plan, sin bolsas y sin tope de excedente. |
| `limit_exceeded` | 429 | `rate_limit_error` | Límite diario o de velocidad del proyecto (`Retry-After`). |
| `too_many_recipients` | 422 | `invalid_request_error` | Más de 50 destinatarios (límite de Amazon SES). |
| `too_many_emails` | 422 | `invalid_request_error` | Más de 100 correos en un lote. |
| `message_too_large` | 413 | `invalid_request_error` | El correo supera el tamaño permitido (10 MB). |
| `invalid_header` | 422 | `invalid_request_error` | Un asunto o una cabecera trae saltos de línea. |
| `template_variables_missing` | 422 | `invalid_request_error` | Faltan variables de la plantilla. |
| `domain_invalid` | 400 | `invalid_request_error` | El texto no es un dominio. |
| `free_mail_domain` | 400 | `invalid_request_error` | Gmail, Hotmail y similares no se pueden usar como remitente. |
| `domain_taken` | 400 | `invalid_request_error` | El dominio ya está registrado en Mailko. |
| `suppression_not_removable` | 409 | `invalid_request_error` | Una queja o una supresión de datos no se quita. |
| `provider_unavailable` | 503 | `api_error` | Amazon SES no respondió: intenta en unos minutos. |
| `module_not_active` | 403 | `permission_error` | Tu plan no incluye la API. |
| `endpoint_out_of_scope` | 403 | `permission_error` | El webhook recibe eventos que la key no puede leer: adminístralo desde la app. |
| `feature_not_available` | 403 | `permission_error` | Tu plan no incluye el módulo de esta ruta. |
| `not_found` | 404 | `invalid_request_error` | No existe ese recurso en tu empresa. |
| `route_not_found` | 404 | `invalid_request_error` | No existe esa ruta. |
| `method_not_allowed` | 405 | `invalid_request_error` | Ese método no aplica a la ruta. |
| `idempotency_key_in_progress` | 409 | `idempotency_error` | Otra petición con esa key aún se procesa. |
| `unsupported_media_type` | 415 | `invalid_request_error` | El cuerpo debe ser JSON. |
| `idempotency_key_reused` | 422 | `idempotency_error` | La key ya se usó con otra petición. |
| `rate_limited` | 429 | `rate_limit_error` | Demasiadas peticiones por minuto o por segundo. |
| `monthly_quota_exceeded` | 429 | `rate_limit_error` | Se acabó el cupo de peticiones del mes. |
| `audience_empty` | 422 | `invalid_request_error` | La campaña no tiene contactos suscritos a quienes enviar. |
| `campaign_not_editable` | 400 | `invalid_request_error` | La campaña ya no es un borrador. |
| `campaign_review_failed` | 400 | `invalid_request_error` | La revisión previa encontró algo que bloquea el envío. |
| `campaign_not_sending` | 400 | `invalid_request_error` | Solo se pausa una campaña que está enviando. |
| `campaign_requires_approval` | 409 | `invalid_request_error` | La campaña espera la revisión del equipo de Mailko (primeras campañas). |
| `confirmation_required` | 409 | `invalid_request_error` | Repite la llamada con `{"confirm": true}`. |
| `import_requires_review` | 202 | `invalid_request_error` | La importación espera la revisión del equipo de Mailko. |
| `list_not_found` | 404 | `invalid_request_error` | No existe esa lista en este proyecto. |
| `return_url_not_allowed` | 400 | `invalid_request_error` | `return_url` no está en los orígenes de tu app socia. |
| `scope_not_allowed` | 400 | `invalid_request_error` | Tu app socia no puede pedir ese permiso. |
| `external_id_taken` | 409 | `invalid_request_error` | Ya hay una conexión activa con ese `external_id` (`connection_id` en el error). |
| `code_not_found` | 404 | `invalid_request_error` | Ese código no existe o es de otra app. |
| `code_used` | 409 | `invalid_request_error` | El código ya se canjeó. |
| `code_expired` | 410 | `invalid_request_error` | El código venció (10 minutos). |
| `connection_revoked` | 409 | `invalid_request_error` | La conexión ya fue revocada. |
| `internal_error` | 500 | `api_error` | Algo falló de nuestro lado. Reintenta con la misma Idempotency-Key. |

## Correos

Enviar correos y ver qué pasó con ellos.

### El objeto correo

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | Id del correo (`msg_…`). |
| `object` | string | Siempre `email`. |
| `status` | enum | queued, sent, delivered, delayed, bounced, complained, suppressed, failed o rejected. |
| `status_reason` | string | Por qué quedó en ese estado, en palabras simples. |
| `from` | string | Remitente. |
| `to` | array | Destinatarios. |
| `cc` | array | Copia. |
| `bcc` | array | Copia oculta. |
| `reply_to` | array | Responder a. |
| `suppressed` | array | Destinatarios que no se enviaron por estar suprimidos. |
| `subject` | string | Asunto. |
| `template` | string | Alias de la plantilla, si se usó. |
| `template_version` | integer | Versión de la plantilla con que salió. |
| `tags` | object | Etiquetas. |
| `metadata` | object | Tus datos. |
| `stream` | enum | `transactional` o `marketing`. |
| `test_mode` | boolean | Enviado con una key de prueba: no se entregó. |
| `created_at` | datetime | Aceptado. |
| `sent_at` | datetime | Entregado a Amazon SES. |
| `delivered_at` | datetime | Recibido por el servidor del destinatario. |
| `last_event_at` | datetime | Último evento. |

### Enviar un correo

`POST /emails` · permiso `send`

Valida, reserva cupo y encola el correo; responde `202` con su id mientras un trabajador lo entrega a Amazon SES. El remitente debe ser de un **dominio verificado de tu proyecto**. Hasta 50 destinatarios entre `to`, `cc` y `bcc`. Los destinatarios en la lista de supresión no se envían ni se cobran. Con una key de prueba (`mk_test_…`) responde igual y no entrega nada.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `from` | string | sí | Remitente: `correo` o `Nombre <correo>` de un dominio verificado. |
| `to` | array | sí | Destinatarios (o un solo correo como texto). |
| `cc` | array | no | Copia. |
| `bcc` | array | no | Copia oculta. |
| `reply_to` | array | no | Responder a. |
| `subject` | string | no | Asunto. Obligatorio sin plantilla. |
| `html` | string | no | Cuerpo HTML. |
| `text` | string | no | Cuerpo en texto plano. |
| `template` | object | no | `{id, version?, variables?}`: alias o id de una plantilla y sus variables. |
| `headers` | object | no | Cabeceras permitidas (List-Unsubscribe, In-Reply-To, References…). |
| `attachments` | array | no | Hasta 20 adjuntos `{filename, content (base64), content_type}`. |
| `tags` | object | no | Hasta 10 etiquetas `nombre: valor` para filtrar después. |
| `metadata` | object | no | Datos tuyos que vuelven en los webhooks. |
| `stream` | enum | no | `transactional` o `marketing`. Mientras Mailko envíe solo correo transaccional, `marketing` responde `marketing_disabled`. Valores: `transactional`, `marketing`. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/emails' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"from": "Tienda Ejemplo <pedidos@tienda.co>", "to": ["cliente@correo.com"], "subject": "Tu pedido #1234", "html": "<p>Gracias por tu compra</p>", "text": "Gracias por tu compra", "reply_to": "soporte@tienda.co", "tags": {"tipo": "pedido"}, "metadata": {"order_id": "1234"}}'
```

Respuesta `202`:

```json
{
  "id": "msg_8f2k3j4h5g6f7d8s9a0q1w2e3r",
  "object": "email",
  "status": "queued",
  "test_mode": false
}
```

### Enviar un lote

`POST /emails/batch` · permiso `send`

Hasta 100 correos en una llamada (`{"emails": [...]}` o una lista). Primero se valida todo el lote: un correo inválido rechaza el lote y dice cuál. Si un límite o el saldo se acaban a mitad del lote, la respuesta de error trae en `accepted` los que sí quedaron en cola.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `emails` | array | sí | Los correos, cada uno como en POST /emails. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/emails/batch' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"emails": [{"from": "Tienda Ejemplo <pedidos@tienda.co>", "to": ["cliente@correo.com"], "subject": "Tu pedido #1234", "html": "<p>Gracias por tu compra</p>", "text": "Gracias por tu compra", "reply_to": "soporte@tienda.co", "tags": {"tipo": "pedido"}, "metadata": {"order_id": "1234"}}]}'
```

Respuesta `202`:

```json
{
  "data": [
    {
      "id": "msg_8f2k3j4h5g6f7d8s9a0q1w2e3r",
      "object": "email",
      "status": "queued",
      "test_mode": false
    }
  ]
}
```

### Listar correos

`GET /emails` · permiso `read`

Los correos del proyecto, del más reciente al más antiguo.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `status` | string | no | Uno o varios estados separados por coma. |
| `recipient` | string | no | Correos a esta dirección. |
| `tag` | string | no | `nombre:valor` de una etiqueta. |
| `created_after` | date | no | Desde (AAAA-MM-DD, día en hora de Bogotá, UTC−5). |
| `created_before` | date | no | Hasta, incluido. |
| `page` | integer | no | Página, desde 1. Por defecto `1`. |
| `page_size` | integer | no | Resultados por página, de 1 a 100. Por defecto `20`. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/emails' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "id": "msg_8f2k3j4h5g6f7d8s9a0q1w2e3r",
      "object": "email",
      "status": "delivered",
      "status_reason": "",
      "from": "Tienda Ejemplo <pedidos@tienda.co>",
      "to": [
        "cliente@correo.com"
      ],
      "cc": [],
      "bcc": [],
      "reply_to": [
        "soporte@tienda.co"
      ],
      "suppressed": [],
      "subject": "Tu pedido #1234",
      "template": null,
      "template_version": null,
      "tags": {
        "tipo": "pedido"
      },
      "metadata": {
        "order_id": "1234"
      },
      "stream": "transactional",
      "test_mode": false,
      "created_at": "2026-10-28T10:02:19-05:00",
      "sent_at": "2026-10-28T10:02:20-05:00",
      "delivered_at": "2026-10-28T10:02:22-05:00",
      "last_event_at": "2026-10-28T10:02:22-05:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

### Consultar un correo

`GET /emails/{id}` · permiso `read`

Estado de un correo y su línea de tiempo de eventos (`events`), con el motivo de cada rebote en palabras simples.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del correo (`msg_…`). |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/emails/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "id": "msg_8f2k3j4h5g6f7d8s9a0q1w2e3r",
  "object": "email",
  "status": "delivered",
  "status_reason": "",
  "from": "Tienda Ejemplo <pedidos@tienda.co>",
  "to": [
    "cliente@correo.com"
  ],
  "cc": [],
  "bcc": [],
  "reply_to": [
    "soporte@tienda.co"
  ],
  "suppressed": [],
  "subject": "Tu pedido #1234",
  "template": null,
  "template_version": null,
  "tags": {
    "tipo": "pedido"
  },
  "metadata": {
    "order_id": "1234"
  },
  "stream": "transactional",
  "test_mode": false,
  "created_at": "2026-10-28T10:02:19-05:00",
  "sent_at": "2026-10-28T10:02:20-05:00",
  "delivered_at": "2026-10-28T10:02:22-05:00",
  "last_event_at": "2026-10-28T10:02:22-05:00",
  "events": [
    {
      "type": "delivered",
      "recipient": "cliente@correo.com",
      "occurred_at": "2026-10-28T10:02:22-05:00",
      "bounce_type": "",
      "bounce_subtype": "",
      "explanation": "",
      "diagnostic": ""
    }
  ]
}
```

## Dominios

Tus dominios de envío y sus registros DNS.

### El objeto dominio

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string |  |
| `id` | string |  |
| `name` | string |  |
| `status` | string | pending, verified, failed, expired o paused. |
| `status_label` | string |  |
| `status_reason` | string |  |
| `region` | string |  |
| `dkim_status` | string |  |
| `mail_from_domain` | string |  |
| `mail_from_status` | string |  |
| `dmarc_status` | string |  |
| `dmarc_record` | string |  |
| `tracking_domain` | string |  |
| `tracking_status` | string |  |
| `problems` | object | Qué está mal en cada registro, en palabras simples. |
| `records` | array | Registros DNS a publicar: `purpose`, `type`, `host` (nombre completo), `name` (relativo a tu dominio principal: `envios.mail` para `mail.tienda.co`), `value`, `status`, `required`. |
| `checked_at` | string |  |
| `verified_at` | string |  |
| `expires_at` | string | Si no verifica antes, el dominio vence. |
| `created_at` | string |  |

### Listar dominios

`GET /domains` · permiso `read`

Los dominios del proyecto con el estado de cada registro DNS.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `page` | integer | no | Página, desde 1. Por defecto `1`. |
| `page_size` | integer | no | Resultados por página, de 1 a 100. Por defecto `20`. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/domains' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "object": "domain",
      "id": "5b4a3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
      "name": "tienda.co",
      "status": "verified",
      "status_label": "Verificado",
      "status_reason": "",
      "region": "us-east-2",
      "dkim_status": "ok",
      "mail_from_domain": "envios.tienda.co",
      "mail_from_status": "ok",
      "dmarc_status": "ok",
      "dmarc_record": "v=DMARC1; p=none;",
      "tracking_domain": "",
      "tracking_status": "pending",
      "problems": {},
      "records": [
        {
          "purpose": "dkim",
          "type": "TXT",
          "host": "mailko._domainkey.tienda.co",
          "name": "mailko._domainkey",
          "value": "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA…",
          "status": "ok",
          "required": true
        },
        {
          "purpose": "mail_from",
          "type": "CNAME",
          "host": "envios.tienda.co",
          "name": "envios",
          "value": "feedback.mailko.co",
          "status": "ok",
          "required": true
        }
      ],
      "checked_at": "2026-10-28T10:00:00-05:00",
      "verified_at": "2026-10-28T09:12:00-05:00",
      "expires_at": "2026-10-31T09:00:00-05:00",
      "created_at": "2026-10-28T09:00:00-05:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

### Agregar un dominio

`POST /domains` · permiso `admin`

Crea la identidad en Amazon SES y responde los registros DNS que debes publicar (`records`): tres CNAME de DKIM, el MX y el SPF del dominio MAIL FROM y un DMARC recomendado. Mailko revisa solo cada minuto; a las 72 horas sin verificar, el dominio vence. No se aceptan dominios de correo gratuito.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | string | sí | Tu dominio, sin http ni www (`tienda.co`). |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/domains' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "tienda.co"}'
```

Respuesta `201`:

```json
{
  "object": "domain",
  "id": "5b4a3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "name": "tienda.co",
  "status": "verified",
  "status_label": "Verificado",
  "status_reason": "",
  "region": "us-east-2",
  "dkim_status": "ok",
  "mail_from_domain": "envios.tienda.co",
  "mail_from_status": "ok",
  "dmarc_status": "ok",
  "dmarc_record": "v=DMARC1; p=none;",
  "tracking_domain": "",
  "tracking_status": "pending",
  "problems": {},
  "records": [
    {
      "purpose": "dkim",
      "type": "TXT",
      "host": "mailko._domainkey.tienda.co",
      "name": "mailko._domainkey",
      "value": "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA…",
      "status": "ok",
      "required": true
    },
    {
      "purpose": "mail_from",
      "type": "CNAME",
      "host": "envios.tienda.co",
      "name": "envios",
      "value": "feedback.mailko.co",
      "status": "ok",
      "required": true
    }
  ],
  "checked_at": "2026-10-28T10:00:00-05:00",
  "verified_at": "2026-10-28T09:12:00-05:00",
  "expires_at": "2026-10-31T09:00:00-05:00",
  "created_at": "2026-10-28T09:00:00-05:00"
}
```

### Consultar un dominio

`GET /domains/{id}` · permiso `read`

Un dominio y sus registros DNS.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/domains/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "object": "domain",
  "id": "5b4a3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "name": "tienda.co",
  "status": "verified",
  "status_label": "Verificado",
  "status_reason": "",
  "region": "us-east-2",
  "dkim_status": "ok",
  "mail_from_domain": "envios.tienda.co",
  "mail_from_status": "ok",
  "dmarc_status": "ok",
  "dmarc_record": "v=DMARC1; p=none;",
  "tracking_domain": "",
  "tracking_status": "pending",
  "problems": {},
  "records": [
    {
      "purpose": "dkim",
      "type": "TXT",
      "host": "mailko._domainkey.tienda.co",
      "name": "mailko._domainkey",
      "value": "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA…",
      "status": "ok",
      "required": true
    },
    {
      "purpose": "mail_from",
      "type": "CNAME",
      "host": "envios.tienda.co",
      "name": "envios",
      "value": "feedback.mailko.co",
      "status": "ok",
      "required": true
    }
  ],
  "checked_at": "2026-10-28T10:00:00-05:00",
  "verified_at": "2026-10-28T09:12:00-05:00",
  "expires_at": "2026-10-31T09:00:00-05:00",
  "created_at": "2026-10-28T09:00:00-05:00"
}
```

### Verificar ahora

`POST /domains/{id}/verify` · permiso `admin`

Revisa ya los registros (Mailko también lo hace solo) y responde el dominio con lo que encontró.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/domains/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/verify' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200`:

```json
{
  "object": "domain",
  "id": "5b4a3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "name": "tienda.co",
  "status": "verified",
  "status_label": "Verificado",
  "status_reason": "",
  "region": "us-east-2",
  "dkim_status": "ok",
  "mail_from_domain": "envios.tienda.co",
  "mail_from_status": "ok",
  "dmarc_status": "ok",
  "dmarc_record": "v=DMARC1; p=none;",
  "tracking_domain": "",
  "tracking_status": "pending",
  "problems": {},
  "records": [
    {
      "purpose": "dkim",
      "type": "TXT",
      "host": "mailko._domainkey.tienda.co",
      "name": "mailko._domainkey",
      "value": "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA…",
      "status": "ok",
      "required": true
    },
    {
      "purpose": "mail_from",
      "type": "CNAME",
      "host": "envios.tienda.co",
      "name": "envios",
      "value": "feedback.mailko.co",
      "status": "ok",
      "required": true
    }
  ],
  "checked_at": "2026-10-28T10:00:00-05:00",
  "verified_at": "2026-10-28T09:12:00-05:00",
  "expires_at": "2026-10-31T09:00:00-05:00",
  "created_at": "2026-10-28T09:00:00-05:00"
}
```

### Eliminar un dominio

`DELETE /domains/{id}` · permiso `admin`

Quita la identidad de Amazon SES. Ningún correo vuelve a salir con ese dominio.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X DELETE 'https://api.mailko.co/v1/domains/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `204` sin cuerpo.

## Supresiones

Direcciones a las que no se envía.

### El objeto supresión

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string |  |
| `id` | string |  |
| `email` | string |  |
| `reason` | string | hard_bounce, complaint, unsubscribe, manual o erasure. |
| `reason_label` | string |  |
| `source` | string |  |
| `source_label` | string |  |
| `detail` | string |  |
| `scope` | string | `workspace` o `global` (de la plataforma). |
| `message_id` | string |  |
| `created_at` | string |  |

### Listar supresiones

`GET /suppressions` · permiso `read`

Direcciones a las que el proyecto no envía: rebotes duros, quejas, bajas y las que agregaste.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `reason` | string | no | Motivos separados por coma. |
| `email` | string | no | Buscar una dirección. |
| `page` | integer | no | Página, desde 1. Por defecto `1`. |
| `page_size` | integer | no | Resultados por página, de 1 a 100. Por defecto `20`. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/suppressions' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "object": "suppression",
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "email": "cliente@correo.com",
      "reason": "hard_bounce",
      "reason_label": "Rebote duro",
      "source": "ses_event",
      "source_label": "Evento de SES",
      "detail": "La dirección no existe.",
      "scope": "workspace",
      "message_id": "msg_8f2k3j4h5g6f7d8s9a0q1w2e3r",
      "created_at": "2026-10-28T10:02:30-05:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

### Agregar una supresión

`POST /suppressions` · permiso `admin`

Bloquea una dirección en este proyecto.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `email` | string | sí | La dirección. |
| `detail` | string | no | Por qué. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/suppressions' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"email": "cliente@correo.com", "detail": "Pidió no recibir más correos"}'
```

Respuesta `201`:

```json
{
  "object": "suppression",
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "email": "cliente@correo.com",
  "reason": "hard_bounce",
  "reason_label": "Rebote duro",
  "source": "ses_event",
  "source_label": "Evento de SES",
  "detail": "La dirección no existe.",
  "scope": "workspace",
  "message_id": "msg_8f2k3j4h5g6f7d8s9a0q1w2e3r",
  "created_at": "2026-10-28T10:02:30-05:00"
}
```

### Consultar una supresión

`GET /suppressions/{id}` · permiso `read`

Una supresión por su id.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/suppressions/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "object": "suppression",
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "email": "cliente@correo.com",
  "reason": "hard_bounce",
  "reason_label": "Rebote duro",
  "source": "ses_event",
  "source_label": "Evento de SES",
  "detail": "La dirección no existe.",
  "scope": "workspace",
  "message_id": "msg_8f2k3j4h5g6f7d8s9a0q1w2e3r",
  "created_at": "2026-10-28T10:02:30-05:00"
}
```

### Quitar una supresión

`DELETE /suppressions/{id}` · permiso `admin`

Vuelve a permitir la dirección. Una queja o una solicitud de supresión de datos no se puede quitar.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X DELETE 'https://api.mailko.co/v1/suppressions/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `204` sin cuerpo.

## Plantillas

Plantillas versionadas con variables.

### El objeto plantilla

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string |  |
| `id` | string |  |
| `name` | string |  |
| `alias` | string |  |
| `description` | string |  |
| `current_version` | integer |  |
| `current` | object | La versión vigente: asunto, HTML, texto y variables. |
| `created_at` | string |  |
| `updated_at` | string |  |

### Listar plantillas

`GET /templates` · permiso `read`

Las plantillas del proyecto con su versión vigente.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `page` | integer | no | Página, desde 1. Por defecto `1`. |
| `page_size` | integer | no | Resultados por página, de 1 a 100. Por defecto `20`. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/templates' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "object": "template",
      "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "Bienvenida",
      "alias": "bienvenida",
      "description": "",
      "current_version": 2,
      "current": {
        "id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
        "version": 2,
        "subject": "Hola {{ nombre }}",
        "html": "<p>Bienvenido, {{ nombre }}</p>",
        "text": "Bienvenido, {{ nombre }}",
        "variables": [
          "nombre"
        ],
        "created_at": "2026-10-20T10:00:00-05:00"
      },
      "created_at": "2026-10-01T10:00:00-05:00",
      "updated_at": "2026-10-20T10:00:00-05:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

### Consultar una plantilla

`GET /templates/{id}` · permiso `read`

Una plantilla y su versión vigente con sus variables.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/templates/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "object": "template",
  "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "Bienvenida",
  "alias": "bienvenida",
  "description": "",
  "current_version": 2,
  "current": {
    "id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
    "version": 2,
    "subject": "Hola {{ nombre }}",
    "html": "<p>Bienvenido, {{ nombre }}</p>",
    "text": "Bienvenido, {{ nombre }}",
    "variables": [
      "nombre"
    ],
    "created_at": "2026-10-20T10:00:00-05:00"
  },
  "created_at": "2026-10-01T10:00:00-05:00",
  "updated_at": "2026-10-20T10:00:00-05:00"
}
```

## Uso

Consumo del mes, saldo y límites.

### El objeto uso

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string |  |
| `available` | boolean | `false` si el saldo no se pudo leer ahora: `used` y `remaining` llegan vacíos. |
| `limit` | integer | Correos del plan este mes (-1: sin límite). |
| `unlimited` | boolean |  |
| `used` | integer |  |
| `remaining` | integer | Lo que queda del cupo del plan este mes. |
| `packs_remaining` | integer | Correos que guardan tus bolsas vigentes. |
| `test_mode` | boolean | Sin plan ni bolsa: solo modo de prueba. |
| `workspace` | object | Límites de hoy del proyecto (nivel de confianza). |

### Consumo del mes

`GET /usage` · permiso `read`

Lo que llevas del mes, lo que te queda del plan y de las bolsas, el excedente y los límites del proyecto hoy.

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/usage' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "object": "usage",
  "available": true,
  "limit": 50000,
  "unlimited": false,
  "used": 12840,
  "remaining": 37160,
  "packs_remaining": 20000,
  "test_mode": false,
  "workspace": {
    "daily_limit": 2000,
    "rate_limit": 5,
    "sent_today": 312,
    "status": "active",
    "trust_level": 1
  }
}
```

## Webhooks por API

Administra por código los mismos webhooks de la pantalla Desarrolladores.

### El objeto webhook

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | uuid | Identificador del webhook. |
| `url` | string | Dirección HTTPS que recibe los eventos. |
| `description` | string | Para qué es. |
| `topics` | array | Eventos suscritos. Vacío = todos. |
| `secret_hint` | string | Los últimos caracteres del secreto de firma. El secreto completo solo se entrega al crear o al rotar. |
| `is_active` | boolean | Encendido. |
| `consecutive_failures` | integer | Entregas fallidas seguidas. |
| `disabled_reason` | string | Por qué se apagó solo, si fue así. |
| `last_delivery_at` | datetime | Última entrega exitosa. |
| `created_at` | datetime | Creación. |
| `updated_at` | datetime | Última modificación. |

### Listar webhooks

`GET /webhook-endpoints` · permiso `read`

Los webhooks de tu empresa.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `page` | integer | no | Página, desde 1. Por defecto `1`. |
| `page_size` | integer | no | Resultados por página, de 1 a 100. Por defecto `20`. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/webhook-endpoints' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "id": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
      "url": "https://mi-app.co/webhooks/mailko",
      "description": "Avisos de entrega",
      "topics": [
        "email.delivered",
        "email.bounced"
      ],
      "secret_hint": "whsec_…a1b2",
      "is_active": true,
      "consecutive_failures": 0,
      "disabled_reason": "",
      "last_delivery_at": "2026-10-01T10:02:20-05:00",
      "created_at": "2026-09-30T18:00:00-05:00",
      "updated_at": "2026-09-30T18:00:00-05:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

### Crear un webhook

`POST /webhook-endpoints` · permiso `admin`

Registra una dirección HTTPS pública. La respuesta trae el **secreto de firma completo** (`secret`) por única vez: guárdalo para verificar las firmas. Después solo verás `secret_hint`.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `url` | string | sí | Dirección HTTPS pública (sin redirecciones). |
| `description` | string | no | Para qué es. |
| `topics` | array | sí | Eventos (ver /webhook-events). Obligatorio: cada evento exige el permiso de lectura de su objeto. |
| `is_active` | boolean | no | Encendido. Por defecto `True`. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/webhook-endpoints' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mi-app.co/webhooks/mailko", "description": "Avisos de entrega", "topics": ["email.delivered", "email.bounced"]}'
```

Respuesta `201`:

```json
{
  "id": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
  "url": "https://mi-app.co/webhooks/mailko",
  "description": "Avisos de entrega",
  "topics": [
    "email.delivered",
    "email.bounced"
  ],
  "secret_hint": "whsec_…a1b2",
  "is_active": true,
  "consecutive_failures": 0,
  "disabled_reason": "",
  "last_delivery_at": "2026-10-01T10:02:20-05:00",
  "created_at": "2026-09-30T18:00:00-05:00",
  "updated_at": "2026-09-30T18:00:00-05:00",
  "secret": "whsec_9fK2…a1b2"
}
```

### Consultar un webhook

`GET /webhook-endpoints/{id}` · permiso `read`

Un webhook por su id.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/webhook-endpoints/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "id": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
  "url": "https://mi-app.co/webhooks/mailko",
  "description": "Avisos de entrega",
  "topics": [
    "email.delivered",
    "email.bounced"
  ],
  "secret_hint": "whsec_…a1b2",
  "is_active": true,
  "consecutive_failures": 0,
  "disabled_reason": "",
  "last_delivery_at": "2026-10-01T10:02:20-05:00",
  "created_at": "2026-09-30T18:00:00-05:00",
  "updated_at": "2026-09-30T18:00:00-05:00"
}
```

### Actualizar un webhook

`PATCH /webhook-endpoints/{id}` · permiso `admin`

Cambia la dirección, los eventos o lo apaga. Al apagarlo, lo que estaba por enviarse se omite; al encenderlo solo llegan los eventos nuevos.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `url` | string | no | Dirección. |
| `description` | string | no | Para qué es. |
| `topics` | array | no | Eventos (cada uno con el permiso de lectura de su objeto). |
| `is_active` | boolean | no | Encendido. |

Ejemplo:

```bash
curl -X PATCH 'https://api.mailko.co/v1/webhook-endpoints/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'
```

Respuesta `200`:

```json
{
  "id": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
  "url": "https://mi-app.co/webhooks/mailko",
  "description": "Avisos de entrega",
  "topics": [
    "email.delivered",
    "email.bounced"
  ],
  "secret_hint": "whsec_…a1b2",
  "is_active": false,
  "consecutive_failures": 0,
  "disabled_reason": "",
  "last_delivery_at": "2026-10-01T10:02:20-05:00",
  "created_at": "2026-09-30T18:00:00-05:00",
  "updated_at": "2026-09-30T18:00:00-05:00"
}
```

### Eliminar un webhook

`DELETE /webhook-endpoints/{id}` · permiso `admin`

Deja de enviarle eventos y borra su historial de entregas.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X DELETE 'https://api.mailko.co/v1/webhook-endpoints/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `204` sin cuerpo.

### Rotar el secreto de firma

`POST /webhook-endpoints/{id}/rotate-secret` · permiso `admin`

Genera un secreto nuevo y lo responde por única vez. El anterior deja de firmar de inmediato.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/webhook-endpoints/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/rotate-secret' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200`:

```json
{
  "id": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
  "url": "https://mi-app.co/webhooks/mailko",
  "description": "Avisos de entrega",
  "topics": [
    "email.delivered",
    "email.bounced"
  ],
  "secret_hint": "whsec_…c3d4",
  "is_active": true,
  "consecutive_failures": 0,
  "disabled_reason": "",
  "last_delivery_at": "2026-10-01T10:02:20-05:00",
  "created_at": "2026-09-30T18:00:00-05:00",
  "updated_at": "2026-09-30T18:00:00-05:00",
  "secret": "whsec_Q7m…c3d4"
}
```

### Enviar un evento de prueba

`POST /webhook-endpoints/{id}/test` · permiso `admin`

Envía ya un evento `ping` firmado (aunque el webhook esté apagado) y responde la entrega con lo que contestó tu servidor.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/webhook-endpoints/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/test' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200`:

```json
{
  "id": "8e7d6c5b-4a39-4281-9706-f5e4d3c2b1a0",
  "event_id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "topic": "ping",
  "api_version": "2026-10-01",
  "source": "app",
  "status": "delivered",
  "status_display": "Entregado",
  "attempts": 1,
  "response_status": 200,
  "response_body": "ok",
  "error": "",
  "duration_ms": 182,
  "next_attempt_at": null,
  "delivered_at": "2026-10-01T10:02:20-05:00",
  "body": {
    "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
    "type": "email.delivered",
    "data": {
      "object": {
        "…": "…"
      }
    }
  },
  "created_at": "2026-10-01T10:02:19-05:00"
}
```

### Historial de entregas

`GET /webhook-endpoints/{id}/deliveries` · permiso `read`

Las entregas del webhook, de la más reciente a la más antigua, con el cuerpo enviado y la respuesta. Se conservan 90 días.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `status` | enum | no | Estado. Valores: `pending`, `delivered`, `failed`, `skipped`. |
| `type` | string | no | Tipo de evento. |
| `page` | integer | no | Página, desde 1. Por defecto `1`. |
| `page_size` | integer | no | Resultados por página, de 1 a 100. Por defecto `20`. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/webhook-endpoints/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/deliveries' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "id": "8e7d6c5b-4a39-4281-9706-f5e4d3c2b1a0",
      "event_id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
      "topic": "email.delivered",
      "api_version": "2026-10-01",
      "source": "app",
      "status": "delivered",
      "status_display": "Entregado",
      "attempts": 1,
      "response_status": 200,
      "response_body": "ok",
      "error": "",
      "duration_ms": 182,
      "next_attempt_at": null,
      "delivered_at": "2026-10-01T10:02:20-05:00",
      "body": {
        "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
        "type": "email.delivered",
        "data": {
          "object": {
            "…": "…"
          }
        }
      },
      "created_at": "2026-10-01T10:02:19-05:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

### Reenviar una entrega

`POST /webhook-endpoints/{id}/deliveries/{delivery_id}/redeliver` · permiso `admin`

Envía otra vez el mismo evento (mismo `id`, para que tu servidor lo deduplique).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |
| `delivery_id` | uuid | sí | La entrega. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/webhook-endpoints/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/deliveries/8e7d6c5b-4a39-4281-9706-f5e4d3c2b1a0/redeliver' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200`:

```json
{
  "id": "8e7d6c5b-4a39-4281-9706-f5e4d3c2b1a0",
  "event_id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "topic": "email.delivered",
  "api_version": "2026-10-01",
  "source": "app",
  "status": "delivered",
  "status_display": "Entregado",
  "attempts": 1,
  "response_status": 200,
  "response_body": "ok",
  "error": "",
  "duration_ms": 182,
  "next_attempt_at": null,
  "delivered_at": "2026-10-01T10:02:20-05:00",
  "body": {
    "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
    "type": "email.delivered",
    "data": {
      "object": {
        "…": "…"
      }
    }
  },
  "created_at": "2026-10-01T10:02:19-05:00"
}
```

### Tipos de evento

`GET /webhook-events` · permiso cualquier API key

Los eventos a los que se puede suscribir un webhook.

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/webhook-events' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "type": "email.delivered",
      "group": "emails",
      "group_label": "Correos",
      "label": "Correo entregado",
      "description": "SES confirmó la entrega al servidor del destinatario.",
      "object": "email"
    }
  ]
}
```

## Contactos

Tus contactos, sin perder bajas ni consentimientos.

### El objeto contacto

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string |  |
| `id` | string |  |
| `email` | string |  |
| `first_name` | string |  |
| `last_name` | string |  |
| `country` | string |  |
| `status` | string | subscribed, pending, unsubscribed, bounced, complained o suppressed. |
| `status_label` | string |  |
| `status_changed_at` | string |  |
| `fields` | object | Tus campos propios (Contactos → Campos). |
| `tags` | array |  |
| `source` | string |  |
| `lists` | array |  |
| `last_sent_at` | string |  |
| `last_opened_at` | string |  |
| `last_clicked_at` | string |  |
| `campaigns_received` | integer |  |
| `cleaned_at` | string | La limpieza automática dejó de enviarle por inactividad. |
| `created_at` | string |  |
| `updated_at` | string |  |

### Listar contactos

`GET /contacts` · permiso `marketing`

Los contactos del proyecto, del más reciente al más antiguo.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `status` | string | no | Uno o varios estados separados por coma. |
| `tag` | string | no | Contactos con esta etiqueta. |
| `list` | uuid | no | Contactos de esta lista. |
| `segment` | uuid | no | Contactos que cumplen este segmento. |
| `search` | string | no | Busca en correo, nombre y apellido. |
| `page` | integer | no | Página, desde 1. Por defecto `1`. |
| `page_size` | integer | no | Resultados por página, de 1 a 100. Por defecto `20`. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/contacts' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "object": "contact",
      "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "email": "ana@correo.co",
      "first_name": "Ana",
      "last_name": "Gómez",
      "country": "CO",
      "status": "subscribed",
      "status_label": "Suscrito",
      "status_changed_at": "2026-10-20T09:12:00-05:00",
      "fields": {
        "ciudad": "Medellín"
      },
      "tags": [
        "cliente"
      ],
      "source": "api",
      "lists": [
        "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
      ],
      "last_sent_at": "2026-10-27T10:00:00-05:00",
      "last_opened_at": "2026-10-27T10:21:00-05:00",
      "last_clicked_at": null,
      "campaigns_received": 4,
      "cleaned_at": null,
      "created_at": "2026-09-02T15:40:00-05:00",
      "updated_at": "2026-10-27T10:21:00-05:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

### Crear o actualizar un contacto

`POST /contacts` · permiso `marketing`

Por correo: si existe se actualiza (`200`), si no se crea (`201`). Quien se dio de baja, rebotó o se quejó **no vuelve a quedar suscrito** por esta vía. Quien está en la lista de supresión entra como `suppressed`.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `email` | string | sí | Correo. |
| `first_name` | string | no | Nombre. |
| `last_name` | string | no | Apellido. |
| `country` | string | no | País (ISO de dos letras). |
| `fields` | object | no | Campos propios del proyecto. |
| `tags` | array | no | Etiquetas. |
| `lists` | array | no | Ids de listas a las que se suma. |
| `status` | enum | no | Estado inicial. Valores: `subscribed`, `pending`, `unsubscribed`. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/contacts' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"email": "ana@correo.co", "first_name": "Ana", "tags": ["cliente"]}'
```

Respuesta `201`:

```json
{
  "object": "contact",
  "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "email": "ana@correo.co",
  "first_name": "Ana",
  "last_name": "Gómez",
  "country": "CO",
  "status": "subscribed",
  "status_label": "Suscrito",
  "status_changed_at": "2026-10-20T09:12:00-05:00",
  "fields": {
    "ciudad": "Medellín"
  },
  "tags": [
    "cliente"
  ],
  "source": "api",
  "lists": [
    "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
  ],
  "last_sent_at": "2026-10-27T10:00:00-05:00",
  "last_opened_at": "2026-10-27T10:21:00-05:00",
  "last_clicked_at": null,
  "campaigns_received": 4,
  "cleaned_at": null,
  "created_at": "2026-09-02T15:40:00-05:00",
  "updated_at": "2026-10-27T10:21:00-05:00"
}
```

### Consultar un contacto

`GET /contacts/{id}` · permiso `marketing`

Datos, estado, listas y actividad.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/contacts/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "object": "contact",
  "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "email": "ana@correo.co",
  "first_name": "Ana",
  "last_name": "Gómez",
  "country": "CO",
  "status": "subscribed",
  "status_label": "Suscrito",
  "status_changed_at": "2026-10-20T09:12:00-05:00",
  "fields": {
    "ciudad": "Medellín"
  },
  "tags": [
    "cliente"
  ],
  "source": "api",
  "lists": [
    "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
  ],
  "last_sent_at": "2026-10-27T10:00:00-05:00",
  "last_opened_at": "2026-10-27T10:21:00-05:00",
  "last_clicked_at": null,
  "campaigns_received": 4,
  "cleaned_at": null,
  "created_at": "2026-09-02T15:40:00-05:00",
  "updated_at": "2026-10-27T10:21:00-05:00"
}
```

### Editar un contacto

`PATCH /contacts/{id}` · permiso `marketing`

Cambia sus datos. El correo no cambia. Reactivar a quien se dio de baja solo se hace en el panel, confirmando el consentimiento.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `first_name` | string | no | Nombre. |
| `last_name` | string | no | Apellido. |
| `country` | string | no | País. |
| `fields` | object | no | Campos propios. |
| `tags` | array | no | Etiquetas que se suman. |
| `lists` | array | no | Listas a las que se suma. |
| `status` | enum | no | Nuevo estado. Valores: `subscribed`, `pending`, `unsubscribed`. |

Ejemplo:

```bash
curl -X PATCH 'https://api.mailko.co/v1/contacts/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200`:

```json
{
  "object": "contact",
  "id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "email": "ana@correo.co",
  "first_name": "Ana",
  "last_name": "Gómez",
  "country": "CO",
  "status": "subscribed",
  "status_label": "Suscrito",
  "status_changed_at": "2026-10-20T09:12:00-05:00",
  "fields": {
    "ciudad": "Medellín"
  },
  "tags": [
    "cliente"
  ],
  "source": "api",
  "lists": [
    "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
  ],
  "last_sent_at": "2026-10-27T10:00:00-05:00",
  "last_opened_at": "2026-10-27T10:21:00-05:00",
  "last_clicked_at": null,
  "campaigns_received": 4,
  "cleaned_at": null,
  "created_at": "2026-09-02T15:40:00-05:00",
  "updated_at": "2026-10-27T10:21:00-05:00"
}
```

### Eliminar un contacto

`DELETE /contacts/{id}` · permiso `marketing`

Borra sus datos para siempre (protección de datos). Queda solo la huella del correo en la lista de supresión, para no volver a escribirle.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X DELETE 'https://api.mailko.co/v1/contacts/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `204` sin cuerpo.

## Listas

Listas de contactos y sus miembros.

### El objeto lista

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string |  |
| `id` | string |  |
| `name` | string |  |
| `description` | string |  |
| `double_opt_in` | boolean | Los formularios de esta lista piden confirmar el correo. |
| `contacts_count` | integer |  |
| `created_at` | string |  |

### Listar listas

`GET /lists` · permiso `marketing`

Las listas del proyecto con su número de contactos.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `page` | integer | no | Página, desde 1. Por defecto `1`. |
| `page_size` | integer | no | Resultados por página, de 1 a 100. Por defecto `20`. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/lists' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "object": "list",
      "id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
      "name": "Clientes",
      "description": "Compraron al menos una vez.",
      "double_opt_in": true,
      "contacts_count": 1840,
      "created_at": "2026-09-01T08:00:00-05:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

### Crear una lista

`POST /lists` · permiso `marketing`

Una lista nueva, vacía.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | string | sí | Nombre. |
| `description` | string | no | Descripción. |
| `double_opt_in` | boolean | no | Pedir confirmación en sus formularios. Por defecto `True`. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/lists' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Clientes"}'
```

Respuesta `201`:

```json
{
  "object": "list",
  "id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "name": "Clientes",
  "description": "Compraron al menos una vez.",
  "double_opt_in": true,
  "contacts_count": 1840,
  "created_at": "2026-09-01T08:00:00-05:00"
}
```

### Consultar una lista

`GET /lists/{id}` · permiso `marketing`

Una lista y su número de contactos.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/lists/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "object": "list",
  "id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "name": "Clientes",
  "description": "Compraron al menos una vez.",
  "double_opt_in": true,
  "contacts_count": 1840,
  "created_at": "2026-09-01T08:00:00-05:00"
}
```

### Agregar contactos a una lista

`POST /lists/{id}/contacts` · permiso `marketing`

Hasta 1.000 correos (`{"contacts": [...]}`). Los que no existen se crean.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `contacts` | array | sí | Correos. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/lists/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/contacts' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"contacts": ["ana@correo.co", "luis@correo.co"]}'
```

Respuesta `200`:

```json
{
  "object": "list_membership",
  "list": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "added": 2
}
```

### Quitar contactos de una lista

`DELETE /lists/{id}/contacts` · permiso `marketing`

Los saca de la lista; el contacto sigue existiendo.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `contacts` | array | sí | Correos. |

Ejemplo:

```bash
curl -X DELETE 'https://api.mailko.co/v1/lists/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/contacts' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"contacts": ["ana@correo.co"]}'
```

Respuesta `200`:

```json
{
  "object": "list_membership",
  "list": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "removed": 1
}
```

## Segmentos

Contactos que cumplen unas reglas.

### El objeto segmento

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string |  |
| `id` | string |  |
| `name` | string |  |
| `description` | string |  |
| `definition` | object | Reglas `{match, rules: [{field, op, value}]}`. |
| `contacts_count` | integer |  |
| `subscribed_count` | integer |  |
| `created_at` | string |  |

### Listar segmentos

`GET /segments` · permiso `marketing`

Los segmentos del proyecto con cuántos contactos cumplen cada uno.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `page` | integer | no | Página, desde 1. Por defecto `1`. |
| `page_size` | integer | no | Resultados por página, de 1 a 100. Por defecto `20`. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/segments' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "object": "segment",
      "id": "6b5c4d3e-2f1a-4b0c-9d8e-7f6a5b4c3d2e",
      "name": "Abrieron en 30 días",
      "description": "",
      "definition": {
        "match": "all",
        "rules": [
          {
            "field": "opened_in_days",
            "op": "lte",
            "value": 30
          }
        ]
      },
      "contacts_count": 920,
      "subscribed_count": 901,
      "created_at": "2026-09-10T08:00:00-05:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

### Consultar un segmento

`GET /segments/{id}` · permiso `marketing`

Sus reglas y su conteo.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/segments/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "object": "segment",
  "id": "6b5c4d3e-2f1a-4b0c-9d8e-7f6a5b4c3d2e",
  "name": "Abrieron en 30 días",
  "description": "",
  "definition": {
    "match": "all",
    "rules": [
      {
        "field": "opened_in_days",
        "op": "lte",
        "value": 30
      }
    ]
  },
  "contacts_count": 920,
  "subscribed_count": 901,
  "created_at": "2026-09-10T08:00:00-05:00"
}
```

## Campañas

Campañas de marketing con envío escalonado.

### El objeto campaña

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string |  |
| `id` | string |  |
| `name` | string |  |
| `subject` | string |  |
| `preheader` | string |  |
| `from` | object |  |
| `from_name` | string |  |
| `from_email` | string |  |
| `reply_to` | string |  |
| `lists` | array |  |
| `segment` | string |  |
| `blocks` | array | El contenido del editor (heading, text, button, image, divider, spacer, html, columns). |
| `theme` | object |  |
| `publish_to` | string | `email`, `web` (solo en el sitio del newsletter) o `both`. |
| `status` | string | draft, review, scheduled, sending, paused, sent o canceled. |
| `status_label` | string |  |
| `status_reason` | string |  |
| `send_at` | string |  |
| `started_at` | string |  |
| `finished_at` | string |  |
| `current_batch` | integer |  |
| `next_batch_at` | string |  |
| `review` | object |  |
| `stats` | object |  |
| `approved_at` | string |  |
| `issue_url` | string |  |
| `audience_count` | integer |  |
| `requires_approval` | boolean | Las primeras campañas del proyecto las revisa el equipo de Mailko. |
| `created_at` | string |  |
| `updated_at` | string |  |

### Listar campañas

`GET /campaigns` · permiso `marketing`

Las campañas del proyecto, de la más reciente a la más antigua.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `status` | string | no | Uno o varios estados separados por coma. |
| `page` | integer | no | Página, desde 1. Por defecto `1`. |
| `page_size` | integer | no | Resultados por página, de 1 a 100. Por defecto `20`. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/campaigns' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "object": "campaign",
      "id": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f",
      "name": "Novedades de noviembre",
      "subject": "Llegó la cosecha de noviembre, {{ nombre | \"amigo\" }}",
      "preheader": "Tres cafés nuevos y envío gratis este fin de semana.",
      "from": {
        "name": "Café La Montaña",
        "email": "hola@cafelamontana.co"
      },
      "from_name": "Café La Montaña",
      "from_email": "hola@cafelamontana.co",
      "reply_to": "",
      "lists": [
        "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
      ],
      "segment": null,
      "blocks": [
        {
          "type": "heading",
          "text": "Cosecha de noviembre",
          "level": 1
        },
        {
          "type": "text",
          "text": "Hola…"
        }
      ],
      "theme": {
        "color": "#0F766E"
      },
      "publish_to": "email",
      "status": "draft",
      "status_label": "Borrador",
      "status_reason": "",
      "send_at": null,
      "started_at": null,
      "finished_at": null,
      "current_batch": 0,
      "next_batch_at": null,
      "review": {},
      "stats": {},
      "approved_at": null,
      "issue_url": null,
      "audience_count": 1840,
      "requires_approval": false,
      "created_at": "2026-10-28T09:00:00-05:00",
      "updated_at": "2026-10-28T09:30:00-05:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

### Crear una campaña

`POST /campaigns` · permiso `marketing`

Un borrador. El contenido va en `blocks` (el formato del editor) o en `html` (se limpia: sin scripts, formularios ni iframes). El pie con tu dirección y el enlace de baja se agrega solo.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | string | sí | Nombre interno. |
| `subject` | string | no | Asunto (admite variables: `{{ nombre | "amigo" }}`). |
| `preheader` | string | no | Texto de vista previa. |
| `from` | object | no | `{name, email}`: el correo de un dominio verificado. |
| `reply_to` | string | no | Responder a. |
| `lists` | array | no | Ids de listas. |
| `segment` | uuid | no | Id de un segmento. |
| `blocks` | array | no | Bloques del editor. |
| `html` | string | no | HTML propio, en vez de bloques. |
| `publish_to` | enum | no | Dónde se publica. Valores: `email`, `web`, `both`. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/campaigns' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Novedades de noviembre", "subject": "Llegó la cosecha de noviembre", "from": {"name": "Café La Montaña", "email": "hola@cafelamontana.co"}, "lists": ["5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"], "html": "<h1>Cosecha de noviembre</h1><p>Hola…</p>"}'
```

Respuesta `201`:

```json
{
  "object": "campaign",
  "id": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f",
  "name": "Novedades de noviembre",
  "subject": "Llegó la cosecha de noviembre, {{ nombre | \"amigo\" }}",
  "preheader": "Tres cafés nuevos y envío gratis este fin de semana.",
  "from": {
    "name": "Café La Montaña",
    "email": "hola@cafelamontana.co"
  },
  "from_name": "Café La Montaña",
  "from_email": "hola@cafelamontana.co",
  "reply_to": "",
  "lists": [
    "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
  ],
  "segment": null,
  "blocks": [
    {
      "type": "heading",
      "text": "Cosecha de noviembre",
      "level": 1
    },
    {
      "type": "text",
      "text": "Hola…"
    }
  ],
  "theme": {
    "color": "#0F766E"
  },
  "publish_to": "email",
  "status": "draft",
  "status_label": "Borrador",
  "status_reason": "",
  "send_at": null,
  "started_at": null,
  "finished_at": null,
  "current_batch": 0,
  "next_batch_at": null,
  "review": {},
  "stats": {},
  "approved_at": null,
  "issue_url": null,
  "audience_count": 1840,
  "requires_approval": false,
  "created_at": "2026-10-28T09:00:00-05:00",
  "updated_at": "2026-10-28T09:30:00-05:00"
}
```

### Consultar una campaña

`GET /campaigns/{id}` · permiso `marketing`

La campaña, su estado y el tamaño de su audiencia.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/campaigns/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "object": "campaign",
  "id": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f",
  "name": "Novedades de noviembre",
  "subject": "Llegó la cosecha de noviembre, {{ nombre | \"amigo\" }}",
  "preheader": "Tres cafés nuevos y envío gratis este fin de semana.",
  "from": {
    "name": "Café La Montaña",
    "email": "hola@cafelamontana.co"
  },
  "from_name": "Café La Montaña",
  "from_email": "hola@cafelamontana.co",
  "reply_to": "",
  "lists": [
    "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
  ],
  "segment": null,
  "blocks": [
    {
      "type": "heading",
      "text": "Cosecha de noviembre",
      "level": 1
    },
    {
      "type": "text",
      "text": "Hola…"
    }
  ],
  "theme": {
    "color": "#0F766E"
  },
  "publish_to": "email",
  "status": "draft",
  "status_label": "Borrador",
  "status_reason": "",
  "send_at": null,
  "started_at": null,
  "finished_at": null,
  "current_batch": 0,
  "next_batch_at": null,
  "review": {},
  "stats": {},
  "approved_at": null,
  "issue_url": null,
  "audience_count": 1840,
  "requires_approval": false,
  "created_at": "2026-10-28T09:00:00-05:00",
  "updated_at": "2026-10-28T09:30:00-05:00"
}
```

### Editar una campaña

`PATCH /campaigns/{id}` · permiso `marketing`

Solo mientras es borrador.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `subject` | string | no | Asunto. |
| `blocks` | array | no | Bloques. |
| `html` | string | no | HTML. |

Ejemplo:

```bash
curl -X PATCH 'https://api.mailko.co/v1/campaigns/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200`:

```json
{
  "object": "campaign",
  "id": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f",
  "name": "Novedades de noviembre",
  "subject": "Llegó la cosecha de noviembre, {{ nombre | \"amigo\" }}",
  "preheader": "Tres cafés nuevos y envío gratis este fin de semana.",
  "from": {
    "name": "Café La Montaña",
    "email": "hola@cafelamontana.co"
  },
  "from_name": "Café La Montaña",
  "from_email": "hola@cafelamontana.co",
  "reply_to": "",
  "lists": [
    "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
  ],
  "segment": null,
  "blocks": [
    {
      "type": "heading",
      "text": "Cosecha de noviembre",
      "level": 1
    },
    {
      "type": "text",
      "text": "Hola…"
    }
  ],
  "theme": {
    "color": "#0F766E"
  },
  "publish_to": "email",
  "status": "draft",
  "status_label": "Borrador",
  "status_reason": "",
  "send_at": null,
  "started_at": null,
  "finished_at": null,
  "current_batch": 0,
  "next_batch_at": null,
  "review": {},
  "stats": {},
  "approved_at": null,
  "issue_url": null,
  "audience_count": 1840,
  "requires_approval": false,
  "created_at": "2026-10-28T09:00:00-05:00",
  "updated_at": "2026-10-28T09:30:00-05:00"
}
```

### Revisar antes de enviar

`POST /campaigns/{id}/review` · permiso `marketing`

La lista de verificación (lo que bloquea: remitente sin verificar, falta la dirección física, audiencia vacía…) y la lectura de la IA, que solo advierte.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/campaigns/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/review' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200`:

```json
{
  "object": "campaign_review",
  "campaign": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f",
  "ok": true,
  "blockers": [],
  "warnings": [
    "12 contactos no tienen «nombre»: dale un valor por defecto, {{ nombre | \"…\" }}."
  ],
  "ai": {
    "score": 18,
    "summary": "Contenido claro y sin señales de spam.",
    "warnings": []
  },
  "audience": 1840,
  "reviewed_at": "2026-10-28T09:31:00-05:00"
}
```

### Programar una campaña

`POST /campaigns/{id}/schedule` · permiso `marketing`

Sale a la hora indicada. Exige `{"confirm": true}`. Las primeras campañas de un proyecto quedan en `review` hasta que el equipo de Mailko las apruebe.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `send_at` | datetime | sí | Cuándo (ISO 8601). Sin desfase horario se lee en la zona horaria de tu empresa. |
| `confirm` | boolean | sí | `true`: confirmas que revisaste la campaña. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/campaigns/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/schedule' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"send_at": "2026-11-03T09:00:00-05:00", "confirm": true}'
```

Respuesta `202`:

```json
{
  "object": "campaign",
  "id": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f",
  "name": "Novedades de noviembre",
  "subject": "Llegó la cosecha de noviembre, {{ nombre | \"amigo\" }}",
  "preheader": "Tres cafés nuevos y envío gratis este fin de semana.",
  "from": {
    "name": "Café La Montaña",
    "email": "hola@cafelamontana.co"
  },
  "from_name": "Café La Montaña",
  "from_email": "hola@cafelamontana.co",
  "reply_to": "",
  "lists": [
    "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
  ],
  "segment": null,
  "blocks": [
    {
      "type": "heading",
      "text": "Cosecha de noviembre",
      "level": 1
    },
    {
      "type": "text",
      "text": "Hola…"
    }
  ],
  "theme": {
    "color": "#0F766E"
  },
  "publish_to": "email",
  "status": "scheduled",
  "status_label": "Programada",
  "status_reason": "",
  "send_at": null,
  "started_at": null,
  "finished_at": null,
  "current_batch": 0,
  "next_batch_at": null,
  "review": {},
  "stats": {},
  "approved_at": null,
  "issue_url": null,
  "audience_count": 1840,
  "requires_approval": false,
  "created_at": "2026-10-28T09:00:00-05:00",
  "updated_at": "2026-10-28T09:30:00-05:00"
}
```

### Enviar una campaña ya

`POST /campaigns/{id}/send` · permiso `marketing`

Empieza el envío escalonado (2 %, 5 % y el resto, con pausas para medir rebotes y quejas). Exige `{"confirm": true}`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `confirm` | boolean | sí | `true`: confirmas que revisaste la campaña. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/campaigns/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/send' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'
```

Respuesta `202`:

```json
{
  "object": "campaign",
  "id": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f",
  "name": "Novedades de noviembre",
  "subject": "Llegó la cosecha de noviembre, {{ nombre | \"amigo\" }}",
  "preheader": "Tres cafés nuevos y envío gratis este fin de semana.",
  "from": {
    "name": "Café La Montaña",
    "email": "hola@cafelamontana.co"
  },
  "from_name": "Café La Montaña",
  "from_email": "hola@cafelamontana.co",
  "reply_to": "",
  "lists": [
    "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
  ],
  "segment": null,
  "blocks": [
    {
      "type": "heading",
      "text": "Cosecha de noviembre",
      "level": 1
    },
    {
      "type": "text",
      "text": "Hola…"
    }
  ],
  "theme": {
    "color": "#0F766E"
  },
  "publish_to": "email",
  "status": "scheduled",
  "status_label": "Programada",
  "status_reason": "",
  "send_at": null,
  "started_at": null,
  "finished_at": null,
  "current_batch": 0,
  "next_batch_at": null,
  "review": {},
  "stats": {},
  "approved_at": null,
  "issue_url": null,
  "audience_count": 1840,
  "requires_approval": false,
  "created_at": "2026-10-28T09:00:00-05:00",
  "updated_at": "2026-10-28T09:30:00-05:00"
}
```

### Pausar una campaña

`POST /campaigns/{id}/pause` · permiso `marketing`

Detiene el envío; lo que falta queda pendiente.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/campaigns/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/pause' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200`:

```json
{
  "object": "campaign",
  "id": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f",
  "name": "Novedades de noviembre",
  "subject": "Llegó la cosecha de noviembre, {{ nombre | \"amigo\" }}",
  "preheader": "Tres cafés nuevos y envío gratis este fin de semana.",
  "from": {
    "name": "Café La Montaña",
    "email": "hola@cafelamontana.co"
  },
  "from_name": "Café La Montaña",
  "from_email": "hola@cafelamontana.co",
  "reply_to": "",
  "lists": [
    "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
  ],
  "segment": null,
  "blocks": [
    {
      "type": "heading",
      "text": "Cosecha de noviembre",
      "level": 1
    },
    {
      "type": "text",
      "text": "Hola…"
    }
  ],
  "theme": {
    "color": "#0F766E"
  },
  "publish_to": "email",
  "status": "paused",
  "status_label": "Pausada",
  "status_reason": "",
  "send_at": null,
  "started_at": null,
  "finished_at": null,
  "current_batch": 0,
  "next_batch_at": null,
  "review": {},
  "stats": {},
  "approved_at": null,
  "issue_url": null,
  "audience_count": 1840,
  "requires_approval": false,
  "created_at": "2026-10-28T09:00:00-05:00",
  "updated_at": "2026-10-28T09:30:00-05:00"
}
```

### Cancelar una campaña

`POST /campaigns/{id}/cancel` · permiso `marketing`

No sale nada más. Lo que no se envió no se cobra.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/campaigns/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/cancel' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200`:

```json
{
  "object": "campaign",
  "id": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f",
  "name": "Novedades de noviembre",
  "subject": "Llegó la cosecha de noviembre, {{ nombre | \"amigo\" }}",
  "preheader": "Tres cafés nuevos y envío gratis este fin de semana.",
  "from": {
    "name": "Café La Montaña",
    "email": "hola@cafelamontana.co"
  },
  "from_name": "Café La Montaña",
  "from_email": "hola@cafelamontana.co",
  "reply_to": "",
  "lists": [
    "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"
  ],
  "segment": null,
  "blocks": [
    {
      "type": "heading",
      "text": "Cosecha de noviembre",
      "level": 1
    },
    {
      "type": "text",
      "text": "Hola…"
    }
  ],
  "theme": {
    "color": "#0F766E"
  },
  "publish_to": "email",
  "status": "canceled",
  "status_label": "Cancelada",
  "status_reason": "",
  "send_at": null,
  "started_at": null,
  "finished_at": null,
  "current_batch": 0,
  "next_batch_at": null,
  "review": {},
  "stats": {},
  "approved_at": null,
  "issue_url": null,
  "audience_count": 1840,
  "requires_approval": false,
  "created_at": "2026-10-28T09:00:00-05:00",
  "updated_at": "2026-10-28T09:30:00-05:00"
}
```

### Estadísticas de una campaña

`GET /campaigns/{id}/stats` · permiso `marketing`

Entregas, rebotes, quejas, aperturas (aproximadas: Apple Mail precarga las imágenes), clics por enlace y por hora, y bajas.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/campaigns/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/stats' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "object": "campaign_stats",
  "campaign": "7c6d5e4f-3a2b-4c1d-8e9f-0a1b2c3d4e5f",
  "recipients": 1840,
  "pending": 0,
  "sent": 1832,
  "skipped": 8,
  "failed": 0,
  "delivered": 1820,
  "bounced": 9,
  "complained": 0,
  "opened": 702,
  "clicked": 133,
  "unsubscribed": 4,
  "rates": {
    "delivery": 0.9934,
    "bounce": 0.0049,
    "complaint": 0,
    "open": 0.3857,
    "click": 0.0731,
    "unsubscribe": 0.0022
  },
  "opens_are_approximate": true,
  "by_hour": [
    {
      "hour": "2026-10-28T10:00:00-05:00",
      "opened": 310,
      "clicked": 61
    }
  ],
  "links": [
    {
      "url": "https://cafelamontana.co/tienda",
      "clicks": 150,
      "unique_clicks": 121
    }
  ]
}
```

## Importaciones

Subir contactos desde un CSV, con informe.

### El objeto importación

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string |  |
| `id` | string |  |
| `file_name` | string |  |
| `status` | string | previewed, review, running, done, failed o rejected. |
| `requires_review` | boolean | Lista grande o con muchas direcciones descartadas: la revisa Mailko antes de importarla. |
| `mapping` | object |  |
| `list` | string |  |
| `counts` | object |  |
| `report` | object |  |
| `created_at` | string |  |

### Listar importaciones

`GET /imports` · permiso `marketing`

Las importaciones del proyecto y su informe.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `page` | integer | no | Página, desde 1. Por defecto `1`. |
| `page_size` | integer | no | Resultados por página, de 1 a 100. Por defecto `20`. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/imports' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "data": [
    {
      "object": "import",
      "id": "8d7e6f5a-4b3c-4d2e-9f0a-1b2c3d4e5f6a",
      "file_name": "clientes.csv",
      "status": "previewed",
      "requires_review": false,
      "mapping": {
        "Correo": "email",
        "Nombre": "first_name"
      },
      "list": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
      "counts": {
        "total": 1900,
        "valid": 1840,
        "invalid": 22,
        "duplicates": 30,
        "disposable": 3,
        "no_mx": 5,
        "suppressed": 0,
        "unsubscribed": 0,
        "new": 1700,
        "existing": 140
      },
      "report": {
        "discard_ratio": 0.0316,
        "needs_review": false
      },
      "created_at": "2026-10-28T08:50:00-05:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

### Subir una importación

`POST /imports` · permiso `marketing`

Paso 1: el CSV en base64, el mapeo de columnas y tu declaración de origen y consentimiento. Responde el informe (inválidos, duplicados, desechables, sin MX, suprimidos); no importa nada hasta `/confirm`.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `file` | string | sí | El CSV en base64 (hasta 10 MB). |
| `filename` | string | no | Nombre del archivo. |
| `mapping` | object | no | Columna del archivo → campo (`email`, `first_name`, `fields.ciudad`…). |
| `list` | uuid | no | Lista a la que entran. |
| `tags` | array | no | Etiquetas para todos. |
| `declaration` | object | sí | `{source, consent: true}`: de dónde salió la lista y que autorizaron recibir tus correos. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/imports' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"file": "Q29ycmVvLE5vbWJyZQphbmFAY29ycmVvLmNvLEFuYQo=", "filename": "clientes.csv", "declaration": {"source": "Clientes de la tienda que aceptaron el boletín al comprar", "consent": true}}'
```

Respuesta `201`:

```json
{
  "object": "import",
  "id": "8d7e6f5a-4b3c-4d2e-9f0a-1b2c3d4e5f6a",
  "file_name": "clientes.csv",
  "status": "previewed",
  "requires_review": false,
  "mapping": {
    "Correo": "email",
    "Nombre": "first_name"
  },
  "list": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "counts": {
    "total": 1900,
    "valid": 1840,
    "invalid": 22,
    "duplicates": 30,
    "disposable": 3,
    "no_mx": 5,
    "suppressed": 0,
    "unsubscribed": 0,
    "new": 1700,
    "existing": 140
  },
  "report": {
    "discard_ratio": 0.0316,
    "needs_review": false
  },
  "created_at": "2026-10-28T08:50:00-05:00"
}
```

### Consultar una importación

`GET /imports/{id}` · permiso `marketing`

Su estado y su informe.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/imports/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "object": "import",
  "id": "8d7e6f5a-4b3c-4d2e-9f0a-1b2c3d4e5f6a",
  "file_name": "clientes.csv",
  "status": "previewed",
  "requires_review": false,
  "mapping": {
    "Correo": "email",
    "Nombre": "first_name"
  },
  "list": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "counts": {
    "total": 1900,
    "valid": 1840,
    "invalid": 22,
    "duplicates": 30,
    "disposable": 3,
    "no_mx": 5,
    "suppressed": 0,
    "unsubscribed": 0,
    "new": 1700,
    "existing": 140
  },
  "report": {
    "discard_ratio": 0.0316,
    "needs_review": false
  },
  "created_at": "2026-10-28T08:50:00-05:00"
}
```

### Confirmar una importación

`POST /imports/{id}/confirm` · permiso `marketing`

Paso 2: importa las filas válidas. Una lista grande o con muchas direcciones descartadas queda en `review` (`202`) hasta que el equipo de Mailko la revise.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | uuid | sí | Identificador del recurso. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/imports/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/confirm' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200`:

```json
{
  "object": "import",
  "id": "8d7e6f5a-4b3c-4d2e-9f0a-1b2c3d4e5f6a",
  "file_name": "clientes.csv",
  "status": "done",
  "requires_review": false,
  "mapping": {
    "Correo": "email",
    "Nombre": "first_name"
  },
  "list": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "counts": {
    "total": 1900,
    "valid": 1840,
    "invalid": 22,
    "duplicates": 30,
    "disposable": 3,
    "no_mx": 5,
    "suppressed": 0,
    "unsubscribed": 0,
    "new": 1700,
    "existing": 140
  },
  "report": {
    "discard_ratio": 0.0316,
    "needs_review": false
  },
  "created_at": "2026-10-28T08:50:00-05:00"
}
```

## Tu API key

Para comprobar que la key funciona.

### El objeto api key

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string | Siempre `api_key`. |
| `id` | uuid | Identificador de la key. |
| `name` | string | Nombre que le diste. |
| `prefix` | string | Prefijo público de la key, para reconocerla en listas y registros. |
| `mode` | enum | `live` (entrega) o `test` (valida y no entrega). |
| `scopes` | array | Permisos de la key. |
| `expires_at` | datetime | Vencimiento, o `null` si no vence. |
| `organization` | object | La empresa dueña de la key: `id` y `name`. |
| `workspace` | object | El proyecto de la key: `id`, `name` y `status`. |
| `api_version` | string | Versión de la API. |

### Tu API key

`GET /me` · permiso cualquier API key

Qué key usas, de qué empresa y con qué permisos: para probar la conexión.

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/me' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "object": "api_key",
  "id": "d9c8b7a6-5f4e-4d3c-2b1a-0f9e8d7c6b5a",
  "name": "Servidor de producción",
  "prefix": "mk_live_Ab12Cd34",
  "scopes": [
    "admin"
  ],
  "expires_at": "2027-10-01T23:59:59-05:00",
  "organization": {
    "id": "11111111-2222-4333-8444-555555555555",
    "name": "Café La Montaña SAS"
  },
  "api_version": "2026-10-01"
}
```

## Apps socias (Conectar Mailko)

Para apps aliadas de Mailko: conectar la cuenta de un cliente con un botón, con su llave de socio (`mkp_live_…`). Mailko avisa a tu webhook con `connection.revoked` (firmado con `Mailko-Signature` y el secreto de tu app) cuando una conexión termina.

### Pedir un enlace de conexión

`POST /partner/link-requests` · permiso `partner`

Solo apps socias, con su **llave de socio** (`mkp_live_…`). Devuelve un enlace de un solo uso (60 minutos) a la pantalla de consentimiento de Mailko, donde el cliente inicia sesión, elige su proyecto y acepta. Mailko lo devuelve a `return_url` con `status=linked&code=…&external_id=…`, `status=cancelled` o `status=failed&reason=expired|used|not_eligible|external_id_taken`. Pedirlo de nuevo crea otro enlace.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | string | sí | Cómo llama tu app a la cuenta (se muestra al cliente). |
| `external_id` | string | sí | Tu identificador de la cuenta: vuelve en la redirección. |
| `return_url` | string | sí | URL https de uno de los orígenes registrados de tu app. |
| `scopes` | array | sí | Permisos de la key que pides: `send`, `read`. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/partner/link-requests' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Gimnasio Andes", "external_id": "bucli-link:3f0c9a1e", "return_url": "https://app.bucli.co/configuracion/mensajes?flujo=mailko", "scopes": ["send", "read"]}'
```

Respuesta `201`:

```json
{
  "id": "lr_Q2x7Vb9Kp3Lm8Nn4Rt6Ws1Yz",
  "url": "https://app.mailko.co/vincular/<token>",
  "expires_at": "2026-11-11T11:00:00-05:00"
}
```

### Canjear el código

`POST /partner/link-requests/exchange` · permiso `partner`

Cambia el `code` que trajo la redirección por la API key del proyecto que eligió el cliente. La key sale **una sola vez**: guárdala cifrada. El código vale 10 minutos y un solo canje; si la respuesta se pierde, reintenta con la **misma** `Idempotency-Key` antes de que venza y recibirás un secreto nuevo (el anterior deja de servir). Con la key, tu app usa la API como cualquier integración (`GET /domains`, `POST /emails`…).

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `code` | string | sí | El `code` de la redirección. |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/partner/link-requests/exchange' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"code": "<code>"}'
```

Respuesta `200`:

```json
{
  "connection_id": "con_H8s2Kd9Lq4Wm7Pz1Xc5Vb3Nr",
  "external_id": "bucli-link:3f0c9a1e",
  "api_key": "mk_live_…",
  "workspace": {
    "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d",
    "name": "Gimnasio Andes"
  },
  "scopes": [
    "send",
    "read"
  ],
  "linked_at": "2026-11-11T10:05:00-05:00"
}
```

### Consultar una conexión

`GET /partner/connections/{id}` · permiso `partner`

Su estado (`active` o `revoked`), el proyecto, los permisos y, si terminó, cuándo y por qué (`owner`, `partner`, `key_revoked`, `workspace_suspended`, `workspace_deleted`).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id de la conexión (`con_…`). |

Ejemplo:

```bash
curl -X GET 'https://api.mailko.co/v1/partner/connections/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
  -H "Authorization: Bearer $MAILKO_API_KEY"
```

Respuesta `200`:

```json
{
  "id": "con_H8s2Kd9Lq4Wm7Pz1Xc5Vb3Nr",
  "external_id": "bucli-link:3f0c9a1e",
  "status": "active",
  "workspace": {
    "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d",
    "name": "Gimnasio Andes"
  },
  "scopes": [
    "send",
    "read"
  ],
  "linked_at": "2026-11-11T10:05:00-05:00",
  "revoked_at": null,
  "revoked_reason": null
}
```

### Revocar una conexión

`POST /partner/connections/{id}/revoke` · permiso `partner`

Termina la conexión y revoca su API key al instante. Idempotente: revocar una ya revocada responde lo mismo. Mailko avisa con `connection.revoked` cuando la revoca otro (el cliente, el equipo de Mailko).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id de la conexión (`con_…`). |

Ejemplo:

```bash
curl -X POST 'https://api.mailko.co/v1/partner/connections/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/revoke' \
  -H "Authorization: Bearer $MAILKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Respuesta `200`:

```json
{
  "id": "con_H8s2Kd9Lq4Wm7Pz1Xc5Vb3Nr",
  "external_id": "bucli-link:3f0c9a1e",
  "status": "revoked",
  "workspace": {
    "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d",
    "name": "Gimnasio Andes"
  },
  "scopes": [
    "send",
    "read"
  ],
  "linked_at": "2026-11-11T10:05:00-05:00",
  "revoked_at": "2026-11-12T09:00:00-05:00",
  "revoked_reason": "partner"
}
```

## Webhooks

Un webhook le avisa a tu servidor en el momento en que pasa algo en Mailko, sin que tengas que preguntar. Mailko hace un `POST` con JSON a tu dirección HTTPS y espera un `2xx` en menos de 10 segundos.

**Reintentos.** Si tu servidor no responde `2xx`, Mailko reintenta el mismo evento (mismo `id`) a los 1, 5 y 30 minutos, 2 horas y 12 horas. Tras 20 entregas fallidas seguidas, el webhook se apaga solo y avisamos al dueño de la empresa; al apagarse, lo pendiente se omite. Puedes reenviar cualquier entrega desde su historial.

**Al menos una vez.** Un evento puede llegar repetido (un reintento cuya respuesta se perdió): deduplica por `id` (también en la cabecera `Mailko-Event-Id`). El orden de llegada no está garantizado: usa `created_at` y, ante la duda, consulta el recurso con la API.

**El cuerpo** es siempre el mismo sobre, y `data.object` es el mismo objeto que responde la API para ese recurso:

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "email.delivered",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "id": "7d4c2b1a-…",
      "object": "email",
      "…": "…"
    }
  }
}
```

`source` dice quién hizo el cambio: `app` (una persona en Mailko), `api` (una integración con una API key), `import` (una importación) o `system` (Mailko solo). Así tu integración puede ignorar el eco de sus propios cambios.

**Cabeceras**

| Cabecera | Qué trae |
|---|---|
| `Mailko-Event-Id` | Id del evento (para deduplicar) |
| `Mailko-Event-Type` | Tipo de evento |
| `Mailko-Delivery-Id` | Id de esta entrega |
| `Mailko-Signature` | Momento del envío y firma: `t=<tiempo Unix>,v1=<firma>` |

Mailko no sigue redirecciones ni llama direcciones internas: usa la dirección final y pública de tu servidor.

### Eventos

| Evento | Cuándo |
|---|---|
| `email.sent` | Amazon SES aceptó el correo para entregarlo. |
| `email.delivered` | El servidor del destinatario recibió el correo. |
| `email.bounced` | El servidor del destinatario devolvió el correo. |
| `email.complained` | El destinatario marcó el correo como no deseado. |
| `email.delayed` | La entrega se está demorando; SES sigue intentando. |
| `email.failed` | El correo no se pudo enviar. |
| `email.opened` | El destinatario abrió el correo (aproximado). |
| `email.clicked` | El destinatario hizo clic en un enlace del correo. |
| `domain.verified` | El dominio quedó listo para enviar. |
| `domain.failed` | El dominio no se verificó, venció o perdió su autenticación. |
| `workspace.status_changed` | El proyecto entró o salió de observación, se pausó o se reanudó. |

#### `email.sent`

Amazon SES aceptó el correo para entregarlo.

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "email.sent",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "object": "email",
      "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d"
    }
  }
}
```

#### `email.delivered`

El servidor del destinatario recibió el correo.

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "email.delivered",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "object": "email",
      "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d"
    }
  }
}
```

#### `email.bounced`

El servidor del destinatario devolvió el correo.

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "email.bounced",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "object": "email",
      "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d"
    }
  }
}
```

#### `email.complained`

El destinatario marcó el correo como no deseado.

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "email.complained",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "object": "email",
      "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d"
    }
  }
}
```

#### `email.delayed`

La entrega se está demorando; SES sigue intentando.

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "email.delayed",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "object": "email",
      "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d"
    }
  }
}
```

#### `email.failed`

El correo no se pudo enviar.

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "email.failed",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "object": "email",
      "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d"
    }
  }
}
```

#### `email.opened`

El destinatario abrió el correo (aproximado).

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "email.opened",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "object": "email",
      "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d"
    }
  }
}
```

#### `email.clicked`

El destinatario hizo clic en un enlace del correo.

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "email.clicked",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "object": "email",
      "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d"
    }
  }
}
```

#### `domain.verified`

El dominio quedó listo para enviar.

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "domain.verified",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "object": "domain",
      "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d"
    }
  }
}
```

#### `domain.failed`

El dominio no se verificó, venció o perdió su autenticación.

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "domain.failed",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "object": "domain",
      "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d"
    }
  }
}
```

#### `workspace.status_changed`

El proyecto entró o salió de observación, se pausó o se reanudó.

```json
{
  "id": "2b4d6f80-1a3c-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "workspace.status_changed",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "organization_id": "11111111-2222-4333-8444-555555555555",
  "workspace_id": "22222222-3333-4444-8555-666666666666",
  "data": {
    "object": {
      "object": "workspace",
      "id": "7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d"
    }
  }
}
```

## Verificar firmas

Cada entrega va firmada con el **secreto de firma** del webhook (empieza por `whsec_`; se muestra completo solo al crearlo o al rotarlo). La firma llega en la cabecera `Mailko-Signature`, con esta forma:

```
Mailko-Signature: t=1791817339,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

`t` es el momento del envío (tiempo Unix, segundos) y `v1` la firma. Verifícala antes de confiar en el contenido:

1. Separa `t` y `v1` de la cabecera `Mailko-Signature`.
2. Toma el **cuerpo crudo**, tal como llegó (no lo vuelvas a serializar).
3. Calcula `HMAC-SHA256(secreto, "<t>.<cuerpo>")` en hexadecimal.
4. Compáralo con `v1` con una comparación de tiempo constante.
5. Rechaza la entrega si `t` tiene más de 5 minutos (evita que alguien repita un aviso capturado).
6. Responde `2xx` rápido y procesa después; deduplica por `Mailko-Event-Id`.

```python
import hashlib
import hmac
import time


def verify_mailko(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    """True si la entrega viene de Mailko y es reciente. `header`: la cabecera Mailko-Signature."""
    try:
        parts = dict(item.strip().split("=", 1) for item in header.split(","))
        timestamp, signature = parts["t"], parts["v1"]
        if abs(time.time() - int(timestamp)) > tolerance:
            return False
    except (KeyError, ValueError):
        return False
    signed = timestamp.encode() + b"." + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)


# Flask:
# ok = verify_mailko(SECRET, request.get_data(), request.headers.get("Mailko-Signature", ""))
```

```javascript
import crypto from 'node:crypto'

// Express: app.post('/webhooks/mailko', express.raw({ type: 'application/json' }), handler)
// const ok = verifyMailko(SECRET, req.body, req.get('Mailko-Signature'))
export function verifyMailko (secret, rawBody, header, tolerance = 300) {
  const parts = {}
  for (const item of (header || '').split(',')) {
    const i = item.indexOf('=')
    if (i > 0) parts[item.slice(0, i).trim()] = item.slice(i + 1).trim()
  }
  const timestamp = Number(parts.t)
  if (!parts.v1 || !Number.isInteger(timestamp)) return false
  if (Math.abs(Date.now() / 1000 - timestamp) > tolerance) return false
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.`)
    .update(rawBody)
    .digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(parts.v1)
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}
```

```php
<?php
function verify_mailko(string $secret, string $body, string $header, int $tolerance = 300): bool {
    $parts = [];
    foreach (explode(',', $header) as $item) {
        $pair = explode('=', trim($item), 2);
        if (count($pair) === 2) $parts[$pair[0]] = $pair[1];
    }
    if (!isset($parts['t'], $parts['v1']) || !ctype_digit($parts['t'])) return false;
    if (abs(time() - (int) $parts['t']) > $tolerance) return false;
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $body, $secret);
    return hash_equals($expected, $parts['v1']);
}
// $ok = verify_mailko($secret, file_get_contents('php://input'),
//     $_SERVER['HTTP_MAILKO_SIGNATURE'] ?? '');
```

## Registro de cambios

### 2026-10-01 — Primera versión pública

- API keys con permisos, vencimiento y regeneración.
- Webhooks administrables por API; eventos versionados con el origen del cambio (`source`).
- Idempotency-Key, límites por minuto, por segundo y por mes, e historial de peticiones.
- Marketing: contactos, listas, segmentos, importaciones y campañas con el permiso `marketing`.
- SMTP relay con tu API key (smtp.mailko.co, puertos 587 y 465).

### Próximamente

- SDKs oficiales para Node, Python y PHP.
