Consultar um endereço de e-mail
Uma chamada diz se um endereço vai aceitar e-mail. Use na hora do cadastro, ou antes de agir sobre um lead, para manter endereços que iriam rejeitar fora do seu envio desde o início. Tudo aqui exige uma chave API com o escopo lookup.
Consultar um endereço
const answer = await bird.lookup.email({ email: "aisha.khan@example.com" });
// result is an open vocabulary; delivery_confidence is always comparable.
console.log(answer.result, answer.delivery_confidence);answer = client.lookup.email(email="aisha.khan@example.com")
# result is an open vocabulary; delivery_confidence is always comparable.
print(answer.result, answer.delivery_confidence)answer, err := client.Lookup.Email(context.Background(), bird.LookupEmailParams{
Email: "aisha.khan@example.com",
})
if err != nil {
log.Fatal(err)
}
// result is an open vocabulary; delivery_confidence is always comparable.
fmt.Println(*answer.Result, *answer.DeliveryConfidence)$answer = $bird->lookup->email(
(new EmailLookupRequest())->setEmail('aisha.khan@example.com'),
);
// result is an open vocabulary; delivery_confidence is always comparable.
echo $answer->getResult(), ' ', $answer->getDeliveryConfidence();bird lookup email --email aisha.khan@example.comcurl -X POST "https://us1.platform.bird.com/v1/lookup/email" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "aisha.khan@example.com"
}'Consultar um lote
Use POST /v1/lookup/email/batch para avaliar até 1.000 endereços em uma única solicitação:
Exemplo de código
curl -X POST "https://us1.platform.bird.com/v1/lookup/email/batch" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"emails":["aisha.khan@example.com","not-an-email"]}'O array data da resposta contém uma avaliação por entrada, na ordem de envio. Endereços malformados recebem avaliações individuais. Endereços duplicados permanecem como entradas separadas, e cada entrada respondida é cobrada. Espaços em branco ao redor são removidos e a capitalização é preservada.
Mantenha cada solicitação dentro de 128 KiB. Divida listas maiores em lotes separados. Se você optar por tentativas idempotentes, use uma chave distinta para cada lote. Respostas de até 256 KiB podem ser retidas para replay; respostas maiores são retornadas sem proteção de replay, então tentar novamente pode executar e cobrar por outro lote. Consulte a referência de lote API.
Como escrever o endereço
Envie o endereço puro, exatamente como você o possui. Uma consulta de endereço único rejeita formatos com display name como Aisha <aisha@example.com> em vez de extraí-los. Consultas em lote retornam uma avaliação para cada string enviada.
A parte antes do @ é passada como escrita em vez de convertida para minúsculas, e o campo email preserva essa capitalização. Respostas em lote removem espaços em branco ao redor; associe cada resultado à entrada na mesma posição. Envie o endereço na capitalização que você possui em vez de normalizá-lo antes: result geralmente é o mesmo de qualquer forma, mas delivery_confidence nem sempre é idêntico, então alterar a capitalização pode mudar a resposta que você recebe.
Os cinco vereditos
result é o campo para tomar a decisão.
valid: o endereço existe e aceita e-mail. Envie.
neutral: não foi possível confirmar de nenhuma forma, geralmente porque o domínio receptor responde da mesma maneira para todos os destinatários. Enviar é razoável; um endereço neutro não é um endereço ruim, é um endereço sem resposta definitiva.
risky: provavelmente aceita e-mail, mas tem mais chance do que a maioria de gerar bounce ou reclamação. Endereços de função, endereços descartáveis e endereços de baixa reputação aparecem aqui. Enviar ou não é uma decisão sobre sua própria tolerância a reclamações, e flags informa qual tipo de risco é.
undeliverable: não aceita e-mail. Não envie. reason diz o motivo: invalid_syntax para um endereço malformado, invalid_domain quando o domínio não aceita e-mail de forma alguma, invalid_recipient quando o domínio aceita e-mail mas esta caixa de correio não existe.
typo: o endereço parece ter erro de digitação, e did_you_mean traz a correção. Ofereça a correção a quem digitou o original em vez de enviar para ela sem perguntar: é uma suposição, e o endereço pretendido pode não ser nenhum dos dois.
result é um vocabulário aberto, então um valor que você não reconhece é um veredito futuro, não um erro. Trate os valores que você conhece e use delivery_confidence como fallback, que está sempre presente e sempre comparável.
Leia a confiança junto com o veredito, não no lugar dele
delivery_confidence vai de 0 (certeza de não ser entregue) a 100 (certeza de ser). A mesma pontuação pode estar sob neutral ou risky por motivos diferentes, então é uma segunda opinião, não um substituto para result. É o campo a usar quando você quer um único limiar para todos os vereditos, incluindo vereditos adicionados no futuro.
valid traz a avaliação de validade do provedor. Um destinatário inválido pode ter valid: false mesmo quando o domínio aceita e-mail. Use result e delivery_confidence juntos ao decidir se deve enviar; valid: true não garante entrega.
Flags descrevem o tipo de endereço
flags fica vazio quando nada notável se aplica. Três valores são definidos hoje, e é uma lista aberta.
role significa que o endereço nomeia uma função em vez de uma pessoa, como support@ ou info@. Respostas e consentimento são ambíguos, e reclamações são mais prováveis.
disposable significa que pertence a um provedor de endereços descartáveis, então normalmente vai deixar de existir.
free_provider significa que pertence a um provedor de caixa de correio para consumidores, como Gmail ou Outlook.com. Isso é comum para e-mail pessoal, e é um sinal apenas quando você esperava um endereço corporativo.
Tentar novamente sem pagar duas vezes
Todo endereço respondido é cobrado, incluindo undeliverable, porque essa é a resposta pela qual você pagou e o bounce que você evitou. Envie um Idempotency-Key para que uma nova tentativa reproduza o veredito armazenado em vez de comprar um segundo. Consulte Idempotência.
O formato GET, que coloca o endereço na URL, não pode carregar uma chave de idempotência. Use o formato POST para qualquer coisa automatizada.
Erros
| Código | O que aconteceu |
|---|---|
| E22003 | Uma consulta de endereço único recebeu um endereço de e-mail inválido. Nada foi cobrado. Consultas em lote avaliam strings malformadas individualmente e cobram essas avaliações. |
| E22001 | A carteira da organização não tem saldo suficiente para a consulta. Recarregue e tente novamente. Nada foi cobrado. |
| E22002 | A consulta está temporariamente indisponível. Tente novamente com backoff. Nada foi cobrado. |
Próximos passos
- Consultar um número de telefone é a outra metade do Lookup.
- Supressões impedem envios repetidos para endereços que já geraram bounce, sem custo.
- Referência de API do Lookup documenta todos os campos.
- Pesquisa de email: esse endereço vai mesmo aceitar mensagens é um vídeo que executa consultas contra um endereço de função, um erro de digitação e um provedor gratuito.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.