API

Una API REST sobre HTTPS. Todo es JSON, cada campo va en snake_case y la base es https://listcheckup.com. No hay ningún SDK que instalar ni nada que esperar — crea una clave y los dos comandos de abajo funcionan.

Autenticación

Cada petición lleva una clave API, creada en tu panel. Las claves empiezan por lck_live_, pueden tener fecha de caducidad y pueden revocarse en cualquier momento.

curl "https://listcheckup.com/v1/me" \
  -H "Authorization: Bearer lck_live_..."

GET /v1/me responde con la cuenta a la que pertenece la clave y su saldo, lo que la convierte en la forma más rápida de confirmar que una clave funciona:

{ "email": "[email protected]", "credits": 24600 }

Sin clave, o con una revocada o caducada, cada endpoint responde 401 y dice cuál de esas cosas ocurrió — una clave revocada y una errata piden arreglos distintos.

Límite de peticiones

120 peticiones para empezar, que se recargan a razón de 60 por minuto, por clave. Es un techo sobre el volumen de peticiones, no sobre las direcciones: una lista de medio millón de direcciones es una sola petición. Superarlo responde 429, y la solución es esperar.

Verificar una dirección

La respuesta llega en la propia petición. Úsalo cuando alguien está esperando — un formulario de alta, un checkout — más que para una lista que ya tienes.

curl "https://listcheckup.com/v1/[email protected]" \
  -H "Authorization: Bearer lck_live_..."

Existe un POST /v1/verify con { "email": "..." } en el cuerpo si una query string resulta incómoda. Ambos devuelven lo mismo:

{
  "email": "[email protected]",
  "normalized_email": "[email protected]",
  "local_part": "someone",
  "domain": "example.com",
  "status": "valid",
  "reason": "mailbox_accepted",
  "confidence": 95,
  "duration_ms": 412
}

status es uno de cinco valores, y confidence indica de 0 a 100 cuánto se puede confiar en ese estado. Un catch-all puntúa bajo aunque el servidor aceptara la dirección, porque allí la aceptación no demuestra nada.

status	Qué significa
valid	El buzón existe y puede recibir correo.
invalid	No puede recibir correo. Elimínala.
risky	Funciona, pero es una dirección desechable o un buzón compartido, no una persona.
catch_all	El dominio acepta cualquier dirección, así que nadie puede saber si esta existe.
unknown	El servidor de correo no quiso responder. Un dato sobre su política, no sobre la dirección.

Solo se te cobra por una respuesta. catch_all y unknown no cuestan nada, porque el trabajo se hizo y el servidor de correo se negó a contestar — cobrar por esos sería cobrarte por nuestra incapacidad de averiguarlo.

Verificar una lista

Cuatro llamadas: crear, iniciar, consultar, recoger.

1. Crear

Las direcciones van como JSON, no como archivo — ya las tienes como cadenas, y construir un cuerpo multipart para enviar cadenas es trabajo para nada.

curl -X POST "https://listcheckup.com/v1/lists" \
  -H "Authorization: Bearer lck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "march-subscribers", "emails": ["[email protected]", "[email protected]"]}'

Todavía no se cobra nada. La respuesta es un resumen de la lista con el precio, para que puedas decidir antes de gastar nada:

{
  "id": "7f3c1d20-9a4b-4c8e-8f21-5b6d7e8a9c04",
  "name": "march-subscribers",
  "status": "awaiting_confirmation",
  "addresses": 24600,
  "duplicates": 1020,
  "not_addresses": 180,
  "unique": 23580,
  "excluded": 0,
  "price": 23400,
  "checked": 0,
  "credits_charged": 0,
  "failure_reason": null,
  "created_at": "2026-03-18T09:12:00+00:00",
  "completed_at": null
}

price está en créditos y es lo que costará iniciarla. Las repeticiones se cuentan una sola vez y las líneas que no son direcciones nunca se cobran, y por eso es más bajo que addresses.

2. Iniciar

curl -X POST "https://listcheckup.com/v1/lists/<id>/start" \
  -H "Authorization: Bearer lck_live_..."

Esta es la llamada que gasta créditos. 402 significa que el saldo no alcanza, y no se cobró ni se inició nada.

3. Saber cuándo ha terminado

Registra un webhook y hacemos un POST a tu servidor en cuanto una lista termina — firmado, con reintentos si tu extremo está caído. Esa es la manera de hacerlo.

Si prefieres preguntar, GET /v1/lists/<id> devuelve el mismo resumen de arriba con status y checked en movimiento. Consúltalo con moderación; un webhook no te cuesta ninguna petición.

status	Significado
uploaded	Aceptada, todavía sin leer.
reading	Se está contando. price es null hasta que esto termina.
awaiting_confirmation	Contada y con precio. No se cobra nada hasta que la inicias.
queued	Iniciada y a la espera de un worker.
running	En curso. checked va subiendo.
completed	Terminada. Los resultados están listos.
failed	Detenida. Consulta failure_reason.
cancelled	Detenida por ti. Los créditos no usados se devuelven.

4. Recoger los resultados

curl "https://listcheckup.com/v1/lists/<id>/results?limit=500&skip=0" \
  -H "Authorization: Bearer lck_live_..."

limit es 500 por defecto y tiene un tope de 2.000; pagina con skip. Añade include=valid,risky para quedarte solo con las categorías que te interesan.

{
  "id": "7f3c1d20-...",
  "status": "completed",
  "total": 24600,
  "offset": 0,
  "returned": 500,
  "results": [
    {
      "row": 1,
      "email": "[email protected]",
      "status": "valid",
      "confidence": 95,
      "reason": "mailbox_accepted",
      "billable": true,
      "duplicate_of_row": null
    }
  ]
}

row es la posición en la lista que enviaste, así que los resultados cuadran con tus propios registros sin tener que casar por la dirección.

Eliminar

DELETE /v1/lists/<id> elimina una lista y sus resultados. Lo que quedó sin gastar en una lista que nunca se ejecutó se devuelve.

Webhooks

Añade un endpoint en el panel y enviamos un POST firmado cuando una lista termina:

{
  "event": "list.finished",
  "occurred_at": "2026-03-18T09:41:00+00:00",
  "list": {
    "id": "7f3c1d20-...",
    "name": "march-subscribers",
    "checked": 24600,
    "safe_to_send": 12000,
    "to_remove": 7400,
    "uncertain": 3100
  }
}

Responde con cualquier 2xx. Con cualquier otra cosa lo reintentamos, seis veces a lo largo de un día aproximadamente. Cada petición lleva una firma HMAC-SHA256 que compruebas con tu secreto de firma; el esquema exacto, con un ejemplo resuelto, se muestra junto al secreto cuando creas el endpoint.

Slack funciona sin nada de eso. Pega una URL de webhook entrante de Slack en lugar de la tuya, y enviamos un mensaje que Slack puede mostrar en vez del JSON de arriba — nada que escribir, nada que alojar. Los reintentos y el registro de entregas funcionan igual.

Úsala desde un asistente de IA

Hay un servidor MCP en https://listcheckup.com/mcp. Apunta a esa URL un asistente compatible con MCP — Claude, o un editor como Cursor — con la misma clave API, y podrá comprobar direcciones por ti sin que nadie escriba código.

Conectarlo

Te conectes como te conectes, la clave viaja de la misma forma: una cabecera Authorization: Bearer <key>. Solo cambia dónde la escribes.

Claude Code — un comando:

claude mcp add --transport http listcheckup https://listcheckup.com/mcp \
  --header "Authorization: Bearer lck_live_..."

Claude Desktop, Cursor y la mayoría de los demás clientes — en el archivo de configuración:

{
  "mcpServers": {
    "listcheckup": {
      "url": "https://listcheckup.com/mcp",
      "headers": { "Authorization": "Bearer lck_live_..." }
    }
  }
}

Comprobar que funciona

Antes de conectarlo a nada, pregúntale al servidor qué sabe hacer:

curl -X POST "https://listcheckup.com/mcp"   -H "Authorization: Bearer lck_live_..."   -H "Content-Type: application/json"   -H "Accept: application/json, text/event-stream"   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Si lista seis herramientas, estás conectado. "error": "unauthorized" significa que la clave no llegó — casi siempre falta la palabra Bearer con su espacio, o la clave se cortó al pegarla. Una clave tiene unos cincuenta caracteres y empieza por lck_live_.

Qué puede hacer

Herramienta	Qué hace
check_email	Una dirección. Cuesta un crédito salvo que la respuesta sea catch-all o unknown.
get_balance	Créditos restantes. Gratis.
create_list	Envía una lista y recibe un precio. No cobra nada.
start_list	Empieza la comprobación. Esta es la llamada que gasta créditos.
get_list	Estado y progreso. Gratis.
get_list_summary	Los recuentos una vez ha terminado. Gratis.

Poner precio e iniciar son dos herramientas separadas a propósito, para que un asistente tenga que enseñarte lo que costará una lista antes de gastar nada, y tú puedas decir que no. Ninguna herramienta acepta una cuenta como argumento — la clave de la cabecera decide de quién son los créditos que se usan, así que nada de lo que un asistente lea o le cuenten puede apuntarlo a la cuenta de otra persona.

Trata la clave como una contraseña

Cualquier cosa que la tenga puede gastar tus créditos. Está en un archivo de configuración en texto claro, así que mantén ese archivo fuera de cualquier repositorio compartido, y revoca la clave si acaba donde no debía — la revocación surte efecto de inmediato, tanto para la API como para este servidor. Dale a cada máquina su propia clave y podrás revocar una sin tocar las demás.

Errores

Cada error es JSON con un código estable y una frase pensada para una persona:

{ "error": "unauthorized", "message": "Provide your API key as 'Authorization: Bearer <key>'." }

Código	Significado
400	Falta algo en la petición o algo está mal. El cuerpo dice qué.
401	Sin clave, o con una desconocida, revocada o caducada.
402	Créditos insuficientes. No se cobró ni se inició nada.
404	No existe esa lista en esta cuenta.
409	La lista no está en un estado en el que eso tenga sentido — ya iniciada, por ejemplo.
429	Límite de peticiones superado. Espera.

Lo que no hará

La API comprueba direcciones que ya tienes. No encuentra, genera ni suministra direcciones, y nunca envía correo a las direcciones que comprueba — la conversación con cada servidor de correo se cierra antes de que exista ningún mensaje. Usarla con listas raspadas, compradas o alquiladas está prohibido; consulta el uso aceptable.