查询电子邮件地址

一次调用即可告诉你某个地址是否接受邮件。在注册时或处理潜在客户之前使用它，从一开始就将会退信的地址排除在发送列表之外。本页所有操作都需要具有 lookup 权限的 API 密钥。

查询地址

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.com

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

批量查询

使用 POST /v1/lookup/email/batch 在一次请求中评估最多 1,000 个地址：

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

响应中的 data 数组按提交顺序为每个输入包含一条评估结果。格式错误的地址会收到各自独立的评估。重复地址作为单独条目保留，每条已应答的条目都会计费。前后空白会被去除，大小写保持原样。

每个请求不超过 128 KiB。较大的列表请拆分为多个批次。如果启用了幂等重试，请为每个批次使用不同的密钥。不超过 256 KiB 的响应可以保留用于重放；更大的响应在返回时不带重放保护，因此重试可能会执行并计费另一个批次。参见批量 API 参考。

如何填写地址

发送裸地址，与你存储的完全一致。单地址查询会拒绝带显示名称的格式（如 Aisha <aisha@example.com>），而不会自动解包。批量查询会为每个提交的字符串返回一条评估结果。

@ 之前的部分按原样传递而不会被转为小写，email 字段会保留该大小写。批量响应会去除前后空白；请按相同位置将每条结果与输入对应。发送地址时保持你存储的大小写，不要先做标准化：result 通常两种写法结果相同，但 delivery_confidence 不一定一致，因此改变大小写可能改变你得到的结果。

五种判定结果

result 是用于决策的字段。

valid：地址存在且可接收邮件。可以发送。

neutral：无法确认结果，通常是因为接收域对所有收件人返回相同的应答。发送是合理的；中性地址不是坏地址，只是无法判定的地址。

risky：地址可能接收邮件，但比大多数地址更容易退信或投诉。角色地址、一次性地址和低信誉地址归入此类。是否发送取决于你对投诉的容忍度，flags 会告诉你具体是哪种风险。

undeliverable：地址不接收邮件。不要发送。reason 说明原因：invalid_syntax 表示地址格式错误，invalid_domain 表示该域完全不接收邮件，invalid_recipient 表示域可以接收邮件但此邮箱不存在。

typo：地址疑似拼写错误，did_you_mean 包含修正建议。将修正建议展示给输入原始地址的人，而不是直接向修正后的地址发送邮件：这只是一种猜测，他们想要的地址可能两者都不是。

result 是一个开放词汇表，因此你不认识的值是未来新增的判定结果，而非错误。对已知的值进行分支处理，对未知的值回退到 delivery_confidence，该字段始终存在且始终可比较。

将置信度与判定结果一起参考，而非取而代之

delivery_confidence 的范围从 0（确定无法投递）到 100（确定可以投递）。相同的分数可能因为不同的原因出现在 neutral 或 risky 下，因此它是第二意见而非 result 的替代。当你需要跨所有判定结果（包括未来新增的判定结果）使用统一阈值时，它是可以依赖的字段。

valid 携带提供商的有效性评估。即使域可以接收邮件，无效收件人也可能具有 valid: false。在决定是否发送时，将 result 和 delivery_confidence 结合使用；valid: true 不能保证投递成功。

标记描述地址类型

flags 在没有值得注意的特征时为空。目前定义了三个值，且这是一个开放列表。

role 表示地址指向一个职能而非个人，例如 support@ 或 info@。回复和授权同意是不明确的，投诉的可能性更高。

disposable 表示地址属于一次性邮箱提供商，通常会很快失效。

free_provider 表示地址属于消费者邮箱提供商，例如 Gmail 或 Outlook.com。对于消费者邮件来说这很正常，只有在你期望的是企业地址时才是一个信号。

重试而不重复付费

每个已应答的地址都会计费，包括 undeliverable，因为这就是你付费获得的结果以及你避免的退信。发送 Idempotency-Key，这样重试会重放已存储的判定结果，而不是再次购买。参阅幂等性。

GET 形式将地址放在 URL 中，无法携带幂等键。对于任何自动化场景，请使用 POST 形式。

错误

后续步骤

• 查询电话号码是 Lookup 的另一半功能。
• Suppressions 可以免费阻止向已退信的地址重复发送。
• Lookup API 参考文档记录了所有字段。
• 邮箱查询：该地址是否真的能接收邮件是一段视频，演示了对角色地址、拼写错误地址和免费邮箱提供商的查询。