Referencia de la API · v1
Correos, dominios, plantillas, supresiones, webhooks y uso de tu cuenta, por REST y JSON.
https://api.mailko.co/v1La 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.
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."394800.00") para no perder centavos.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.
401 con el código api_key_revoked o api_key_expired.403 missing_scope y dice cuál le falta en required_scope.403 module_not_active. Sin suscripción, 402 no_active_subscription.402 subscription_read_only.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.
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:
{
"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.Los listados se piden por páginas con page (desde 1) y page_size (de 1 a 100, por defecto 20) y responden:
{
"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.
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.
Idempotent-Replayed: true.409 idempotency_key_in_progress. Espera y reintenta.422 idempotency_key_reused. Genera una key nueva por operación.5xx no se guarda: el reintento se ejecuta de verdad.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.
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.
Cada API key lleva solo los permisos que le diste. Una ruta sin el suyo responde 403 missing_scope.
Enviar
Enviar correos (POST /v1/emails y /v1/emails/batch). Nada más.
Consultar
Ver correos y sus eventos, dominios, supresiones, plantillas, webhooks y el uso del mes.
Administrar
Agregar, verificar y eliminar dominios; manejar supresiones y webhooks.
Marketing
Contactos, listas, segmentos e importaciones; crear campañas y, con confirmación, enviarlas.
Enviar correos y ver qué pasó con ellos.
/emailsValida, 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.
fromstringobligatorioRemitente: correo o Nombre <correo> de un dominio verificado.
toarrayobligatorioDestinatarios (o un solo correo como texto).
ccarrayopcionalCopia.
bccarrayopcionalCopia oculta.
reply_toarrayopcionalResponder a.
subjectstringopcionalAsunto. Obligatorio sin plantilla.
htmlstringopcionalCuerpo HTML.
textstringopcionalCuerpo en texto plano.
templateobjectopcional{id, version?, variables?}: alias o id de una plantilla y sus variables.
headersobjectopcionalCabeceras permitidas (List-Unsubscribe, In-Reply-To, References…).
attachmentsarrayopcionalHasta 20 adjuntos {filename, content (base64), content_type}.
tagsobjectopcionalHasta 10 etiquetas nombre: valor para filtrar después.
metadataobjectopcionalDatos tuyos que vuelven en los webhooks.
streamenumopcionaltransactional o marketing. Mientras Mailko envíe solo correo transaccional, marketing responde marketing_disabled.
transactionalmarketingcurl -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 <[email protected]>", "to": ["[email protected]"], "subject": "Tu pedido #1234", "html": "<p>Gracias por tu compra</p>", "text": "Gracias por tu compra", "reply_to": "[email protected]", "tags": {"tipo": "pedido"}, "metadata": {"order_id": "1234"}}'{
"id": "msg_8f2k3j4h5g6f7d8s9a0q1w2e3r",
"object": "email",
"status": "queued",
"test_mode": false
}https://api.mailko.co/v1/emails
/emails/batchHasta 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.
emailsarrayobligatorioLos correos, cada uno como en POST /emails.
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 <[email protected]>", "to": ["[email protected]"], "subject": "Tu pedido #1234", "html": "<p>Gracias por tu compra</p>", "text": "Gracias por tu compra", "reply_to": "[email protected]", "tags": {"tipo": "pedido"}, "metadata": {"order_id": "1234"}}]}'{
"data": [
{
"id": "msg_8f2k3j4h5g6f7d8s9a0q1w2e3r",
"object": "email",
"status": "queued",
"test_mode": false
}
]
}https://api.mailko.co/v1/emails/batch
/emailsLos correos del proyecto, del más reciente al más antiguo.
statusstringopcionalUno o varios estados separados por coma.
recipientstringopcionalCorreos a esta dirección.
tagstringopcionalnombre:valor de una etiqueta.
created_afterdateopcionalDesde (AAAA-MM-DD, día en hora de Bogotá, UTC−5).
created_beforedateopcionalHasta, incluido.
pageintegeropcionalPágina, desde 1.
Por defecto 1
page_sizeintegeropcionalResultados por página, de 1 a 100.
Por defecto 20
curl -X GET 'https://api.mailko.co/v1/emails' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"data": [
{
"id": "msg_8f2k3j4h5g6f7d8s9a0q1w2e3r",
"object": "email",
"status": "delivered",
"status_reason": "",
"from": "Tienda Ejemplo <[email protected]>",
"to": [
"[email protected]"
],
"cc": [],
"bcc": [],
"reply_to": [
"[email protected]"
],
"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
}
}https://api.mailko.co/v1/emails
/emails/{id}Estado de un correo y su línea de tiempo de eventos (events), con el motivo de cada rebote en palabras simples.
idstringobligatorioId del correo (msg_…).
curl -X GET 'https://api.mailko.co/v1/emails/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"id": "msg_8f2k3j4h5g6f7d8s9a0q1w2e3r",
"object": "email",
"status": "delivered",
"status_reason": "",
"from": "Tienda Ejemplo <[email protected]>",
"to": [
"[email protected]"
],
"cc": [],
"bcc": [],
"reply_to": [
"[email protected]"
],
"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": "[email protected]",
"occurred_at": "2026-10-28T10:02:22-05:00",
"bounce_type": "",
"bounce_subtype": "",
"explanation": "",
"diagnostic": ""
}
]
}https://api.mailko.co/v1/emails/{id}
Tus dominios de envío y sus registros DNS.
/domainsLos dominios del proyecto con el estado de cada registro DNS.
pageintegeropcionalPágina, desde 1.
Por defecto 1
page_sizeintegeropcionalResultados por página, de 1 a 100.
Por defecto 20
curl -X GET 'https://api.mailko.co/v1/domains' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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
}
}https://api.mailko.co/v1/domains
/domainsCrea 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.
namestringobligatorioTu dominio, sin http ni www (tienda.co).
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"}'{
"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"
}https://api.mailko.co/v1/domains
/domains/{id}Un dominio y sus registros DNS.
iduuidobligatorioIdentificador del recurso.
curl -X GET 'https://api.mailko.co/v1/domains/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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"
}https://api.mailko.co/v1/domains/{id}
/domains/{id}/verifyRevisa ya los registros (Mailko también lo hace solo) y responde el dominio con lo que encontró.
iduuidobligatorioIdentificador del recurso.
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)"{
"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"
}https://api.mailko.co/v1/domains/{id}/verify
/domains/{id}Quita la identidad de Amazon SES. Ningún correo vuelve a salir con ese dominio.
iduuidobligatorioIdentificador del recurso.
curl -X DELETE 'https://api.mailko.co/v1/domains/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Sin cuerpo.
https://api.mailko.co/v1/domains/{id}
Direcciones a las que no se envía.
/suppressionsDirecciones a las que el proyecto no envía: rebotes duros, quejas, bajas y las que agregaste.
reasonstringopcionalMotivos separados por coma.
emailstringopcionalBuscar una dirección.
pageintegeropcionalPágina, desde 1.
Por defecto 1
page_sizeintegeropcionalResultados por página, de 1 a 100.
Por defecto 20
curl -X GET 'https://api.mailko.co/v1/suppressions' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"data": [
{
"object": "suppression",
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"email": "[email protected]",
"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
}
}https://api.mailko.co/v1/suppressions
/suppressionsBloquea una dirección en este proyecto.
emailstringobligatorioLa dirección.
detailstringopcionalPor qué.
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": "[email protected]", "detail": "Pidió no recibir más correos"}'{
"object": "suppression",
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"email": "[email protected]",
"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"
}https://api.mailko.co/v1/suppressions
/suppressions/{id}Una supresión por su id.
iduuidobligatorioIdentificador del recurso.
curl -X GET 'https://api.mailko.co/v1/suppressions/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"object": "suppression",
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"email": "[email protected]",
"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"
}https://api.mailko.co/v1/suppressions/{id}
/suppressions/{id}Vuelve a permitir la dirección. Una queja o una solicitud de supresión de datos no se puede quitar.
iduuidobligatorioIdentificador del recurso.
curl -X DELETE 'https://api.mailko.co/v1/suppressions/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Sin cuerpo.
https://api.mailko.co/v1/suppressions/{id}
Plantillas versionadas con variables.
/templatesLas plantillas del proyecto con su versión vigente.
pageintegeropcionalPágina, desde 1.
Por defecto 1
page_sizeintegeropcionalResultados por página, de 1 a 100.
Por defecto 20
curl -X GET 'https://api.mailko.co/v1/templates' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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
}
}https://api.mailko.co/v1/templates
/templates/{id}Una plantilla y su versión vigente con sus variables.
iduuidobligatorioIdentificador del recurso.
curl -X GET 'https://api.mailko.co/v1/templates/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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"
}https://api.mailko.co/v1/templates/{id}
Consumo del mes, saldo y límites.
/usageLo que llevas del mes, lo que te queda del plan y de las bolsas, el excedente y los límites del proyecto hoy.
curl -X GET 'https://api.mailko.co/v1/usage' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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
}
}https://api.mailko.co/v1/usage
Administra por código los mismos webhooks de la pantalla Desarrolladores.
/webhook-endpointsLos webhooks de tu empresa.
pageintegeropcionalPágina, desde 1.
Por defecto 1
page_sizeintegeropcionalResultados por página, de 1 a 100.
Por defecto 20
curl -X GET 'https://api.mailko.co/v1/webhook-endpoints' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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
}
}https://api.mailko.co/v1/webhook-endpoints
/webhook-endpointsRegistra 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.
urlstringobligatorioDirección HTTPS pública (sin redirecciones).
descriptionstringopcionalPara qué es.
topicsarrayobligatorioEventos (ver /webhook-events). Obligatorio: cada evento exige el permiso de lectura de su objeto.
is_activebooleanopcionalEncendido.
Por defecto true
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"]}'{
"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"
}https://api.mailko.co/v1/webhook-endpoints
/webhook-endpoints/{id}Un webhook por su id.
iduuidobligatorioIdentificador del recurso.
curl -X GET 'https://api.mailko.co/v1/webhook-endpoints/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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"
}https://api.mailko.co/v1/webhook-endpoints/{id}
/webhook-endpoints/{id}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.
iduuidobligatorioIdentificador del recurso.
urlstringopcionalDirección.
descriptionstringopcionalPara qué es.
topicsarrayopcionalEventos (cada uno con el permiso de lectura de su objeto).
is_activebooleanopcionalEncendido.
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}'{
"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"
}https://api.mailko.co/v1/webhook-endpoints/{id}
/webhook-endpoints/{id}Deja de enviarle eventos y borra su historial de entregas.
iduuidobligatorioIdentificador del recurso.
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)"Sin cuerpo.
https://api.mailko.co/v1/webhook-endpoints/{id}
/webhook-endpoints/{id}/rotate-secretGenera un secreto nuevo y lo responde por única vez. El anterior deja de firmar de inmediato.
iduuidobligatorioIdentificador del recurso.
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)"{
"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"
}https://api.mailko.co/v1/webhook-endpoints/{id}/rotate-secret
/webhook-endpoints/{id}/testEnvía ya un evento ping firmado (aunque el webhook esté apagado) y responde la entrega con lo que contestó tu servidor.
iduuidobligatorioIdentificador del recurso.
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)"{
"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"
}https://api.mailko.co/v1/webhook-endpoints/{id}/test
/webhook-endpoints/{id}/deliveriesLas 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.
iduuidobligatorioIdentificador del recurso.
statusenumopcionalEstado.
pendingdeliveredfailedskippedtypestringopcionalTipo de evento.
pageintegeropcionalPágina, desde 1.
Por defecto 1
page_sizeintegeropcionalResultados por página, de 1 a 100.
Por defecto 20
curl -X GET 'https://api.mailko.co/v1/webhook-endpoints/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/deliveries' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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
}
}https://api.mailko.co/v1/webhook-endpoints/{id}/deliveries
/webhook-endpoints/{id}/deliveries/{delivery_id}/redeliverEnvía otra vez el mismo evento (mismo id, para que tu servidor lo deduplique).
iduuidobligatorioIdentificador del recurso.
delivery_iduuidobligatorioLa entrega.
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)"{
"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"
}https://api.mailko.co/v1/webhook-endpoints/{id}/deliveries/{delivery_id}/redeliver
/webhook-eventsLos eventos a los que se puede suscribir un webhook.
curl -X GET 'https://api.mailko.co/v1/webhook-events' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"data": [
{
"type": "email.delivered",
"group": "emails",
"group_label": "Correos",
"label": "Correo entregado",
"description": "SES confirmó la entrega al servidor del destinatario.",
"object": "email"
}
]
}https://api.mailko.co/v1/webhook-events
Tus contactos, sin perder bajas ni consentimientos.
/contactsLos contactos del proyecto, del más reciente al más antiguo.
statusstringopcionalUno o varios estados separados por coma.
tagstringopcionalContactos con esta etiqueta.
listuuidopcionalContactos de esta lista.
segmentuuidopcionalContactos que cumplen este segmento.
searchstringopcionalBusca en correo, nombre y apellido.
pageintegeropcionalPágina, desde 1.
Por defecto 1
page_sizeintegeropcionalResultados por página, de 1 a 100.
Por defecto 20
curl -X GET 'https://api.mailko.co/v1/contacts' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"data": [
{
"object": "contact",
"id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
"email": "[email protected]",
"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
}
}https://api.mailko.co/v1/contacts
/contactsPor 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.
emailstringobligatorioCorreo.
first_namestringopcionalNombre.
last_namestringopcionalApellido.
countrystringopcionalPaís (ISO de dos letras).
fieldsobjectopcionalCampos propios del proyecto.
tagsarrayopcionalEtiquetas.
listsarrayopcionalIds de listas a las que se suma.
statusenumopcionalEstado inicial.
subscribedpendingunsubscribedcurl -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": "[email protected]", "first_name": "Ana", "tags": ["cliente"]}'{
"object": "contact",
"id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
"email": "[email protected]",
"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"
}https://api.mailko.co/v1/contacts
/contacts/{id}Datos, estado, listas y actividad.
iduuidobligatorioIdentificador del recurso.
curl -X GET 'https://api.mailko.co/v1/contacts/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"object": "contact",
"id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
"email": "[email protected]",
"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"
}https://api.mailko.co/v1/contacts/{id}
/contacts/{id}Cambia sus datos. El correo no cambia. Reactivar a quien se dio de baja solo se hace en el panel, confirmando el consentimiento.
iduuidobligatorioIdentificador del recurso.
first_namestringopcionalNombre.
last_namestringopcionalApellido.
countrystringopcionalPaís.
fieldsobjectopcionalCampos propios.
tagsarrayopcionalEtiquetas que se suman.
listsarrayopcionalListas a las que se suma.
statusenumopcionalNuevo estado.
subscribedpendingunsubscribedcurl -X PATCH 'https://api.mailko.co/v1/contacts/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"{
"object": "contact",
"id": "3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
"email": "[email protected]",
"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"
}https://api.mailko.co/v1/contacts/{id}
/contacts/{id}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.
iduuidobligatorioIdentificador del recurso.
curl -X DELETE 'https://api.mailko.co/v1/contacts/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Sin cuerpo.
https://api.mailko.co/v1/contacts/{id}
Listas de contactos y sus miembros.
/listsLas listas del proyecto con su número de contactos.
pageintegeropcionalPágina, desde 1.
Por defecto 1
page_sizeintegeropcionalResultados por página, de 1 a 100.
Por defecto 20
curl -X GET 'https://api.mailko.co/v1/lists' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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
}
}https://api.mailko.co/v1/lists
/listsUna lista nueva, vacía.
namestringobligatorioNombre.
descriptionstringopcionalDescripción.
double_opt_inbooleanopcionalPedir confirmación en sus formularios.
Por defecto true
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"}'{
"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"
}https://api.mailko.co/v1/lists
/lists/{id}Una lista y su número de contactos.
iduuidobligatorioIdentificador del recurso.
curl -X GET 'https://api.mailko.co/v1/lists/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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"
}https://api.mailko.co/v1/lists/{id}
/lists/{id}/contactsHasta 1.000 correos ({"contacts": [...]}). Los que no existen se crean.
iduuidobligatorioIdentificador del recurso.
contactsarrayobligatorioCorreos.
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": ["[email protected]", "[email protected]"]}'{
"object": "list_membership",
"list": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
"added": 2
}https://api.mailko.co/v1/lists/{id}/contacts
/lists/{id}/contactsLos saca de la lista; el contacto sigue existiendo.
iduuidobligatorioIdentificador del recurso.
contactsarrayobligatorioCorreos.
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": ["[email protected]"]}'{
"object": "list_membership",
"list": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
"removed": 1
}https://api.mailko.co/v1/lists/{id}/contacts
Contactos que cumplen unas reglas.
/segmentsLos segmentos del proyecto con cuántos contactos cumplen cada uno.
pageintegeropcionalPágina, desde 1.
Por defecto 1
page_sizeintegeropcionalResultados por página, de 1 a 100.
Por defecto 20
curl -X GET 'https://api.mailko.co/v1/segments' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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
}
}https://api.mailko.co/v1/segments
/segments/{id}Sus reglas y su conteo.
iduuidobligatorioIdentificador del recurso.
curl -X GET 'https://api.mailko.co/v1/segments/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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"
}https://api.mailko.co/v1/segments/{id}
Campañas de marketing con envío escalonado.
/campaignsLas campañas del proyecto, de la más reciente a la más antigua.
statusstringopcionalUno o varios estados separados por coma.
pageintegeropcionalPágina, desde 1.
Por defecto 1
page_sizeintegeropcionalResultados por página, de 1 a 100.
Por defecto 20
curl -X GET 'https://api.mailko.co/v1/campaigns' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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": "[email protected]"
},
"from_name": "Café La Montaña",
"from_email": "[email protected]",
"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
}
}https://api.mailko.co/v1/campaigns
/campaignsUn 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.
namestringobligatorioNombre interno.
subjectstringopcionalAsunto (admite variables: {{ nombre | "amigo" }}).
preheaderstringopcionalTexto de vista previa.
fromobjectopcional{name, email}: el correo de un dominio verificado.
reply_tostringopcionalResponder a.
listsarrayopcionalIds de listas.
segmentuuidopcionalId de un segmento.
blocksarrayopcionalBloques del editor.
htmlstringopcionalHTML propio, en vez de bloques.
publish_toenumopcionalDónde se publica.
emailwebbothcurl -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": "[email protected]"}, "lists": ["5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d"], "html": "<h1>Cosecha de noviembre</h1><p>Hola…</p>"}'{
"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": "[email protected]"
},
"from_name": "Café La Montaña",
"from_email": "[email protected]",
"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"
}https://api.mailko.co/v1/campaigns
/campaigns/{id}La campaña, su estado y el tamaño de su audiencia.
iduuidobligatorioIdentificador del recurso.
curl -X GET 'https://api.mailko.co/v1/campaigns/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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": "[email protected]"
},
"from_name": "Café La Montaña",
"from_email": "[email protected]",
"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"
}https://api.mailko.co/v1/campaigns/{id}
/campaigns/{id}Solo mientras es borrador.
iduuidobligatorioIdentificador del recurso.
subjectstringopcionalAsunto.
blocksarrayopcionalBloques.
htmlstringopcionalHTML.
curl -X PATCH 'https://api.mailko.co/v1/campaigns/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"{
"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": "[email protected]"
},
"from_name": "Café La Montaña",
"from_email": "[email protected]",
"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"
}https://api.mailko.co/v1/campaigns/{id}
/campaigns/{id}/reviewLa 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.
iduuidobligatorioIdentificador del recurso.
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)"{
"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"
}https://api.mailko.co/v1/campaigns/{id}/review
/campaigns/{id}/scheduleSale 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.
iduuidobligatorioIdentificador del recurso.
send_atdatetimeobligatorioCuándo (ISO 8601). Sin desfase horario se lee en la zona horaria de tu empresa.
confirmbooleanobligatoriotrue: confirmas que revisaste la campaña.
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}'{
"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": "[email protected]"
},
"from_name": "Café La Montaña",
"from_email": "[email protected]",
"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"
}https://api.mailko.co/v1/campaigns/{id}/schedule
/campaigns/{id}/sendEmpieza el envío escalonado (2 %, 5 % y el resto, con pausas para medir rebotes y quejas). Exige {"confirm": true}.
iduuidobligatorioIdentificador del recurso.
confirmbooleanobligatoriotrue: confirmas que revisaste la campaña.
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}'{
"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": "[email protected]"
},
"from_name": "Café La Montaña",
"from_email": "[email protected]",
"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"
}https://api.mailko.co/v1/campaigns/{id}/send
/campaigns/{id}/pauseDetiene el envío; lo que falta queda pendiente.
iduuidobligatorioIdentificador del recurso.
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)"{
"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": "[email protected]"
},
"from_name": "Café La Montaña",
"from_email": "[email protected]",
"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"
}https://api.mailko.co/v1/campaigns/{id}/pause
/campaigns/{id}/cancelNo sale nada más. Lo que no se envió no se cobra.
iduuidobligatorioIdentificador del recurso.
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)"{
"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": "[email protected]"
},
"from_name": "Café La Montaña",
"from_email": "[email protected]",
"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"
}https://api.mailko.co/v1/campaigns/{id}/cancel
/campaigns/{id}/statsEntregas, rebotes, quejas, aperturas (aproximadas: Apple Mail precarga las imágenes), clics por enlace y por hora, y bajas.
iduuidobligatorioIdentificador del recurso.
curl -X GET 'https://api.mailko.co/v1/campaigns/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d/stats' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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
}
]
}https://api.mailko.co/v1/campaigns/{id}/stats
Subir contactos desde un CSV, con informe.
/importsLas importaciones del proyecto y su informe.
pageintegeropcionalPágina, desde 1.
Por defecto 1
page_sizeintegeropcionalResultados por página, de 1 a 100.
Por defecto 20
curl -X GET 'https://api.mailko.co/v1/imports' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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
}
}https://api.mailko.co/v1/imports
/importsPaso 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.
filestringobligatorioEl CSV en base64 (hasta 10 MB).
filenamestringopcionalNombre del archivo.
mappingobjectopcionalColumna del archivo → campo (email, first_name, fields.ciudad…).
listuuidopcionalLista a la que entran.
tagsarrayopcionalEtiquetas para todos.
declarationobjectobligatorio{source, consent: true}: de dónde salió la lista y que autorizaron recibir tus correos.
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}}'{
"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"
}https://api.mailko.co/v1/imports
/imports/{id}Su estado y su informe.
iduuidobligatorioIdentificador del recurso.
curl -X GET 'https://api.mailko.co/v1/imports/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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"
}https://api.mailko.co/v1/imports/{id}
/imports/{id}/confirmPaso 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.
iduuidobligatorioIdentificador del recurso.
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)"{
"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"
}https://api.mailko.co/v1/imports/{id}/confirm
Para comprobar que la key funciona.
/meQué key usas, de qué empresa y con qué permisos: para probar la conexión.
curl -X GET 'https://api.mailko.co/v1/me' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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"
}https://api.mailko.co/v1/me
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.
/partner/link-requestsSolo 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.
namestringobligatorioCómo llama tu app a la cuenta (se muestra al cliente).
external_idstringobligatorioTu identificador de la cuenta: vuelve en la redirección.
return_urlstringobligatorioURL https de uno de los orígenes registrados de tu app.
scopesarrayobligatorioPermisos de la key que pides: send, read.
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"]}'{
"id": "lr_Q2x7Vb9Kp3Lm8Nn4Rt6Ws1Yz",
"url": "https://app.mailko.co/vincular/<token>",
"expires_at": "2026-11-11T11:00:00-05:00"
}https://api.mailko.co/v1/partner/link-requests
/partner/link-requests/exchangeCambia 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…).
codestringobligatorioEl code de la redirección.
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>"}'{
"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"
}https://api.mailko.co/v1/partner/link-requests/exchange
/partner/connections/{id}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).
idstringobligatorioId de la conexión (con_…).
curl -X GET 'https://api.mailko.co/v1/partner/connections/7d4c2b1a-9e8f-4a6b-8c5d-1e2f3a4b5c6d' \
-H "Authorization: Bearer $MAILKO_API_KEY"{
"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
}https://api.mailko.co/v1/partner/connections/{id}
/partner/connections/{id}/revokeTermina 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).
idstringobligatorioId de la conexión (con_…).
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)"{
"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"
}https://api.mailko.co/v1/partner/connections/{id}/revoke
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:
{
"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.
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=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdt es el momento del envío (tiempo Unix, segundos) y v1 la firma. Verifícala antes de confiar en el contenido:
t y v1 de la cabecera Mailko-Signature.HMAC-SHA256(secreto, "<t>.<cuerpo>") en hexadecimal.v1 con una comparación de tiempo constante.t tiene más de 5 minutos (evita que alguien repita un aviso capturado).2xx rápido y procesa después; deduplica por Mailko-Event-Id.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", ""))
Abre un evento para ver un ejemplo completo de lo que recibe tu servidor.
| Código | HTTP | Tipo | Qué significa |
|---|---|---|---|
| validation_error | 400 | invalid_request_error | Un campo no es válido; el detalle está en |
| invalid_parameter | 400 | invalid_request_error | Un parámetro de la URL no es válido. |
| invalid_page | 400 | invalid_request_error |
|
| invalid_page_size | 400 | invalid_request_error |
|
| idempotency_key_required | 400 | invalid_request_error | Esta operación exige |
| 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_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 ( |
| 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: |
| 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 ( |
| 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 |
| 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 |
|
| 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 |
| 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. |
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