# Lookup 概述 Lookup 在你发送消息之前回答关于收件人的问题。给它一个电话号码，它会告诉你这个号码的信息：当前服务网络、所属国家、是否曾经转网，以及线路类型。给它一个电子邮件地址，它会告诉你这个地址是否值得发送。 两者都是一次请求、一次应答。无需创建任何资源，无需轮询，事后也无需清理。控制台中的 [**Lookup**](https://bird.com/dashboard/w/lookup) 页面可以逐条运行这两种操作，这是在编写任何代码之前查看应答格式的最快方式。 ## 每次查询的费用 每次查询都从你的组织钱包中扣费，这是在基于它进行开发之前值得了解的部分。 电话号码查询始终会对基础查询计费一次。在此基础上，你可以请求**属性**，即来自付费数据源的额外信息。你请求的每个属性单独计费，但**仅在成功返回时才收费**。无法回答的属性会返回一个说明状态，不产生任何费用。 电子邮件地址查询按每个已回答的地址计费一次。每个判定结果都会计费，包括 `undeliverable`：这就是你请求的答案，也是帮你避免退信的答案。 查询失败时不收取任何费用。格式错误的号码、被拒绝的地址或无法连接的数据源都不产生费用。 [Lookup 定价](/products/lookup/pricing)列出了基础查询、每个属性以及电子邮件地址查询的费率。 ## 号码查询分为两个层级 这种分层是电话号码查询的核心设计，值得明确说明。 **基础查询**始终执行。它回答当前服务网络、号码发放网络、所属国家、号码是否曾经转网，以及粗略的 `line_type`（移动、固定电话、VoIP、免费电话等）。如果基础查询无法回答，整个请求会失败，而不是返回一个需要你检查才能发现为空的半空应答。 **属性**是你在基础查询之上添加的内容，通过在 `type` 中指定属性名称来请求。它们回答更精细的问题：号段的精确分配业务、完整的携号转网记录、号码当前是否在网、是否在漫游、SIM 卡最近一次更换时间，以及可信度评分。无法回答的属性不会导致请求失败，而是降级为一个状态值，基础查询仍然正常返回。 ## 只有 `ok` 携带值，也只有 `ok` 会被计费 每个属性块都有一个 `status`，读取它不是可选的。 `ok` 表示属性已回答，值在响应中，且已计费。 `unavailable` 表示没有收到应答，因此该属性不包含任何内容，不计费。 `inconclusive` 表示收到了应答但未能解析该属性：号码不在其背后数据的覆盖范围内，或者数据源返回了该属性不报告的值。这是一个真实的发现而非缺失，同样不计费。 `status` 是一个开放词汇表，将来可能会添加更多值。基于 `ok` 进行分支判断，将其他所有值视为 "not answered"，你的代码无论怎样扩展都能保持正确。 ## 在 Lookup 与发送时验证之间做选择 Lookup 用于在你提交**之前**逐个收件人地做出决策：在注册时检查号码或地址、在操作之前筛选线索，或根据线路类型以不同方式路由消息。它按每次检查收费，并给你一个可以据此行动的答案。 如果你只是想停止向已经退信或投诉过的地址发送消息，则不需要 Lookup。[屏蔽列表](/docs/guides/email/suppressions)会自动且免费地完成这项工作。 两种操作都没有批量形式，`lookup` [请求速率限制](/docs/guides/rate-limits)起始为每个凭证每分钟 10 次请求，因此目前不适合用来检查整个列表。如果你有这方面的需求，请联系我们提高限额。 ## 后续步骤 - [查询电话号码](/docs/guides/lookup/phone-numbers)涵盖基础查询、每个属性及各自的返回内容。 - [查询电子邮件地址](/docs/guides/lookup/email-addresses)涵盖判定结果以及如何处理每种结果。 - [Lookup API 参考](/docs/api/reference/create-phone-number-lookup)记录了每个字段。 - [幂等性](/docs/guides/idempotency)说明如何重试查询而不被重复收费。 ## Related resources - [Phone number lookup: check a number before you send](/learn/lookup/phone-number-lookup-check-a-number-before-you-send) (video) - [Lookup](/lookup-api) (product) [Get an implementation brief](/learn/workspace?topic=lookup)