Inicio rápido de la API de TrekMail Email Verifier

Utiliza la API cuando la verificación deba formar parte de tu producto o flujo de importación. Crea un token con verify:read y verify:write, mantenlo en secreto y llama al mismo host que utilizas para iniciar sesión. En los ejemplos, sustituye https://YOUR-TREKMAIL-HOST y YOUR_API_TOKEN.

1. Crear un token

1. Abre Dashboard → AI Agents & API.
2. Crea un token.
3. Activa verify:read y verify:write.
4. Guarda el token de forma segura. Solo se muestra una vez.

Envíalo con cada solicitud:

Authorization: Bearer YOUR_API_TOKEN

Guarda el token en un almacén de secretos o una variable de entorno. No lo incluyas en código del navegador, un repositorio público, una solicitud de soporte ni un archivo de contactos exportado. Si sospechas que quedó expuesto, revócalo y crea otro en el dashboard.

2. Verificar una dirección

Utiliza POST /api/v1/verify para obtener de inmediato el resultado de una sola dirección. Quick es el valor predeterminado cuando se omite mode.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

La respuesta contiene campos estables de nivel superior, como dirección, estado, puntuación de confianza, proveedor, factores de riesgo y créditos restantes. El objeto checks registra los datos detallados y puede variar cuando una comprobación no está disponible o el modo Deep aporta información adicional.

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

Lee primero status y trust_score. Considera las claves de cada comprobación como detalles de apoyo, no como garantía de propiedad del buzón o de entrega.

El endpoint individual tiene un límite de ruta de 60 solicitudes por minuto. Si compruebas una dirección introducida por un usuario durante el registro, llama al endpoint después de la validación básica en el cliente y muestra un error sencillo cuando el servicio no esté disponible temporalmente, en vez de bloquear a la persona de forma indefinida.

3. Enviar un trabajo masivo

Las solicitudes masivas aceptan una matriz JSON emails, no la carga de un archivo. Incluye una clave de idempotencia para que un reintento de red no cree otro trabajo.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"September contacts",
    "mode":"deep",
    "emails":["first@example.com","second@example.net"]
  }'

La lista puede contener hasta 50,000 entradas. TrekMail normaliza los duplicados y rechaza del trabajo las entradas con sintaxis no válida. La respuesta indica el ID del trabajo, la cantidad aceptada, una pequeña muestra rechazada, los créditos cobrados y el desglose del precio Deep.

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

probe es la cantidad cobrada con la tarifa Deep completa. skip es la cantidad cobrada con la tarifa normal porque el proveedor no ofrece información útil a nivel de buzón. La respuesta establece el coste definitivo de ese envío.

Antes de enviar una lista completa, elimina en tu propio importador los valores que no sean direcciones. La API elimina direcciones duplicadas e informa de la cantidad rechazada, pero validar el origen crea un registro de auditoría más claro. Si la solicitud agota el tiempo de espera desde el punto de vista de tu aplicación, repite la misma solicitud masiva con la misma clave de idempotencia y comprueba el ID devuelto antes de crear otro envío.

4. Consultar y descargar

Consulta el trabajo con GET /api/v1/verify/bulk/{jobId} hasta que alcance un estado final:

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

La respuesta incluye status, total, processed, progress, summary, la hora de creación y la de finalización. Los trabajos completos y parciales incluyen una matriz results paginada.

Consulta a intervalos razonables y aplica espera progresiva. Un trabajo puede permanecer pendiente antes de comenzar, y Deep puede tardar más cuando un proveedor receptor ofrece datos adicionales. No deduzcas una hora de finalización fija solo a partir del tamaño de la lista.

Puedes solicitar una página de resultados más pequeña o buscar una dirección conocida cuando haya resultados disponibles:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Descarga un trabajo procesado como CSV:

curl -o results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Los filtros de exportación de la API son all, safe y safe_risky (Safe + Valid + Risky).

Para detener un trabajo pendiente o en ejecución, utiliza el endpoint de cancelación. Reembolsa el trabajo sin procesar y conserva las filas procesadas:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Elimina un trabajo solo cuando quieras borrar tanto su registro del verificador como sus resultados. Si aún está en ejecución, cancélalo primero y utiliza después el endpoint de eliminación con una clave de idempotencia. La referencia completa muestra ambas llamadas.

5. Gestionar las respuestas habituales

• 402: la cuenta necesita más créditos.
• 422: comprueba el cuerpo de la solicitud, el modo seleccionado o la clave de idempotencia obligatoria para una solicitud masiva.
• 429: reduce la frecuencia y vuelve a intentarlo con espera progresiva.
• 503: la verificación no está disponible temporalmente. Vuelve a intentarlo más tarde; una verificación individual fallida se reembolsa.

Lista de comprobación para una integración en producción

1. Mantén el token en el servidor y concede solo los dos ámbitos necesarios del verificador.
2. Valida y normaliza los contactos antes de llamar a la API masiva.
3. Guarda el ID del trabajo, el identificador de la lista enviada, la clave de idempotencia y el valor credits_charged devuelto.
4. Consulta con espera progresiva en vez de utilizar un bucle continuo.
5. Guarda o procesa el CSV antes de que termine su periodo de conservación de 15 días.
6. Conserva las decisiones de consentimiento, baja y supresión en tu propia aplicación. El resultado del verificador no las sustituye.

Utiliza la Referencia de la API REST de Email Verifier para consultar todos los endpoints, ámbitos y campos de respuesta.