Início rápido da API do TrekMail Email Verifier

Utilize a API quando a verificação precisar de fazer parte do seu produto ou fluxo de importação. Crie um token com verify:read e verify:write, mantenha-o secreto e chame o mesmo host que utiliza para iniciar sessão. Nos exemplos, substitua https://YOUR-TREKMAIL-HOST e YOUR_API_TOKEN.

1. Criar um token

1. Abra Dashboard → AI Agents & API.
2. Crie um token.
3. Ative verify:read e verify:write.
4. Guarde o token em segurança. Só é apresentado uma vez.

Envie-o em todos os pedidos:

Authorization: Bearer YOUR_API_TOKEN

Guarde o token num cofre de segredos ou numa variável de ambiente. Não o coloque em código do navegador, num repositório público, num pedido de suporte ou num ficheiro de contactos exportado. Se suspeitar que foi exposto, revogue-o e crie outro no dashboard.

2. Verificar um endereço

Utilize POST /api/v1/verify para obter imediatamente o resultado de um único endereço. Quick é a predefinição quando mode é omitido.

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

A resposta contém campos de nível superior estáveis, como endereço, estado, pontuação de confiança, fornecedor, fatores de risco e créditos restantes. O objeto checks regista os indícios detalhados e pode variar quando uma verificação não está disponível ou o modo Deep oferece informações adicionais.

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

Leia primeiro status e trust_score. Considere as chaves de cada verificação como detalhes de apoio, não como garantia de propriedade da caixa de correio ou de entrega.

O endpoint individual tem um limite de rota de 60 pedidos por minuto. Se verificar um endereço introduzido por um utilizador durante o registo, chame-o após uma validação básica no cliente e apresente um erro simples quando o serviço estiver temporariamente indisponível, em vez de bloquear a pessoa indefinidamente.

3. Enviar um trabalho em massa

Os pedidos em massa aceitam um array JSON emails, não o carregamento de um ficheiro. Inclua uma chave de idempotência para que uma nova tentativa de rede não crie um segundo trabalho.

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

A lista pode conter até 50,000 entradas. O TrekMail normaliza duplicados e rejeita do trabalho entradas com sintaxe inválida. A resposta indica o ID do trabalho, a quantidade aceite, uma pequena amostra rejeitada, os créditos cobrados e a discriminação do preço 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 é a quantidade cobrada à tarifa Deep completa. skip é a quantidade cobrada à tarifa normal porque o fornecedor não disponibiliza indícios úteis ao nível da caixa de correio. A resposta indica o custo definitivo desse envio.

Antes de enviar uma lista completa, remova no seu importador os valores que não sejam endereços. A API elimina endereços duplicados e indica a quantidade rejeitada, mas a validação na origem cria um histórico de auditoria mais claro. Se o pedido exceder o tempo limite do ponto de vista da sua aplicação, repita o mesmo pedido em massa com a mesma chave de idempotência e verifique o ID devolvido antes de criar outro envio.

4. Consultar e descarregar

Consulte o trabalho com GET /api/v1/verify/bulk/{jobId} até que atinja um estado final:

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

A resposta inclui status, total, processed, progress, summary, a hora de criação e a hora de conclusão. Os trabalhos concluídos e parciais incluem um array results paginado.

Consulte a intervalos razoáveis com espera progressiva. Um trabalho pode permanecer pendente antes de começar e o trabalho Deep pode demorar mais quando um fornecedor destinatário oferece indícios adicionais. Não presuma um tempo de conclusão fixo apenas a partir do tamanho da lista.

Pode pedir uma página de resultados menor ou procurar um endereço conhecido quando os resultados estiverem disponíveis:

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

Descarregue um trabalho processado como CSV:

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

Os filtros de exportação da API são all, safe e safe_risky (Safe + Valid + Risky).

Para parar um trabalho pendente ou em execução, utilize o endpoint de cancelamento. Este reembolsa o trabalho não processado e mantém as linhas processadas:

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

Elimine um trabalho apenas quando pretender remover o registo do verificador e os respetivos resultados. Se ainda estiver em execução, cancele-o primeiro e depois utilize o endpoint de eliminação com uma chave de idempotência. A referência completa mostra ambas as chamadas.

5. Tratar as respostas habituais

• 402: a conta precisa de mais créditos.
• 422: verifique o corpo do pedido, o modo selecionado ou a chave de idempotência obrigatória num pedido em massa.
• 429: reduza a frequência e volte a tentar com espera progressiva.
• 503: a verificação está temporariamente indisponível. Volte a tentar mais tarde; uma verificação individual sem êxito é reembolsada.

Lista de verificação para uma integração em produção

1. Mantenha o token no servidor e conceda apenas os dois âmbitos necessários do verificador.
2. Valide e normalize os contactos antes de chamar a API em massa.
3. Guarde o ID do trabalho, o identificador da lista enviada, a chave de idempotência e o valor credits_charged devolvido.
4. Consulte com espera progressiva em vez de utilizar um ciclo contínuo.
5. Guarde ou processe o CSV antes do fim do período de retenção de 15 dias.
6. Mantenha as decisões de consentimento, anulação de subscrição e supressão na sua própria aplicação. Um resultado do verificador não as substitui.

Utilize a Referência da API REST do Email Verifier para todos os endpoints, âmbitos e campos de resposta.