Referência da API REST do Email Verifier

A API do Email Verifier é disponibilizada em /api/v1. Utilize o host TrekMail usado pela sua conta para iniciar sessão. Os exemplos utilizam https://YOUR-TREKMAIL-HOST como marcador de posição.

Autenticação e âmbitos

Envie um token de API no cabeçalho Authorization:

Authorization: Bearer YOUR_API_TOKEN

Ative os âmbitos ao criar o token:

Conceda ambos os âmbitos se o cliente tiver de enviar trabalho e depois ler ou descarregar o resultado.

Host e formato do pedido

Todos os exemplos usam corpos JSON e um token Bearer. O carregamento de ficheiros no dashboard é separado da API: POST /verify/bulk aceita um array JSON emails, não um ficheiro multipart. Use exatamente o host da conta e do token. Não presuma que o token ou saldo de um host de marca funciona noutro.

Envie Content-Type: application/json nos pedidos POST /verify e POST /verify/bulk. Guarde o token e o valor de idempotência fora do código do cliente.

Idempotência

POST /api/v1/verify/bulk e DELETE /api/v1/verify/bulk/{jobId} exigem um cabeçalho Idempotency-Key. Gere um valor novo para cada operação pretendida e reutilize-o apenas ao repetir a mesma operação.

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

A verificação individual e o cancelamento não exigem esse cabeçalho. Um pedido em massa também está protegido pela deteção da mesma lista normalizada e modo num prazo de 24 horas, mas a chave de idempotência continua a ser o mecanismo correto para repetir.

Tratar um resultado de rede incerto

Se a aplicação perder a resposta a um pedido em massa, não gere outra chave nem envie outra lista. Repita o pedido idêntico com a mesma chave. Guarde a chave com o identificador da lista de origem até o TrekMail devolver o ID do trabalho. Assim, a repetição mantém-se ligada à operação original e evita uma segunda cobrança.

Resumo dos endpoints

Anteponha /api/v1 a todos os caminhos da tabela.

Ler o saldo de créditos

GET /api/v1/verify/credits

No host TrekMail normal, a resposta inclui a quota do plano e o 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"
}

Num host White Label, só os créditos comprados estão disponíveis para o produto de marca, pelo que a resposta contém purchased_balance e total_available.

Exemplo:

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

Leia o saldo imediatamente antes de um envio grande. A resposta é um instantâneo, portanto uma aplicação que envia vários trabalhos deve registar o valor cobrado em cada resposta em massa, em vez de o calcular depois a partir de um número desatualizado.

Campos do saldo

As respostas de saldo White Label têm intencionalmente menos campos porque o produto de marca só utiliza créditos comprados.

Verificar um endereço

POST /api/v1/verify

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

A resposta inclui email, status, trust_score, checks, provider, risk_factors e credits_remaining. No host normal, credits_remaining tem valores monthly e purchased. A forma detalhada de checks pode variar consoante o modo e o que o fornecedor destinatário disponibiliza.

Quick custa 1 crédito. Deep custa normalmente 2 créditos, enquanto as exceções específicas do fornecedor são calculadas a 1 crédito. Se a verificação não puder decorrer após a cobrança, o pedido individual reembolsa-a e devolve uma resposta de indisponibilidade temporária.

Exemplo:

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

Utilize status, trust_score, provider e risk_factors de nível superior como contrato normal da aplicação. checks contém indícios úteis, mas as chaves podem diferir quando uma verificação externa é ignorada, está indisponível ou Deep obtém mais informações.

Interpretar um resultado individual

Não trate uma resposta remota aceite como verificação de propriedade ou permissão. Mantenha separadas as decisões de subscrição, anulação e preferências.

Criar um trabalho em massa

POST /api/v1/verify/bulk

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

Os duplicados são normalizados antes do preço. Um trabalho novo bem-sucedido devolve 201:

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

probe e skip explicam o cálculo Deep. deep_savings é a diferença face a cobrar cada endereço à tarifa Deep completa. Uma lista duplicada devolve os job_id e estado existentes, em vez de iniciar outro trabalho.

Exemplo:

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

A API testa a sintaxe dos valores antes de admitir o trabalho. Se todos forem rejeitados, devolve 422 e não cria trabalho. Se alguns forem rejeitados, a resposta indica rejected_count e até cinco valores em rejected_sample. Não use essa pequena amostra como relatório completo de limpeza; retenha a validação da origem no seu importador.

Lista de verificação do envio em massa

1. Leia e normalize a origem na sua aplicação.
2. Limite o pedido a 50,000 entradas.
3. Gere e guarde uma chave de idempotência antes do pedido.
4. Dê ao trabalho um nome reconhecível pelo operador.
5. Guarde job_id, credits_charged e a discriminação do preço devolvida.
6. Consulte a job_id guardada; não deduza a conclusão do pedido HTTP original.

Ler um trabalho

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

A resposta base inclui job_id, name, status, total, processed, progress, summary, created_at e completed_at.

Quando há resultados para um trabalho concluído, parcial ou falhado, também inclui:

{
  "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 opcionais:

Um trabalho cancelado com linhas processadas pode ser descarregado, mas utilize o endpoint de download para exportar.

Ler estados sem adivinhar

O cliente deve consultar com espera progressiva. Não faça novo envio só porque o trabalho continua pendente ou um pedido de rede expirou localmente.

Exemplo de resposta 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 pode crescer durante o trabalho. Use processed e total para apresentar progresso, em vez de somar apenas as categorias reconhecidas pela aplicação.

Descarregar um trabalho

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

O download está disponível para trabalhos concluídos, parciais ou cancelados com linhas processadas. Transmite um CSV com colunas Email, Status, Trust Score, Provider e Risk Factors.

Exemplo:

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

Guarde o resultado durante o período de retenção de 15 dias. O CSV é uma exportação para o seu fluxo; não altera consentimentos, subscrições ou contactos noutro sistema.

O endpoint devolve conflito enquanto não houver exportação processada. Verifique primeiro o estado. Um pedido bem-sucedido transmite o CSV sem invólucro JSON, portanto trate-o como resposta de ficheiro.

Listar trabalhos

GET /api/v1/verify/bulk

Utilize page, per_page e opcionalmente status. per_page tem predefinição 20 e aceita 1 a 100. Os estados são pending, processing, completed, partial, cancelled e failed.

A resposta contém um array jobs e um objeto pagination. Cada registo tem ID, nome, estado, total, quantidade processada, progresso e datas.

Exemplo:

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

Use este endpoint quando o worker reiniciar ou for preciso reconciliar IDs. Não trate o nome como identificador único; guarde a job_id numérica devolvida.

Formato da resposta da 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}
}

Use status quando uma página operacional só precisar de trabalhos ativos ou concluídos. A paginação é importante para contas com muitas listas; não presuma que uma resposta contém todo o histórico.

Cancelar um trabalho

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

Cancele apenas trabalho pendente ou em execução. Uma resposta bem-sucedida é:

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

O reembolso corresponde ao trabalho não processado. Se o trabalho terminar antes de o cancelamento chegar, a API devolve conflito sem alterar o resultado.

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

Cancelar não elimina o trabalho. Descarregue as linhas processadas se necessário ou elimine depois o registo terminado.

Eliminar um trabalho

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

Cancele primeiro um trabalho em execução. A eliminação remove permanentemente o trabalho e os resultados depois de o TrekMail remover a lista de origem preparada. Uma resposta bem-sucedida é:

{"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"

A operação é permanente para o registo do verificador. Não retira CSV já descarregados pela aplicação, portanto aplique o seu processo de retenção a essas cópias.

Ordem de eliminação

1. Leia o estado.
2. Cancele se estiver pendente ou em processamento.
3. Guarde qualquer exportação processada que tenha de reter.
4. Elimine o trabalho parado com uma chave de idempotência.
5. Remova cópias do seu sistema segundo as regras de privacidade e retenção.

Erros e novas tentativas

A verificação individual tem limite de 60 pedidos por minuto e o envio em massa 10 por minuto. Crie novas tentativas com espera progressiva, preserve a chave em repetições em massa e não repita cegamente após um resultado de rede desconhecido.

Padrão seguro para repetir

1. Gere e guarde uma chave antes do envio em massa.
2. Envie o pedido com essa chave.
3. Se perder a resposta, repita o pedido idêntico com a mesma chave.
4. Guarde a job_id devolvida e pare de criar envios para essa lista.
5. Consulte até ao estado final e descarregue ou processe o resultado.

Numa verificação individual, um 503 temporário significa que o serviço não concluiu a verificação. Repita mais tarde com espera progressiva. Não converta a resposta em Invalid na sua base de dados.

Manter os contactos seguros

As listas de email são dados pessoais em muitos contextos. Envie apenas os dados necessários, limite o token ao sistema que executa o trabalho e evite registar arrays completos de endereços. Quando necessário, registe ID, quantidade, tempos e resultado geral em vez da lista completa.

O TrekMail retém resultados durante 15 dias. Planeie armazenamento seguro ou eliminação das suas exportações antes de integrar listas de grande volume.

Os sinais não provam propriedade, consentimento ou entrega futura. Mantenha permissões e supressões na aplicação mesmo quando um endereço obtém Safe.