Visão geral do Lookup

O Lookup responde perguntas sobre um destinatário antes de você enviar uma mensagem. Forneça um número de telefone e ele informa o que o número é: a rede que o atende, o país, se ele mudou de rede e que tipo de linha é. Forneça um endereço de e-mail e ele informa se vale a pena enviar para aquele endereço.

São uma solicitação e uma resposta. Não há nada para criar, nada para consultar e nada para limpar depois. A página Lookup no dashboard executa as mesmas duas operações uma por vez, que é a forma mais rápida de ver como uma resposta se apresenta antes de você escrever qualquer código.

Quanto custa cada lookup

Cada lookup é cobrado da carteira da sua organização, e essa é a parte que vale a pena entender antes de construir algo em cima disso.

Um lookup de número de telefone sempre cobra uma vez pela consulta base. Além disso, você pode solicitar propriedades, dados extras que vêm de uma fonte de dados paga. Cada propriedade solicitada é cobrada separadamente, mas somente quando é entregue. Uma propriedade que não pôde ser respondida retorna com um status indicando isso e não custa nada.

Um lookup de endereço de e-mail cobra uma vez por endereço respondido. Todos os vereditos são cobrados, incluindo undeliverable: essa é a resposta que você pediu, e é a que evita um bounce.

Nada é cobrado quando um lookup falha. Um número malformado, um endereço que recusamos ou uma fonte de dados inacessível não custam nada.

Preços do Lookup lista a tarifa da consulta base, de cada propriedade e de um lookup de endereço de e-mail.

O lookup de número tem duas camadas

Essa divisão é todo o design do lookup de número de telefone, então vale a pena ser explícito sobre ela.

A consulta base sempre é executada. Ela responde a rede que atende o número, a rede que emitiu o número, o país, se o número já mudou de rede e um line_type genérico (móvel, linha fixa, VoIP, toll-free etc.). Se a consulta base não puder ser respondida, a solicitação inteira falha em vez de retornar uma resposta incompleta que você teria que inspecionar para descobrir que estava vazia.

Propriedades são o que você adiciona por cima, nomeando-as em type. Elas respondem perguntas mais detalhadas: o serviço alocado exato da faixa, o registro completo de portabilidade, se o número está ativo na rede neste momento, se está em roaming, quando o SIM foi trocado pela última vez e uma pontuação de credibilidade. Uma propriedade que não pode ser respondida nunca faz a solicitação falhar. Ela degrada para um status, e a consulta base ainda é entregue.

Somente ok carrega um valor, e somente ok é cobrado

Todo bloco de propriedade tem um status, e lê-lo não é opcional.

ok significa que a propriedade foi respondida, seu valor está na resposta e foi cobrada.

unavailable significa que nenhuma resposta chegou, então a propriedade não adiciona nada. Não foi cobrada.

inconclusive significa que uma resposta chegou, mas não resolve a propriedade: o número está fora da cobertura dos dados por trás dela, ou a fonte retornou um valor que essa propriedade não reporta. É uma constatação real, não uma ausência, e também não foi cobrada.

status é um vocabulário aberto, então mais valores podem ser adicionados. Faça branch em ok e trate todo o resto como "not answered", e seu código se mantém correto independentemente de como ele crescer.

Escolhendo entre Lookup e validar no envio

O Lookup serve para decidir antes de você se comprometer, um destinatário por vez: verificar um número ou endereço no cadastro, filtrar um lead antes de agir sobre ele ou rotear uma mensagem de forma diferente dependendo do tipo de linha. Custa dinheiro por verificação e fornece uma resposta sobre a qual você pode agir.

Se você só quer parar de enviar para endereços que já deram bounce ou reclamaram, não precisa do Lookup. Supressões fazem isso automaticamente e de graça.

Nenhuma das operações tem forma em lote, e o limite de requisições do lookup começa em 10 solicitações por minuto por credencial, então verificar uma lista inteira não é para o que isso foi dimensionado hoje. Fale conosco sobre aumentar o limite se é disso que você precisa.

Próximos passos

• Consultar um número de telefone cobre a consulta base, cada propriedade e o que cada uma retorna.
• Consultar um endereço de e-mail cobre os vereditos e o que fazer com cada um.
• Referência API do Lookup documenta todos os campos.
• Idempotência explica como tentar novamente um lookup sem pagar por ele duas vezes.