Referencia de la API REST de Email Verifier

La API de Email Verifier se ofrece bajo /api/v1. Usa el host de TrekMail donde tu cuenta inicia sesión. Los ejemplos usan https://YOUR-TREKMAIL-HOST como marcador de posición.

Autenticación y scopes

Envía un token de API en el encabezado Authorization:

Authorization: Bearer YOUR_API_TOKEN

Activa los scopes al crear el token:

Asigna ambos scopes a un cliente que deba enviar trabajo y después leer o descargar el resultado.

Host y formato de solicitud

Todos los ejemplos usan cuerpos JSON y un token Bearer. El cargador de archivos del panel es independiente de la API: POST /verify/bulk acepta un array JSON emails, no un archivo multipart. Usa el host exacto que corresponda a la cuenta y al token. No presupongas que un token o saldo de un host con una marca funciona en otro.

Envía Content-Type: application/json en las solicitudes POST /verify y POST /verify/bulk. Guarda el token y el valor de idempotencia fuera del código del cliente.

Idempotencia

POST /api/v1/verify/bulk y DELETE /api/v1/verify/bulk/{jobId} requieren el encabezado Idempotency-Key. Genera un valor nuevo para cada operación prevista y reutilízalo solo al reintentar esa misma operación.

Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee

La verificación individual y la cancelación de trabajos no requieren ese encabezado. Las solicitudes masivas también están protegidas mediante detección de listas duplicadas para la misma lista normalizada y el mismo modo durante 24 horas, pero una clave de idempotencia sigue siendo el mecanismo correcto para reintentar.

Cómo actuar ante un resultado de red incierto

Si tu aplicación pierde la respuesta de una solicitud masiva, no generes otra clave de idempotencia ni envíes otra lista. Repite la solicitud idéntica con la misma clave. Guarda la clave junto al identificador de la lista de origen hasta que TrekMail devuelva un ID de trabajo. Así, el reintento permanece vinculado a la operación original y no genera un segundo cargo evitable.

Resumen de endpoints

Antepón /api/v1 a cada ruta de la tabla.

Consultar el saldo de créditos

GET /api/v1/verify/credits

En el host estándar de TrekMail, la respuesta incluye la asignación del plan y el saldo comprado:

{
  "monthly_limit": 300,
  "monthly_used": 120,
  "monthly_remaining": 180,
  "purchased_balance": 5000,
  "total_available": 5180,
  "plan": "pro",
  "trialing": false,
  "resets_at": "2026-10-01T00:00:00+00:00"
}

En un host White Label, el producto con marca solo dispone de créditos comprados, por lo que la respuesta contiene purchased_balance y total_available.

Solicitud de ejemplo:

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

Consulta el saldo justo antes de un envío grande. La respuesta de saldo es una instantánea. Si una aplicación envía varios trabajos, debe registrar el importe cobrado en cada respuesta masiva en vez de calcularlo después a partir de una cifra obsoleta.

Campos del saldo

Las respuestas de saldo de White Label contienen menos campos deliberadamente, porque el producto con marca solo utiliza créditos comprados.

Verificar una dirección

POST /api/v1/verify

{
  "email": "person@example.com",
  "mode": "quick"
}

La respuesta incluye email, status, trust_score, checks, provider, risk_factors y credits_remaining. En el host estándar, credits_remaining contiene los valores monthly y purchased. La estructura detallada de checks puede variar según el modo y la información que ofrezca el proveedor receptor.

Quick cuesta 1 crédito. Deep suele costar 2 créditos, aunque las excepciones específicas del proveedor se calculan a 1 crédito. Si la verificación no puede ejecutarse después del cobro, la solicitud de una dirección reembolsa el cargo y devuelve una respuesta de indisponibilidad temporal.

Solicitud de ejemplo:

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"}'

Usa status, trust_score, provider y risk_factors del nivel superior como contrato normal de la aplicación. checks contiene pruebas auxiliares útiles, pero cada clave puede variar si se omite una comprobación previa, no está disponible o el modo Deep obtiene información adicional.

Interpretación de un resultado individual

No hagas que una aplicación trate una respuesta remota aceptada como verificación de propiedad o permiso. Mantén separadas las decisiones de suscripción, baja y preferencias de contacto.

Crear un trabajo masivo

POST /api/v1/verify/bulk

{
  "emails": ["first@example.com", "second@example.net"],
  "name": "September contacts",
  "mode": "deep"
}

Los duplicados se normalizan antes de calcular el precio. Un trabajo nuevo creado correctamente devuelve 201 con:

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

probe y skip explican el cálculo del precio de Deep. deep_savings es la diferencia respecto a cobrar la tarifa completa de Deep por cada dirección enviada. Una lista duplicada devuelve el job_id y estado existentes en vez de iniciar otro trabajo.

Solicitud de ejemplo:

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

La API comprueba que los valores enviados tengan una sintaxis de email válida antes de admitir el trabajo. Si se rechazan todas las entradas, devuelve 422 y no crea un trabajo. Si solo se rechazan algunas, la respuesta correcta indica rejected_count y hasta cinco valores en rejected_sample. No uses esa muestra pequeña como informe completo de limpieza. Conserva el resultado de validación del origen en tu propio importador.

Lista de control para el envío masivo

1. Lee y normaliza el origen en tu propia aplicación.
2. Limita la solicitud a 50,000 entradas enviadas.
3. Genera y conserva una clave de idempotencia antes de la solicitud.
4. Usa un nombre de trabajo suficientemente descriptivo para que un operador lo reconozca después.
5. Guarda job_id, credits_charged y el desglose de precio que devuelve TrekMail.
6. Consulta periódicamente el job_id guardado. No deduzcas la finalización de la solicitud HTTP original.

Consultar un trabajo

GET /api/v1/verify/bulk/{jobId}

La respuesta base incluye job_id, name, status, total, processed, progress, summary, created_at y completed_at.

Cuando hay resultados para un trabajo completado, parcial o fallido, la respuesta también incluye:

{
  "results": [
    {
      "email": "person@example.com",
      "status": "valid",
      "trust_score": 82,
      "checks": {},
      "provider": "example.com",
      "risk_factors": ["no_dmarc"]
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "last_page": 1}
}

Parámetros de consulta opcionales:

Un trabajo cancelado que tenga filas procesadas se puede descargar, pero usa el endpoint de descarga para exportarlo.

Leer estados sin hacer suposiciones

Un cliente de API debe hacer consultas periódicas con espera incremental. No envíes un nuevo trabajo masivo solo porque el actual siga pendiente o porque una solicitud de red haya agotado el tiempo localmente.

Ejemplo de respuesta de estado

{
  "job_id": 42,
  "name": "September contacts",
  "status": "processing",
  "total": 1500,
  "processed": 400,
  "progress": 27,
  "summary": {"safe": 220, "valid": 105, "risky": 55, "invalid": 20},
  "created_at": "2026-09-04T13:15:00+00:00",
  "completed_at": null
}

summary puede crecer mientras avanza el trabajo. Usa processed y total para mostrar el progreso, en vez de sumar solo las categorías que la aplicación reconoce actualmente.

Descargar un trabajo

GET /api/v1/verify/bulk/{jobId}/download

La descarga está disponible para trabajos completados, parciales o cancelados que tengan filas procesadas. Transmite un CSV con las columnas Email, Status, Trust Score, Provider y Risk Factors.

Ejemplo:

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

Guarda la descarga dentro del periodo de conservación de resultados de 15 días. El CSV es una exportación para tu propio flujo. No cambia el consentimiento, las suscripciones ni los contactos de otro sistema.

El endpoint de descarga devuelve un conflicto si todavía no hay una exportación procesada. Comprueba primero el estado del trabajo. Una solicitud correcta transmite el CSV en vez de devolver un envoltorio JSON, así que trátala como respuesta de archivo en tu cliente HTTP.

Enumerar trabajos

GET /api/v1/verify/bulk

Usa page, per_page y el parámetro opcional status. per_page tiene un valor predeterminado de 20 y admite de 1 a 100. Los estados de trabajo son pending, processing, completed, partial, cancelled y failed.

La respuesta contiene un array jobs y un objeto pagination. Cada registro de trabajo incluye ID, nombre, estado, total, cantidad procesada, progreso y marcas de tiempo.

Ejemplo:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk?status=processing&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Usa el endpoint de listado cuando el worker se reinicie o necesites conciliar los ID de trabajos. No trates el nombre de un trabajo como identificador único. Guarda el job_id numérico devuelto.

Estructura de la respuesta de lista

{
  "jobs": [
    {
      "job_id": 42,
      "name": "September contacts",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-09-04T13:15:00+00:00",
      "completed_at": "2026-09-04T13:28:00+00:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 20, "total": 1, "last_page": 1}
}

Usa el parámetro de consulta status cuando una página de operaciones solo necesite trabajos activos o finalizados. La paginación es importante para las cuentas que verifican muchas listas. No presupongas que una respuesta contiene todo el historial.

Cancelar un trabajo

POST /api/v1/verify/bulk/{jobId}/cancel

Cancela únicamente trabajos pendientes o en curso. Una respuesta correcta es:

{"status":"cancelled","credits_refunded":40}

El reembolso corresponde al trabajo no procesado. Si el trabajo llega a un estado terminal antes de que la cancelación lo alcance, la API devuelve un conflicto y no cambia el resultado.

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

Cancelar no elimina el trabajo. Descarga las filas procesadas si las necesitas o elimina después el registro finalizado.

Eliminar un trabajo

DELETE /api/v1/verify/bulk/{jobId}

Cancela primero un trabajo en curso. La eliminación borra definitivamente el trabajo y sus resultados después de que TrekMail retire de forma segura la lista de origen preparada. Una respuesta correcta es:

{"deleted":true}

curl -X DELETE https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 843ef0c5-4dc0-4c09-bacd-5bd0fe87e847"

Esta operación es permanente para el registro del verificador. No retira los archivos CSV que la aplicación ya haya descargado, por lo que debes aplicar tu propio proceso de conservación a esas copias.

Orden de eliminación

1. Consulta el estado del trabajo.
2. Cancélalo si está pendiente o en proceso.
3. Guarda cualquier exportación procesada que debas conservar.
4. Elimina con una clave de idempotencia el trabajo que ya no está en curso.
5. Elimina las copias que mantenga tu sistema según sus reglas de privacidad y conservación.

Errores y reintentos

La verificación individual tiene un límite de ruta de 60 solicitudes por minuto y el envío masivo, de 10 solicitudes por minuto. Implementa reintentos con espera incremental, conserva la misma clave de idempotencia para un reintento masivo y no reintentes a ciegas tras un resultado de red desconocido.

Patrón seguro de reintento

1. Genera y conserva una clave de idempotencia antes de un envío masivo.
2. Envía la solicitud con esa clave.
3. Si se pierde la respuesta, repite la solicitud idéntica con la misma clave.
4. Conserva el job_id devuelto y deja de crear nuevos envíos para esa lista de origen.
5. Consulta ese trabajo hasta que alcance un estado terminal y después descarga o procesa el resultado.

En una verificación individual, un 503 temporal significa que el servicio no pudo completar la comprobación. Reintenta después con la espera incremental habitual. No conviertas esa respuesta en un resultado Invalid en tu propia base de datos.

Proteger los datos de contacto

Las listas de correo son datos personales en muchos contextos. Envía solo los datos necesarios para la verificación, limita el acceso del token al sistema que ejecuta el trabajo y evita registrar arrays completos de direcciones en los logs de la aplicación. Cuando necesites logs, guarda el ID del trabajo, la cantidad, los tiempos y el resultado general, no la lista completa.

TrekMail conserva los resultados durante 15 días. Planifica el almacenamiento seguro de exportaciones o la ruta de eliminación antes de integrar listas de gran volumen.

Las señales de verificación no demuestran la propiedad de una persona, su consentimiento ni la entrega futura. Mantén la gestión de permisos y supresión en tu aplicación aunque una dirección obtenga Safe.