Idioma

English Italiano Deutsch Español Português (Brasil)Français

¿Buscas una visión general? Consulta la API de verificación de correo o la API de validación de correo para formularios de registro (en inglés).

Referencia de la API para validar correos

Verifica correos uno a uno, procesa lotes en bloque y haz una verificación profunda de direcciones catch-all y protegidas por SEG. Todos los endpoints usan JSON, se autentican con una clave de API y se cobran por cada verificación correcta.

Introducción

La API de Giggal.ai te permite verificar direcciones de correo una a una, procesar lotes de hasta 50.000 correos por tarea y hacer una verificación profunda de direcciones catch-all y protegidas por SEG, con una API REST sencilla en JSON. Cada verificación correcta descuenta créditos de tu cuenta.

URL base

https://api.giggal.ai/v1

Consigue una clave de API

Crea una clave de API desde tu panel de Giggal.ai. Abre la pestaña Developer API en la barra lateral y haz clic en Create API Key. Cada clave pertenece a tu cuenta, registra su propio uso y se puede revocar en cualquier momento.

Abrir la pestaña Developer API

Estructura de la respuesta

Todas las respuestas siguen la misma estructura JSON:

// Success
{ "success": true, "data": { ... }, "meta": { ... } }

// Error
{ "success": false, "error": "Human-readable error message" }

Inicio rápido: verifica un correo con cURL

curl -X POST https://api.giggal.ai/v1/verify \
  -H "Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"info@giggal.ai"}'

Autenticación

Envía tu clave de API en cada solicitud con una de estas dos cabeceras. Las dos funcionan.

Opción 1: token Bearer

Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Opción 2: cabecera X-API-Key

X-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Si la clave falta, no es válida o fue revocada, la API devuelve HTTP 401. No expongas nunca tus claves de API en el código del lado del cliente. Haz las llamadas a través de tu backend.

Idempotencia (en bloque y catch-all)

En POST /v1/verify-batch y POST /v1/catchall, envía una cabecera Idempotency-Key. Si repites la solicitud con la misma clave, recibes la respuesta original. No se crea una tarea duplicada ni se cobran los créditos dos veces.

Idempotency-Key: 2026-07-24-list-batch-42

Verificación individual

1 endpoint en este grupo.

POST/v1/verify

Verificar un solo correo

Verifica una dirección de correo de forma síncrona. Cuesta 1 crédito. Si el dominio es catch-all, la verificación profunda se hace en la misma solicitud y la respuesta incluye catch_all_score y catch_all_verdict.

Autorizaciones

api_key_auth

Cuerpo de la solicitud

Obligatorio

string

La dirección de correo que quieres verificar.

POST/v1/verify

Ejemplos de respuesta

{
  "success": true,
  "data": {
    "email": "info@giggal.ai",
    "is_valid": true,
    "status": "deliverable",
    "risk_level": "low",
    "deliverability_score": 89,
    "details": {
      "general": {
        "domain": "giggal.ai",
        "reason": "Mailbox confirmed deliverable"
      },
      "attributes": {
        "free_email": false,
        "role_account": false,
        "disposable": false,
        "catch_all": true,
        "has_plus_tag": false,
        "mailbox_full": false,
        "no_reply": false
      },
      "mail_server": {
        "smtp_provider": "google",
        "mx_record": "aspmx.l.google.com",
        "implicit_mx": null
      },
      "blacklist": {
        "is_blacklisted": false,
        "blacklists_found": [],
        "blacklist_reasons": [],
        "reputation_score": 100,
        "last_checked": "2026-07-23T20:47:15.540Z"
      },
      "sub_status": null
    },
    "catch_all_score": 89,
    "catch_all_verdict": "valid"
  },
  "meta": {
    "creditsUsed": 1
  }
}

Verificación en bloque

3 endpoints en este grupo.

POST/v1/verify-batch

Enviar una tarea de verificación en bloque

Envía hasta 50.000 correos por tarea. El procesamiento es asíncrono, así que consulta GET /v1/jobs/:jobId para ver el avance. Envía una cabecera Idempotency-Key para repetir la creación de la tarea sin riesgo de cobros dobles.

Autorizaciones

api_key_auth

Cuerpo de la solicitud

emails

Obligatorio

string[]

Lista de direcciones de correo a verificar. Máximo 50.000 por tarea. El servidor elimina los duplicados y las direcciones mal formadas.

name

string

Nombre opcional de la tarea, fácil de leer. Aparece en tu panel.

POST/v1/verify-batch

Ejemplos de respuesta

{
  "success": true,
  "data": {
    "jobId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "processing",
    "name": "July prospect list",
    "submittedEmails": 19,
    "totalEmails": 19,
    "acceptedEmails": 19,
    "rejectedEmails": 0,
    "processedEmails": 0,
    "progress": { "total": 19, "processed": 0, "percentage": 0 },
    "requestId": "e8044428-e49f-4aa2-9900-e29d73fd4071",
    "batchIds": [
      "a639b1de-0e3a-4f8a-882d-95cee9db3f99",
      "c2760ed9-eced-4222-939b-3fa4151bde93"
    ],
    "createdAt": "2026-07-23T20:47:21.908Z",
    "updatedAt": "2026-07-23T20:47:22.040Z",
    "completedAt": null,
    "resultsExpiresAt": null,
    "resultsExpired": false,
    "error": null
  },
  "meta": {
    "idempotentReplay": false,
    "acceptedEmails": 19,
    "rejectedEmails": 0,
    "duplicateEmails": 0,
    "invalidEmails": 0
  }
}

GET/v1/jobs/:jobId

Consultar el estado de una tarea en bloque

Consulta este endpoint para ver el avance. Cambios de estado: processing → completed (o failed). Intervalo de consulta recomendado: de 10 a 15 segundos. Los lotes pequeños (< 50 correos) suelen terminar en menos de 30 segundos.

Autorizaciones

api_key_auth

Parámetros de ruta y de consulta

jobId

Obligatorio

string

El ID de tarea que devuelve POST /v1/verify-batch.

GET/v1/jobs/:jobId

Ejemplos de respuesta

{
  "success": true,
  "data": {
    "jobId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "completed",
    "name": "July prospect list",
    "submittedEmails": 19,
    "totalEmails": 19,
    "acceptedEmails": 19,
    "rejectedEmails": 0,
    "processedEmails": 19,
    "progress": { "total": 19, "processed": 19, "percentage": 100 },
    "requestId": "e8044428-e49f-4aa2-9900-e29d73fd4071",
    "batchIds": [
      "a639b1de-0e3a-4f8a-882d-95cee9db3f99",
      "c2760ed9-eced-4222-939b-3fa4151bde93"
    ],
    "createdAt": "2026-07-23T20:47:21.908Z",
    "updatedAt": "2026-07-23T20:48:00.848Z",
    "completedAt": "2026-07-23T20:48:00.840Z",
    "resultsExpiresAt": "2026-07-25T20:48:00.840Z",
    "resultsExpired": false,
    "error": null
  }
}

GET/v1/jobs/:jobId/results

Obtener los resultados de una tarea en bloque

Cuando el estado sea "completed", obtén los resultados de cada correo. Los resultados están paginados, así que envía los parámetros de consulta page y limit. Los resultados se guardan durante 48 horas (consulta resultsExpiresAt en la tarea).

Autorizaciones

api_key_auth

Parámetros de ruta y de consulta

jobId

Obligatorio

string

El ID de la tarea.

page

integer

Número de página. Por defecto, 1.

limit

integer

Resultados por página. Por defecto, 25. Máximo, 500.

GET/v1/jobs/:jobId/results

Ejemplos de respuesta

{
  "success": true,
  "data": {
    "job": {
      "jobId": "api_job_6a627dd94559c7cd818d8fc9",
      "status": "completed",
      "name": "July prospect list",
      "totalEmails": 19,
      "processedEmails": 19,
      "completedAt": "2026-07-23T20:48:00.840Z",
      "resultsExpiresAt": "2026-07-25T20:48:00.840Z"
    },
    "results": [
      {
        "email": "hassaan@giggal.ai",
        "status": "deliverable",
        "is_valid": true,
        "risk_level": "high",
        "deliverability_score": 88,
        "details": {
          "general": {
            "domain": "giggal.ai",
            "reason": "All validations passed"
          },
          "attributes": {
            "free_email": false,
            "role_account": false,
            "disposable": false,
            "catch_all": true,
            "has_plus_tag": false,
            "mailbox_full": false,
            "no_reply": false
          },
          "mail_server": {
            "smtp_provider": "google",
            "mx_record": "aspmx.l.google.com",
            "implicit_mx": null
          },
          "blacklist": {
            "is_blacklisted": false,
            "blacklists_found": [],
            "reputation_score": 100,
            "last_checked": "2026-07-23T20:47:22.665Z"
          },
          "sub_status": null
        }
      },
      {
        "email": "zain@giggal.ai",
        "status": "deliverable",
        "is_valid": true,
        "risk_level": "low",
        "deliverability_score": 100,
        "details": { "general": { "domain": "giggal.ai", "reason": "2.1.5 OK" }, "...": "..." }
      }
    ],
    "pagination": {
      "total": 19,
      "page": 1,
      "limit": 25,
      "pages": 1
    }
  }
}

Verificación catch-all

4 endpoints en este grupo.

POST/v1/catchall

Iniciar una tarea de verificación catch-all

Inicia la verificación profunda catch-all de una tarea en bloque terminada. Solo se vuelven a comprobar las direcciones marcadas como catch-all en la tarea de origen. Se cobra 1 crédito por dirección (consulta creditsRequired en la respuesta).

Autorizaciones

api_key_auth

Cuerpo de la solicitud

jobId

Obligatorio

string

El ID de una tarea de verificación en bloque terminada. Solo se verifican a fondo las direcciones catch-all de esa tarea.

name

string

Nombre opcional de la tarea, fácil de leer.

POST/v1/catchall

Ejemplos de respuesta

{
  "success": true,
  "data": {
    "taskId": "catchall_e4194da2-c118-47c2-84bf-9c25ce8a363e",
    "sourceJobId": "api_job_6a627dd94559c7cd818d8fc9",
    "fileId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "processing",
    "name": "Catch-all round for July list",
    "totalEmails": 8,
    "processedEmails": 0,
    "progress": { "total": 8, "processed": 0, "percentage": 0 },
    "requestId": "4e7596e0-c51e-4b05-b4e9-4b8a681041fd",
    "batchIds": ["7d2b1f03-68dd-4687-be95-fcc4fbabc2e7"],
    "creditsUsed": 0,
    "creditsRequired": 8,
    "creditsPerEmail": 1,
    "verdictCounts": { "valid": 0, "invalid": 0 },
    "initiatedVia": "developer_api",
    "createdAt": "2026-07-23T20:50:51.468Z",
    "updatedAt": "2026-07-23T20:50:51.662Z",
    "lastUpdated": "2026-07-23T20:50:51.468Z"
  },
  "meta": {
    "idempotentReplay": false
  }
}

GET/v1/catchall/:taskId

Consultar el estado de una tarea catch-all

Consulta este endpoint para ver el avance y los verdictCounts en tiempo real. Las tareas catch-all suelen terminar en unos segundos o en unos minutos, según el volumen.

Autorizaciones

api_key_auth

Parámetros de ruta y de consulta

taskId

Obligatorio

string

El ID de tarea que devuelve POST /v1/catchall.

GET/v1/catchall/:taskId

Ejemplos de respuesta

{
  "success": true,
  "data": {
    "taskId": "catchall_e4194da2-c118-47c2-84bf-9c25ce8a363e",
    "sourceJobId": "api_job_6a627dd94559c7cd818d8fc9",
    "fileId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "completed",
    "name": "Catch-all round for July list",
    "totalEmails": 8,
    "processedEmails": 8,
    "progress": { "total": 8, "processed": 8, "percentage": 100 },
    "requestId": "4e7596e0-c51e-4b05-b4e9-4b8a681041fd",
    "batchIds": ["7d2b1f03-68dd-4687-be95-fcc4fbabc2e7"],
    "creditsUsed": 8,
    "creditsRequired": 8,
    "creditsPerEmail": 1,
    "verdictCounts": { "valid": 1, "invalid": 7 },
    "initiatedVia": "developer_api",
    "createdAt": "2026-07-23T20:50:51.468Z",
    "updatedAt": "2026-07-23T20:50:56.646Z",
    "lastUpdated": "2026-07-23T20:50:56.583Z"
  }
}

GET/v1/catchall/:taskId/results

Obtener los resultados de una tarea catch-all

Obtén los resultados paginados de cada correo con el desglose de la puntuación (señales de clasificación del dominio y antigüedad del dominio).

Autorizaciones

api_key_auth

Parámetros de ruta y de consulta

taskId

Obligatorio

string

El ID de la tarea.

page

integer

Número de página. Por defecto, 1.

limit

integer

Resultados por página. Por defecto, 25. Máximo, 500.

verdict

string

Filtra por resultado: valid | invalid.

GET/v1/catchall/:taskId/results

Ejemplos de respuesta

{
  "success": true,
  "data": {
    "task": {
      "taskId": "catchall_e4194da2-c118-47c2-84bf-9c25ce8a363e",
      "status": "completed",
      "totalEmails": 8,
      "verdictCounts": { "valid": 1, "invalid": 7 }
    },
    "results": [
      {
        "email": "hassaan@giggal.ai",
        "score": 88,
        "verdict": "valid",
        "is_actually_catchall": true,
        "breakdown": {
          "domain_triage": {
            "score": 16,
            "max": 25,
            "signals": [
              "provider:google",
              "auth:partial",
              "spf:strict",
              "mx:multiple",
              "ssl:valid",
              "a_records",
              "tld:trusted"
            ],
            "ssl_cert_age_days": 22
          },
          "domain_age": {
            "score": 12,
            "max": 15,
            "signals": ["age:9y"]
          }
        }
      },
      {
        "email": "zain@giggal.ai",
        "score": 9,
        "verdict": "invalid",
        "is_actually_catchall": true,
        "breakdown": {
          "domain_triage": {
            "score": 23,
            "max": 25,
            "signals": ["provider:google", "auth:spf+dkim+dmarc", "dmarc:reject"],
            "ssl_cert_age_days": 53
          },
          "domain_age": {
            "score": 15,
            "max": 15,
            "signals": ["age:11y"]
          }
        }
      }
    ],
    "pagination": {
      "total": 8,
      "page": 1,
      "limit": 25,
      "pages": 1
    }
  }
}

GET/v1/catchall/:taskId/download

Descargar los resultados catch-all en CSV

Descarga todos los resultados de una tarea catch-all terminada en un archivo CSV con las columnas Email, Score y Verdict. El Content-Type es text/csv.

Autorizaciones

api_key_auth

Parámetros de ruta y de consulta

taskId

Obligatorio

string

El ID de la tarea.

verdict

string

Filtra por resultado: valid | invalid.

GET/v1/catchall/:taskId/download

Ejemplos de respuesta

Email,Score,Verdict
"hassaan@giggal.ai",88,"valid"
"zain@giggal.ai",9,"invalid"
"info@giggal.ai",8,"invalid"
"hassaan@giggal.ai",6,"invalid"
"zain@giggal.ai",3,"invalid"
"info@giggal.ai",8,"invalid"
"hassaan@giggal.ai",6,"invalid"
"zain@giggal.ai",9,"invalid"

Cuenta

1 endpoint en este grupo.

GET/v1/credits

Consultar el saldo de créditos

Devuelve el saldo de tu cuenta: créditos disponibles, reservados (retenidos para tareas en curso) y totales históricos. Las verificaciones que vuelven como "unknown" se reembolsan de forma automática y se reflejan aquí.

Autorizaciones

api_key_auth

GET/v1/credits

Ejemplos de respuesta

{
  "success": true,
  "data": {
    "balance": 145,
    "availableCredits": 145,
    "reservedCredits": 0,
    "totalPurchased": 1000,
    "totalConsumed": 92100,
    "transactionCount": 247,
    "lastTransactionAt": "2026-07-20T21:52:27.374Z"
  }
}

Errores y límites de uso

Estado	Significado
200 OK	La solicitud se completó (verificación síncrona o consulta de estado o resultados).
202 Accepted	La tarea asíncrona se creó y está en cola.
400 Bad Request	Faltan parámetros o no son válidos (formato de correo incorrecto, lista emails vacía, falta jobId).
401 Unauthorized	La clave de API falta, no es válida o fue revocada.
402 Payment Required	No tienes créditos suficientes para la operación solicitada.
404 Not Found	El ID de tarea no existe en tu cuenta.
409 Conflict	La tarea no está en el estado necesario (por ejemplo, pides los resultados antes de que termine).
410 Gone	Los resultados de la tarea superaron el plazo de conservación de 48 horas.
429 Too Many Requests	Se superó el límite de uso. Espera y vuelve a intentarlo.
500 / 502 / 503	El servidor o el servicio de verificación no está disponible por el momento.

Límites de uso

Cada respuesta incluye las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (con la escritura del RFC) para que puedas espaciar tus solicitudes. RateLimit-Reset es el número de segundos que faltan para que se reinicie la ventana actual.

Categoría	Límite
Todos los endpoints (por defecto)	300 solicitudes / 15 minutos
Creación de lotes (POST /v1/verify-batch, POST /v1/catchall)	30 solicitudes / 15 minutos
Consulta de tareas (GET /v1/jobs/:id, GET /v1/jobs/:id/results)	600 solicitudes / 15 minutos
Máximo de correos por tarea en bloque	50.000
Conservación de los resultados	48 horas

Hay tres niveles porque las consultas de estado se hacen más a menudo que la creación de lotes. Puedes consultar cada pocos segundos mientras una tarea está en curso. Por eso 600 / 15 min (≈ 40/min) te da margen sin sobrecargar el backend.

¿Necesitas límites más altos?

Subimos los límites de forma habitual para los socios de integración verificados.

Habla con nosotros

Formato de la respuesta 429

Cuando alcanzas un límite de uso, la API devuelve HTTP 429 con este cuerpo:

{
  "success": false,
  "message": "Developer API rate limit exceeded"
}

Antes de volver a intentarlo, espera el tiempo que indica la cabecera RateLimit-Reset (segundos hasta que se reinicia la ventana).

¿Listo para integrar la API?

Crea tu clave de API en segundos. Incluye créditos de prueba gratis para que conectes todo de principio a fin antes de gastar nada.

Consigue tu clave de API Habla con nuestro equipo