Referência da API de verificação de e-mail
Verifique e-mails individuais, processe lotes em massa e faça uma verificação aprofundada de endereços catch-all e protegidos por SEG. Todos os endpoints usam JSON, são autenticados com uma chave de API e são cobrados por verificação concluída com sucesso.
Introdução
A API da Giggal.ai permite verificar endereços de e-mail individuais, processar lotes de até 50.000 e-mails por tarefa e fazer uma verificação aprofundada de endereços catch-all e protegidos por SEG, com uma API REST simples em JSON. Cada verificação concluída com sucesso consome créditos da sua conta.
https://api.giggal.ai/v1Crie uma chave de API no painel da Giggal.ai. Abra a aba Developer API na barra lateral e clique em Create API Key. Cada chave pertence à sua conta, registra o próprio uso e pode ser revogada a qualquer momento.
Abrir a aba Developer APITodas as respostas seguem o mesmo formato JSON:
// Success
{ "success": true, "data": { ... }, "meta": { ... } }
// Error
{ "success": false, "error": "Human-readable error message" }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"}'Autenticação
Envie a sua chave de API em cada requisição, usando um destes dois cabeçalhos. Qualquer um funciona.
Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxxX-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxxChaves ausentes, inválidas ou revogadas devolvem HTTP 401. Nunca exponha chaves de API no código do lado do cliente. Faça as chamadas passarem pelo seu backend.
Para POST /v1/verify-batch e POST /v1/catchall, envie um cabeçalho Idempotency-Key. Novas tentativas com a mesma chave devolvem a resposta original, sem criar uma tarefa duplicada e sem cobrar os créditos duas vezes.
Idempotency-Key: 2026-07-24-list-batch-42Verificação individual
1 endpoint neste grupo.
/v1/verifyVerificar um único e-mail
Verifica um endereço de e-mail de forma síncrona. Custa 1 crédito. Quando o domínio é catch-all, a verificação aprofundada roda na mesma chamada, e a resposta inclui catch_all_score e catch_all_verdict.
Verificação em massa
3 endpoints neste grupo.
/v1/verify-batchEnviar uma tarefa de verificação em massa
Envie até 50.000 e-mails por tarefa. O processamento é assíncrono, então consulte GET /v1/jobs/:jobId para ver o andamento. Envie um cabeçalho Idempotency-Key para repetir a criação da tarefa com segurança, sem cobrança dupla.
/v1/jobs/:jobIdConsultar o status de uma tarefa em massa
Consulte para acompanhar o andamento. O status passa de processing para completed (ou failed). Intervalo de consulta recomendado: 10 a 15 segundos. Lotes pequenos (menos de 50 e-mails) costumam terminar em até 30 segundos.
/v1/jobs/:jobId/resultsObter os resultados de uma tarefa em massa
Quando o status for "completed", busque os resultados de cada e-mail. Os resultados são paginados, então envie os parâmetros de consulta page e limit. Os resultados ficam guardados por 48 horas (veja resultsExpiresAt na tarefa).
Verificação catch-all
4 endpoints neste grupo.
/v1/catchallIniciar uma tarefa de verificação catch-all
Inicia a verificação catch-all aprofundada de uma tarefa em massa já concluída. Só os endereços marcados como catch-all na tarefa de origem são verificados de novo. A cobrança é de 1 crédito por endereço (veja creditsRequired na resposta).
/v1/catchall/:taskIdConsultar o status de uma tarefa catch-all
Consulte para acompanhar o andamento e a contagem de resultados em tempo real (verdictCounts). As tarefas catch-all costumam terminar entre alguns segundos e alguns minutos, conforme o volume.
/v1/catchall/:taskId/resultsObter os resultados de uma tarefa catch-all
Busca os resultados paginados de cada e-mail, com o detalhamento da pontuação (sinais de triagem do domínio e idade do domínio).
/v1/catchall/:taskId/downloadBaixar os resultados catch-all em CSV
Baixa todos os resultados de uma tarefa catch-all concluída em um arquivo CSV com as colunas Email, Score e Verdict. O Content-Type é text/csv.
Conta
1 endpoint neste grupo.
/v1/creditsConsultar o saldo atual de créditos
Devolve o saldo da sua conta, com os créditos disponíveis, os reservados (separados para tarefas em andamento) e os totais desde a criação da conta. As verificações que voltam como "unknown" são reembolsadas automaticamente e aparecem aqui.
Erros e limites de requisição
| Status | Significado |
|---|---|
| 200 OK | A requisição foi concluída (verificação síncrona ou consulta de status e resultados). |
| 202 Accepted | Tarefa assíncrona criada e colocada na fila. |
| 400 Bad Request | Parâmetros ausentes ou inválidos (formato de e-mail incorreto, lista emails vazia, jobId ausente). |
| 401 Unauthorized | Chave de API ausente, inválida ou revogada. |
| 402 Payment Required | Créditos insuficientes para a operação pedida. |
| 404 Not Found | O ID da tarefa não existe na sua conta. |
| 409 Conflict | A tarefa não está no estado exigido (por exemplo, ao pedir resultados antes da conclusão). |
| 410 Gone | Os resultados da tarefa passaram do prazo de 48 horas de armazenamento. |
| 429 Too Many Requests | Limite de requisições excedido. Espere e tente de novo. |
| 500 / 502 / 503 | O servidor ou o serviço de verificação está temporariamente indisponível. |
Limites de requisição
Todas as respostas incluem os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (grafia da RFC), para que você controle o ritmo das requisições. RateLimit-Reset é o número de segundos até a janela atual reiniciar.
| Categoria | Limite |
|---|---|
| Todos os endpoints (padrão) | 300 requisições / 15 minutos |
| Criação de lotes (POST /v1/verify-batch, POST /v1/catchall) | 30 requisições / 15 minutos |
| Consulta de tarefas (GET /v1/jobs/:id, GET /v1/jobs/:id/results) | 600 requisições / 15 minutos |
| Máximo de e-mails por tarefa em massa | 50.000 |
| Armazenamento dos resultados das tarefas | 48 horas |
Existem três faixas porque as consultas de status acontecem com mais frequência do que a criação de lotes. Você pode consultar a cada poucos segundos enquanto uma tarefa roda. Por isso, 600 / 15 min (cerca de 40 por minuto) dá margem sem sobrecarregar o backend.
Precisa de limites maiores?
Aumentamos os limites com frequência para parceiros de integração verificados.
Formato da resposta 429
Quando você atinge um limite, a API devolve HTTP 429 com este corpo:
{
"success": false,
"message": "Developer API rate limit exceeded"
}Antes de tentar de novo, espere o tempo indicado no cabeçalho RateLimit-Reset (segundos até a janela reiniciar).
Pronto para integrar?
Crie a sua chave de API em segundos. Os créditos de teste grátis estão incluídos, para que você monte a integração de ponta a ponta antes de gastar qualquer valor.