{"openapi":"3.1.0","info":{"title":"API de Mailko","version":"2026-10-01","description":"Correos transaccionales, dominios, plantillas y webhooks de tu empresa en Mailko."},"servers":[{"url":"https://api.mailko.co/v1"}],"security":[{"ApiKey":[]}],"tags":[{"name":"emails","description":"Enviar correos y ver qué pasó con ellos."},{"name":"domains","description":"Tus dominios de envío y sus registros DNS."},{"name":"suppressions","description":"Direcciones a las que no se envía."},{"name":"templates","description":"Plantillas versionadas con variables."},{"name":"usage","description":"Consumo del mes, saldo y límites."},{"name":"webhook-endpoints","description":"Administra por código los mismos webhooks de la pantalla Desarrolladores."},{"name":"contacts","description":"Tus contactos, sin perder bajas ni consentimientos."},{"name":"lists","description":"Listas de contactos y sus miembros."},{"name":"segments","description":"Contactos que cumplen unas reglas."},{"name":"campaigns","description":"Campañas de marketing con envío escalonado."},{"name":"imports","description":"Subir contactos desde un CSV, con informe."},{"name":"me","description":"Para comprobar que la key funciona."},{"name":"partner","description":"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."}],"paths":{"/emails":{"post":{"operationId":"emails-send","summary":"Enviar un correo","description":"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.","tags":["emails"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"description":"Aceptado","content":{"application/json":{"example":{"id":"msg_8f2k3j4h5g6f7d8s9a0q1w2e3r","object":"email","status":"queued","test_mode":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"send","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","description":"Remitente: `correo` o `Nombre <correo>` de un dominio verificado."},"to":{"type":"array","items":{},"description":"Destinatarios (o un solo correo como texto)."},"cc":{"type":"array","items":{},"description":"Copia."},"bcc":{"type":"array","items":{},"description":"Copia oculta."},"reply_to":{"type":"array","items":{},"description":"Responder a."},"subject":{"type":"string","description":"Asunto. Obligatorio sin plantilla."},"html":{"type":"string","description":"Cuerpo HTML."},"text":{"type":"string","description":"Cuerpo en texto plano."},"template":{"type":"object","description":"`{id, version?, variables?}`: alias o id de una plantilla y sus variables."},"headers":{"type":"object","description":"Cabeceras permitidas (List-Unsubscribe, In-Reply-To, References…)."},"attachments":{"type":"array","items":{},"description":"Hasta 20 adjuntos `{filename, content (base64), content_type}`."},"tags":{"type":"object","description":"Hasta 10 etiquetas `nombre: valor` para filtrar después."},"metadata":{"type":"object","description":"Datos tuyos que vuelven en los webhooks."},"stream":{"type":"string","enum":["transactional","marketing"],"description":"`transactional` o `marketing`. Mientras Mailko envíe solo correo transaccional, `marketing` responde `marketing_disabled`."}},"required":["from","to"]},"example":{"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"}}}}}},"get":{"operationId":"emails-list","summary":"Listar correos","description":"Los correos del proyecto, del más reciente al más antiguo.","tags":["emails"],"parameters":[{"name":"status","in":"query","required":false,"description":"Uno o varios estados separados por coma.","schema":{"type":"string"}},{"name":"recipient","in":"query","required":false,"description":"Correos a esta dirección.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"`nombre:valor` de una etiqueta.","schema":{"type":"string"}},{"name":"created_after","in":"query","required":false,"description":"Desde (AAAA-MM-DD, día en hora de Bogotá, UTC−5).","schema":{"type":"string","format":"date"}},{"name":"created_before","in":"query","required":false,"description":"Hasta, incluido.","schema":{"type":"string","format":"date"}},{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Resultados por página, de 1 a 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null}},"/emails/batch":{"post":{"operationId":"emails-batch","summary":"Enviar un lote","description":"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.","tags":["emails"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"description":"Aceptado","content":{"application/json":{"example":{"data":[{"id":"msg_8f2k3j4h5g6f7d8s9a0q1w2e3r","object":"email","status":"queued","test_mode":false}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"send","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{},"description":"Los correos, cada uno como en POST /emails."}},"required":["emails"]},"example":{"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"}}]}}}}}},"/emails/{id}":{"get":{"operationId":"emails-retrieve","summary":"Consultar un correo","description":"Estado de un correo y su línea de tiempo de eventos (`events`), con el motivo de cada rebote en palabras simples.","tags":["emails"],"parameters":[{"name":"id","in":"path","required":true,"description":"Id del correo (`msg_…`).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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":""}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null}},"/domains":{"get":{"operationId":"domains-list","summary":"Listar dominios","description":"Los dominios del proyecto con el estado de cada registro DNS.","tags":["domains"],"parameters":[{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Resultados por página, de 1 a 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null},"post":{"operationId":"domains-create","summary":"Agregar un dominio","description":"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.","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Creado","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"admin","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Tu dominio, sin http ni www (`tienda.co`)."}},"required":["name"]},"example":{"name":"tienda.co"}}}}}},"/domains/{id}":{"get":{"operationId":"domains-retrieve","summary":"Consultar un dominio","description":"Un dominio y sus registros DNS.","tags":["domains"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null},"delete":{"operationId":"domains-delete","summary":"Eliminar un dominio","description":"Quita la identidad de Amazon SES. Ningún correo vuelve a salir con ese dominio.","tags":["domains"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"204":{"description":"Sin contenido"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"admin","x-idempotency":"recommended"}},"/domains/{id}/verify":{"post":{"operationId":"domains-verify","summary":"Verificar ahora","description":"Revisa ya los registros (Mailko también lo hace solo) y responde el dominio con lo que encontró.","tags":["domains"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"admin","x-idempotency":"recommended"}},"/suppressions":{"get":{"operationId":"suppressions-list","summary":"Listar supresiones","description":"Direcciones a las que el proyecto no envía: rebotes duros, quejas, bajas y las que agregaste.","tags":["suppressions"],"parameters":[{"name":"reason","in":"query","required":false,"description":"Motivos separados por coma.","schema":{"type":"string"}},{"name":"email","in":"query","required":false,"description":"Buscar una dirección.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Resultados por página, de 1 a 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null},"post":{"operationId":"suppressions-create","summary":"Agregar una supresión","description":"Bloquea una dirección en este proyecto.","tags":["suppressions"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Creado","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"admin","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"La dirección."},"detail":{"type":"string","description":"Por qué."}},"required":["email"]},"example":{"email":"cliente@correo.com","detail":"Pidió no recibir más correos"}}}}}},"/suppressions/{id}":{"get":{"operationId":"suppressions-retrieve","summary":"Consultar una supresión","description":"Una supresión por su id.","tags":["suppressions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null},"delete":{"operationId":"suppressions-delete","summary":"Quitar una supresión","description":"Vuelve a permitir la dirección. Una queja o una solicitud de supresión de datos no se puede quitar.","tags":["suppressions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"204":{"description":"Sin contenido"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"admin","x-idempotency":"recommended"}},"/templates":{"get":{"operationId":"templates-list","summary":"Listar plantillas","description":"Las plantillas del proyecto con su versión vigente.","tags":["templates"],"parameters":[{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Resultados por página, de 1 a 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null}},"/templates/{id}":{"get":{"operationId":"templates-retrieve","summary":"Consultar una plantilla","description":"Una plantilla y su versión vigente con sus variables.","tags":["templates"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null}},"/usage":{"get":{"operationId":"usage-retrieve","summary":"Consumo del mes","description":"Lo que llevas del mes, lo que te queda del plan y de las bolsas, el excedente y los límites del proyecto hoy.","tags":["usage"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null}},"/webhook-endpoints":{"get":{"operationId":"webhooks-list","summary":"Listar webhooks","description":"Los webhooks de tu empresa.","tags":["webhook-endpoints"],"parameters":[{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Resultados por página, de 1 a 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null},"post":{"operationId":"webhooks-create","summary":"Crear un webhook","description":"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`.","tags":["webhook-endpoints"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Creado","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"admin","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Dirección HTTPS pública (sin redirecciones)."},"description":{"type":"string","description":"Para qué es."},"topics":{"type":"array","items":{},"description":"Eventos (ver /webhook-events). Obligatorio: cada evento exige el permiso de lectura de su objeto."},"is_active":{"type":"boolean","description":"Encendido."}},"required":["url","topics"]},"example":{"url":"https://mi-app.co/webhooks/mailko","description":"Avisos de entrega","topics":["email.delivered","email.bounced"]}}}}}},"/webhook-endpoints/{id}":{"get":{"operationId":"webhooks-retrieve","summary":"Consultar un webhook","description":"Un webhook por su id.","tags":["webhook-endpoints"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null},"patch":{"operationId":"webhooks-update","summary":"Actualizar un webhook","description":"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.","tags":["webhook-endpoints"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"admin","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Dirección."},"description":{"type":"string","description":"Para qué es."},"topics":{"type":"array","items":{},"description":"Eventos (cada uno con el permiso de lectura de su objeto)."},"is_active":{"type":"boolean","description":"Encendido."}}},"example":{"is_active":false}}}}},"delete":{"operationId":"webhooks-delete","summary":"Eliminar un webhook","description":"Deja de enviarle eventos y borra su historial de entregas.","tags":["webhook-endpoints"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"204":{"description":"Sin contenido"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"admin","x-idempotency":"recommended"}},"/webhook-endpoints/{id}/rotate-secret":{"post":{"operationId":"webhooks-rotate-secret","summary":"Rotar el secreto de firma","description":"Genera un secreto nuevo y lo responde por única vez. El anterior deja de firmar de inmediato.","tags":["webhook-endpoints"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"admin","x-idempotency":"recommended"}},"/webhook-endpoints/{id}/test":{"post":{"operationId":"webhooks-test","summary":"Enviar un evento de prueba","description":"Envía ya un evento `ping` firmado (aunque el webhook esté apagado) y responde la entrega con lo que contestó tu servidor.","tags":["webhook-endpoints"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"admin","x-idempotency":"recommended"}},"/webhook-endpoints/{id}/deliveries":{"get":{"operationId":"webhooks-deliveries","summary":"Historial de entregas","description":"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.","tags":["webhook-endpoints"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"description":"Estado.","schema":{"type":"string","enum":["pending","delivered","failed","skipped"]}},{"name":"type","in":"query","required":false,"description":"Tipo de evento.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Resultados por página, de 1 a 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"read","x-idempotency":null}},"/webhook-endpoints/{id}/deliveries/{delivery_id}/redeliver":{"post":{"operationId":"webhooks-redeliver","summary":"Reenviar una entrega","description":"Envía otra vez el mismo evento (mismo `id`, para que tu servidor lo deduplique).","tags":["webhook-endpoints"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"name":"delivery_id","in":"path","required":true,"description":"La entrega.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"admin","x-idempotency":"recommended"}},"/webhook-events":{"get":{"operationId":"webhooks-events","summary":"Tipos de evento","description":"Los eventos a los que se puede suscribir un webhook.","tags":["webhook-endpoints"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"type":"email.delivered","group":"emails","group_label":"Correos","label":"Correo entregado","description":"SES confirmó la entrega al servidor del destinatario.","object":"email"}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":null,"x-idempotency":null}},"/contacts":{"get":{"operationId":"contacts-list","summary":"Listar contactos","description":"Los contactos del proyecto, del más reciente al más antiguo.","tags":["contacts"],"parameters":[{"name":"status","in":"query","required":false,"description":"Uno o varios estados separados por coma.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Contactos con esta etiqueta.","schema":{"type":"string"}},{"name":"list","in":"query","required":false,"description":"Contactos de esta lista.","schema":{"type":"string","format":"uuid"}},{"name":"segment","in":"query","required":false,"description":"Contactos que cumplen este segmento.","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","required":false,"description":"Busca en correo, nombre y apellido.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Resultados por página, de 1 a 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":null},"post":{"operationId":"contacts-upsert","summary":"Crear o actualizar un contacto","description":"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`.","tags":["contacts"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Creado","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Correo."},"first_name":{"type":"string","description":"Nombre."},"last_name":{"type":"string","description":"Apellido."},"country":{"type":"string","description":"País (ISO de dos letras)."},"fields":{"type":"object","description":"Campos propios del proyecto."},"tags":{"type":"array","items":{},"description":"Etiquetas."},"lists":{"type":"array","items":{},"description":"Ids de listas a las que se suma."},"status":{"type":"string","enum":["subscribed","pending","unsubscribed"],"description":"Estado inicial."}},"required":["email"]},"example":{"email":"ana@correo.co","first_name":"Ana","tags":["cliente"]}}}}}},"/contacts/{id}":{"get":{"operationId":"contacts-retrieve","summary":"Consultar un contacto","description":"Datos, estado, listas y actividad.","tags":["contacts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":null},"patch":{"operationId":"contacts-update","summary":"Editar un contacto","description":"Cambia sus datos. El correo no cambia. Reactivar a quien se dio de baja solo se hace en el panel, confirmando el consentimiento.","tags":["contacts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","description":"Nombre."},"last_name":{"type":"string","description":"Apellido."},"country":{"type":"string","description":"País."},"fields":{"type":"object","description":"Campos propios."},"tags":{"type":"array","items":{},"description":"Etiquetas que se suman."},"lists":{"type":"array","items":{},"description":"Listas a las que se suma."},"status":{"type":"string","enum":["subscribed","pending","unsubscribed"],"description":"Nuevo estado."}}}}}}},"delete":{"operationId":"contacts-delete","summary":"Eliminar un contacto","description":"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.","tags":["contacts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"204":{"description":"Sin contenido"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended"}},"/lists":{"get":{"operationId":"lists-list","summary":"Listar listas","description":"Las listas del proyecto con su número de contactos.","tags":["lists"],"parameters":[{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Resultados por página, de 1 a 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":null},"post":{"operationId":"lists-create","summary":"Crear una lista","description":"Una lista nueva, vacía.","tags":["lists"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Creado","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nombre."},"description":{"type":"string","description":"Descripción."},"double_opt_in":{"type":"boolean","description":"Pedir confirmación en sus formularios."}},"required":["name"]},"example":{"name":"Clientes"}}}}}},"/lists/{id}":{"get":{"operationId":"lists-retrieve","summary":"Consultar una lista","description":"Una lista y su número de contactos.","tags":["lists"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":null}},"/lists/{id}/contacts":{"post":{"operationId":"lists-add-contacts","summary":"Agregar contactos a una lista","description":"Hasta 1.000 correos (`{\"contacts\": [...]}`). Los que no existen se crean.","tags":["lists"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"object":"list_membership","list":"5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d","added":2}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{},"description":"Correos."}},"required":["contacts"]},"example":{"contacts":["ana@correo.co","luis@correo.co"]}}}}},"delete":{"operationId":"lists-remove-contacts","summary":"Quitar contactos de una lista","description":"Los saca de la lista; el contacto sigue existiendo.","tags":["lists"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"object":"list_membership","list":"5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d","removed":1}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{},"description":"Correos."}},"required":["contacts"]},"example":{"contacts":["ana@correo.co"]}}}}}},"/segments":{"get":{"operationId":"segments-list","summary":"Listar segmentos","description":"Los segmentos del proyecto con cuántos contactos cumplen cada uno.","tags":["segments"],"parameters":[{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Resultados por página, de 1 a 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":null}},"/segments/{id}":{"get":{"operationId":"segments-retrieve","summary":"Consultar un segmento","description":"Sus reglas y su conteo.","tags":["segments"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":null}},"/campaigns":{"get":{"operationId":"campaigns-list","summary":"Listar campañas","description":"Las campañas del proyecto, de la más reciente a la más antigua.","tags":["campaigns"],"parameters":[{"name":"status","in":"query","required":false,"description":"Uno o varios estados separados por coma.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Resultados por página, de 1 a 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":null},"post":{"operationId":"campaigns-create","summary":"Crear una campaña","description":"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.","tags":["campaigns"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Creado","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nombre interno."},"subject":{"type":"string","description":"Asunto (admite variables: `{{ nombre | \"amigo\" }}`)."},"preheader":{"type":"string","description":"Texto de vista previa."},"from":{"type":"object","description":"`{name, email}`: el correo de un dominio verificado."},"reply_to":{"type":"string","description":"Responder a."},"lists":{"type":"array","items":{},"description":"Ids de listas."},"segment":{"type":"string","format":"uuid","description":"Id de un segmento."},"blocks":{"type":"array","items":{},"description":"Bloques del editor."},"html":{"type":"string","description":"HTML propio, en vez de bloques."},"publish_to":{"type":"string","enum":["email","web","both"],"description":"Dónde se publica."}},"required":["name"]},"example":{"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>"}}}}}},"/campaigns/{id}":{"get":{"operationId":"campaigns-retrieve","summary":"Consultar una campaña","description":"La campaña, su estado y el tamaño de su audiencia.","tags":["campaigns"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":null},"patch":{"operationId":"campaigns-update","summary":"Editar una campaña","description":"Solo mientras es borrador.","tags":["campaigns"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","description":"Asunto."},"blocks":{"type":"array","items":{},"description":"Bloques."},"html":{"type":"string","description":"HTML."}}}}}}}},"/campaigns/{id}/review":{"post":{"operationId":"campaigns-review","summary":"Revisar antes de enviar","description":"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.","tags":["campaigns"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended"}},"/campaigns/{id}/schedule":{"post":{"operationId":"campaigns-schedule","summary":"Programar una campaña","description":"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.","tags":["campaigns"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"description":"Aceptado","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"send_at":{"type":"string","format":"date-time","description":"Cuándo (ISO 8601). Sin desfase horario se lee en la zona horaria de tu empresa."},"confirm":{"type":"boolean","description":"`true`: confirmas que revisaste la campaña."}},"required":["send_at","confirm"]},"example":{"send_at":"2026-11-03T09:00:00-05:00","confirm":true}}}}}},"/campaigns/{id}/send":{"post":{"operationId":"campaigns-send","summary":"Enviar una campaña ya","description":"Empieza el envío escalonado (2 %, 5 % y el resto, con pausas para medir rebotes y quejas). Exige `{\"confirm\": true}`.","tags":["campaigns"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"description":"Aceptado","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean","description":"`true`: confirmas que revisaste la campaña."}},"required":["confirm"]},"example":{"confirm":true}}}}}},"/campaigns/{id}/pause":{"post":{"operationId":"campaigns-pause","summary":"Pausar una campaña","description":"Detiene el envío; lo que falta queda pendiente.","tags":["campaigns"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended"}},"/campaigns/{id}/cancel":{"post":{"operationId":"campaigns-cancel","summary":"Cancelar una campaña","description":"No sale nada más. Lo que no se envió no se cobra.","tags":["campaigns"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended"}},"/campaigns/{id}/stats":{"get":{"operationId":"campaigns-stats","summary":"Estadísticas de una campaña","description":"Entregas, rebotes, quejas, aperturas (aproximadas: Apple Mail precarga las imágenes), clics por enlace y por hora, y bajas.","tags":["campaigns"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":null}},"/imports":{"get":{"operationId":"imports-list","summary":"Listar importaciones","description":"Las importaciones del proyecto y su informe.","tags":["imports"],"parameters":[{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Resultados por página, de 1 a 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":null},"post":{"operationId":"imports-create","summary":"Subir una importación","description":"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`.","tags":["imports"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Creado","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"El CSV en base64 (hasta 10 MB)."},"filename":{"type":"string","description":"Nombre del archivo."},"mapping":{"type":"object","description":"Columna del archivo → campo (`email`, `first_name`, `fields.ciudad`…)."},"list":{"type":"string","format":"uuid","description":"Lista a la que entran."},"tags":{"type":"array","items":{},"description":"Etiquetas para todos."},"declaration":{"type":"object","description":"`{source, consent: true}`: de dónde salió la lista y que autorizaron recibir tus correos."}},"required":["file","declaration"]},"example":{"file":"Q29ycmVvLE5vbWJyZQphbmFAY29ycmVvLmNvLEFuYQo=","filename":"clientes.csv","declaration":{"source":"Clientes de la tienda que aceptaron el boletín al comprar","consent":true}}}}}}},"/imports/{id}":{"get":{"operationId":"imports-retrieve","summary":"Consultar una importación","description":"Su estado y su informe.","tags":["imports"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":null}},"/imports/{id}/confirm":{"post":{"operationId":"imports-confirm","summary":"Confirmar una importación","description":"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.","tags":["imports"],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador del recurso.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"marketing","x-idempotency":"recommended"}},"/me":{"get":{"operationId":"me","summary":"Tu API key","description":"Qué key usas, de qué empresa y con qué permisos: para probar la conexión.","tags":["me"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":null,"x-idempotency":null}},"/partner/link-requests":{"post":{"operationId":"partner-link-requests-create","summary":"Pedir un enlace de conexión","description":"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.","tags":["partner"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Creado","content":{"application/json":{"example":{"id":"lr_Q2x7Vb9Kp3Lm8Nn4Rt6Ws1Yz","url":"https://app.mailko.co/vincular/<token>","expires_at":"2026-11-11T11:00:00-05:00"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"partner","x-idempotency":"recommended","security":[{"PartnerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Cómo llama tu app a la cuenta (se muestra al cliente)."},"external_id":{"type":"string","description":"Tu identificador de la cuenta: vuelve en la redirección."},"return_url":{"type":"string","description":"URL https de uno de los orígenes registrados de tu app."},"scopes":{"type":"array","items":{},"description":"Permisos de la key que pides: `send`, `read`."}},"required":["name","external_id","return_url","scopes"]},"example":{"name":"Gimnasio Andes","external_id":"bucli-link:3f0c9a1e","return_url":"https://app.bucli.co/configuracion/mensajes?flujo=mailko","scopes":["send","read"]}}}}}},"/partner/link-requests/exchange":{"post":{"operationId":"partner-link-requests-exchange","summary":"Canjear el código","description":"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`…).","tags":["partner"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"partner","x-idempotency":"recommended","security":[{"PartnerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"El `code` de la redirección."}},"required":["code"]},"example":{"code":"<code>"}}}}}},"/partner/connections/{id}":{"get":{"operationId":"partner-connections-retrieve","summary":"Consultar una conexión","description":"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`).","tags":["partner"],"parameters":[{"name":"id","in":"path","required":true,"description":"Id de la conexión (`con_…`).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"partner","x-idempotency":null,"security":[{"PartnerKey":[]}]}},"/partner/connections/{id}/revoke":{"post":{"operationId":"partner-connections-revoke","summary":"Revocar una conexión","description":"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).","tags":["partner"],"parameters":[{"name":"id","in":"path","required":true,"description":"Id de la conexión (`con_…`).","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"partner","x-idempotency":"recommended","security":[{"PartnerKey":[]}]}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"mk_live_…","description":"API key de Configuración → Desarrolladores. Permisos: send, read, admin, marketing."},"PartnerKey":{"type":"http","scheme":"bearer","bearerFormat":"mkp_live_…","description":"Llave de socio de una app aliada (Conectar Mailko): solo sirve en /partner."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Clave única por operación: un reintento con la misma clave repite la respuesta.","schema":{"type":"string","maxLength":255}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","required":["type","code","message","request_id"],"properties":{"type":{"type":"string","enum":["api_error","authentication_error","billing_error","idempotency_error","invalid_request_error","permission_error","rate_limit_error"]},"code":{"type":"string","enum":["validation_error","invalid_parameter","invalid_page","invalid_page_size","idempotency_key_required","idempotency_key_invalid","authentication_required","api_key_missing","authorization_header_invalid","api_key_invalid","api_key_revoked","api_key_expired","partner_key_missing","partner_key_invalid","partner_key_revoked","subscription_read_only","subscription_limit_exceeded","no_active_subscription","missing_scope","domain_not_verified","workspace_paused","marketing_disabled","workspace_in_review","insufficient_balance","limit_exceeded","too_many_recipients","too_many_emails","message_too_large","invalid_header","template_variables_missing","domain_invalid","free_mail_domain","domain_taken","suppression_not_removable","provider_unavailable","module_not_active","endpoint_out_of_scope","feature_not_available","not_found","route_not_found","method_not_allowed","idempotency_key_in_progress","unsupported_media_type","idempotency_key_reused","rate_limited","monthly_quota_exceeded","audience_empty","campaign_not_editable","campaign_review_failed","campaign_not_sending","campaign_requires_approval","confirmation_required","import_requires_review","list_not_found","return_url_not_allowed","scope_not_allowed","external_id_taken","code_not_found","code_used","code_expired","connection_revoked","internal_error"]},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"request_id":{"type":"string"}}}}},"Correo":{"type":"object","properties":{"id":{"type":"string","description":"Id del correo (`msg_…`)."},"object":{"type":"string","description":"Siempre `email`."},"status":{"type":"string","description":"queued, sent, delivered, delayed, bounced, complained, suppressed, failed o rejected."},"status_reason":{"type":"string","description":"Por qué quedó en ese estado, en palabras simples."},"from":{"type":"string","description":"Remitente."},"to":{"type":"array","items":{},"description":"Destinatarios."},"cc":{"type":"array","items":{},"description":"Copia."},"bcc":{"type":"array","items":{},"description":"Copia oculta."},"reply_to":{"type":"array","items":{},"description":"Responder a."},"suppressed":{"type":"array","items":{},"description":"Destinatarios que no se enviaron por estar suprimidos."},"subject":{"type":"string","description":"Asunto."},"template":{"type":"string","description":"Alias de la plantilla, si se usó."},"template_version":{"type":"integer","description":"Versión de la plantilla con que salió."},"tags":{"type":"object","description":"Etiquetas."},"metadata":{"type":"object","description":"Tus datos."},"stream":{"type":"string","description":"`transactional` o `marketing`."},"test_mode":{"type":"boolean","description":"Enviado con una key de prueba: no se entregó."},"created_at":{"type":"string","format":"date-time","description":"Aceptado."},"sent_at":{"type":"string","format":"date-time","description":"Entregado a Amazon SES."},"delivered_at":{"type":"string","format":"date-time","description":"Recibido por el servidor del destinatario."},"last_event_at":{"type":"string","format":"date-time","description":"Último evento."}}},"Dominio":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","description":"pending, verified, failed, expired o paused."},"status_label":{"type":"string"},"status_reason":{"type":"string"},"region":{"type":"string"},"dkim_status":{"type":"string"},"mail_from_domain":{"type":"string"},"mail_from_status":{"type":"string"},"dmarc_status":{"type":"string"},"dmarc_record":{"type":"string"},"tracking_domain":{"type":"string"},"tracking_status":{"type":"string"},"problems":{"type":"object","description":"Qué está mal en cada registro, en palabras simples."},"records":{"type":"array","items":{},"description":"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":{"type":"string"},"verified_at":{"type":"string"},"expires_at":{"type":"string","description":"Si no verifica antes, el dominio vence."},"created_at":{"type":"string"}}},"Supresión":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"string"},"email":{"type":"string"},"reason":{"type":"string","description":"hard_bounce, complaint, unsubscribe, manual o erasure."},"reason_label":{"type":"string"},"source":{"type":"string"},"source_label":{"type":"string"},"detail":{"type":"string"},"scope":{"type":"string","description":"`workspace` o `global` (de la plataforma)."},"message_id":{"type":"string"},"created_at":{"type":"string"}}},"Plantilla":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"alias":{"type":"string"},"description":{"type":"string"},"current_version":{"type":"integer"},"current":{"type":"object","description":"La versión vigente: asunto, HTML, texto y variables."},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"Uso":{"type":"object","properties":{"object":{"type":"string"},"available":{"type":"boolean","description":"`false` si el saldo no se pudo leer ahora: `used` y `remaining` llegan vacíos."},"limit":{"type":"integer","description":"Correos del plan este mes (-1: sin límite)."},"unlimited":{"type":"boolean"},"used":{"type":"integer"},"remaining":{"type":"integer","description":"Lo que queda del cupo del plan este mes."},"packs_remaining":{"type":"integer","description":"Correos que guardan tus bolsas vigentes."},"test_mode":{"type":"boolean","description":"Sin plan ni bolsa: solo modo de prueba."},"workspace":{"type":"object","description":"Límites de hoy del proyecto (nivel de confianza)."}}},"Contacto":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"country":{"type":"string"},"status":{"type":"string","description":"subscribed, pending, unsubscribed, bounced, complained o suppressed."},"status_label":{"type":"string"},"status_changed_at":{"type":"string"},"fields":{"type":"object","description":"Tus campos propios (Contactos → Campos)."},"tags":{"type":"array","items":{}},"source":{"type":"string"},"lists":{"type":"array","items":{}},"last_sent_at":{"type":"string"},"last_opened_at":{"type":"string"},"last_clicked_at":{"type":"string"},"campaigns_received":{"type":"integer"},"cleaned_at":{"type":"string","description":"La limpieza automática dejó de enviarle por inactividad."},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"Lista":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"double_opt_in":{"type":"boolean","description":"Los formularios de esta lista piden confirmar el correo."},"contacts_count":{"type":"integer"},"created_at":{"type":"string"}}},"Segmento":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"definition":{"type":"object","description":"Reglas `{match, rules: [{field, op, value}]}`."},"contacts_count":{"type":"integer"},"subscribed_count":{"type":"integer"},"created_at":{"type":"string"}}},"Campaña":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"subject":{"type":"string"},"preheader":{"type":"string"},"from":{"type":"object"},"from_name":{"type":"string"},"from_email":{"type":"string"},"reply_to":{"type":"string"},"lists":{"type":"array","items":{}},"segment":{"type":"string"},"blocks":{"type":"array","items":{},"description":"El contenido del editor (heading, text, button, image, divider, spacer, html, columns)."},"theme":{"type":"object"},"publish_to":{"type":"string","description":"`email`, `web` (solo en el sitio del newsletter) o `both`."},"status":{"type":"string","description":"draft, review, scheduled, sending, paused, sent o canceled."},"status_label":{"type":"string"},"status_reason":{"type":"string"},"send_at":{"type":"string"},"started_at":{"type":"string"},"finished_at":{"type":"string"},"current_batch":{"type":"integer"},"next_batch_at":{"type":"string"},"review":{"type":"object"},"stats":{"type":"object"},"approved_at":{"type":"string"},"issue_url":{"type":"string"},"audience_count":{"type":"integer"},"requires_approval":{"type":"boolean","description":"Las primeras campañas del proyecto las revisa el equipo de Mailko."},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"Importación":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"string"},"file_name":{"type":"string"},"status":{"type":"string","description":"previewed, review, running, done, failed o rejected."},"requires_review":{"type":"boolean","description":"Lista grande o con muchas direcciones descartadas: la revisa Mailko antes de importarla."},"mapping":{"type":"object"},"list":{"type":"string"},"counts":{"type":"object"},"report":{"type":"object"},"created_at":{"type":"string"}}},"APIkey":{"type":"object","properties":{"object":{"type":"string","description":"Siempre `api_key`."},"id":{"type":"string","format":"uuid","description":"Identificador de la key."},"name":{"type":"string","description":"Nombre que le diste."},"prefix":{"type":"string","description":"Prefijo público de la key, para reconocerla en listas y registros."},"mode":{"type":"string","description":"`live` (entrega) o `test` (valida y no entrega)."},"scopes":{"type":"array","items":{},"description":"Permisos de la key."},"expires_at":{"type":"string","format":"date-time","description":"Vencimiento, o `null` si no vence."},"organization":{"type":"object","description":"La empresa dueña de la key: `id` y `name`."},"workspace":{"type":"object","description":"El proyecto de la key: `id`, `name` y `status`."},"api_version":{"type":"string","description":"Versión de la API."}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador del webhook."},"url":{"type":"string","description":"Dirección HTTPS que recibe los eventos."},"description":{"type":"string","description":"Para qué es."},"topics":{"type":"array","items":{},"description":"Eventos suscritos. Vacío = todos."},"secret_hint":{"type":"string","description":"Los últimos caracteres del secreto de firma. El secreto completo solo se entrega al crear o al rotar."},"is_active":{"type":"boolean","description":"Encendido."},"consecutive_failures":{"type":"integer","description":"Entregas fallidas seguidas."},"disabled_reason":{"type":"string","description":"Por qué se apagó solo, si fue así."},"last_delivery_at":{"type":"string","format":"date-time","description":"Última entrega exitosa."},"created_at":{"type":"string","format":"date-time","description":"Creación."},"updated_at":{"type":"string","format":"date-time","description":"Última modificación."}}}}}}