# 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

**TypeScript**

```typescript
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);
```

Examples: [TypeScript](/pt-br/documentacao/guides/lookup/email-addresses.ts.md) · [Python](/pt-br/documentacao/guides/lookup/email-addresses.py.md) · [Go](/pt-br/documentacao/guides/lookup/email-addresses.go.md) · [PHP](/pt-br/documentacao/guides/lookup/email-addresses.php.md) · [CLI](/pt-br/documentacao/guides/lookup/email-addresses.cli.md) · [MCP](/pt-br/documentacao/guides/lookup/email-addresses.mcp.md) · [cURL](/pt-br/documentacao/guides/lookup/email-addresses.curl.md)

## Consultar um lote

Use `POST /v1/lookup/email/batch` para avaliar até 1.000 endereços em uma única solicitação:

```bash
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](/docs/guides/idempotency), 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](/docs/api/reference/create-email-lookup-batch).

## 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](/docs/guides/idempotency).

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`](/docs/api/errors/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`](/docs/api/errors/E22001) | A carteira da organização não tem saldo suficiente para a consulta. Recarregue e tente novamente. Nada foi cobrado.                                                               |
| [`E22002`](/docs/api/errors/E22002) | A consulta está temporariamente indisponível. Tente novamente com backoff. Nada foi cobrado.                                                                                      |

## Próximos passos

- [Consultar um número de telefone](/docs/guides/lookup/phone-numbers) é a outra metade do Lookup.
- [Supressões](/docs/guides/email/suppressions) impedem envios repetidos para endereços que já geraram bounce, sem custo.
- [Referência de API do Lookup](/docs/api/reference/create-email-lookup) documenta todos os campos.
- [Pesquisa de email: esse endereço vai mesmo aceitar mensagens](/learn/lookup/email-lookup-will-that-address-actually-accept-mail) é um vídeo que executa consultas contra um endereço de função, um erro de digitação e um provedor gratuito.

## Related resources

- [What are bounced emails?](/explained/deliverability/what-are-bounced-emails) (answer)
- [Email lookup](/lookup-api) (product)

[Get an implementation brief](/learn/workspace?topic=lookup-email)