# 查询电子邮件地址

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

## 查询地址

**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](/zh-sg/wendang/guides/lookup/email-addresses.ts.md) · [Python](/zh-sg/wendang/guides/lookup/email-addresses.py.md) · [Go](/zh-sg/wendang/guides/lookup/email-addresses.go.md) · [PHP](/zh-sg/wendang/guides/lookup/email-addresses.php.md) · [CLI](/zh-sg/wendang/guides/lookup/email-addresses.cli.md) · [MCP](/zh-sg/wendang/guides/lookup/email-addresses.mcp.md) · [cURL](/zh-sg/wendang/guides/lookup/email-addresses.curl.md)

## 批量查询

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

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

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

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

## 如何填写地址

发送裸地址，与你存储的完全一致。单地址查询会拒绝带显示名称的格式（如 `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`，这样重试会重放已存储的判定结果，而不是再次购买。参阅[幂等性](/docs/guides/idempotency)。

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

## 错误

| 状态码                              | 说明                                                                                               |
| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`E22003`](/docs/api/errors/E22003) | 单地址查询收到了无效的电子邮件地址。不会计费。批量查询会单独评估格式错误的字符串并对这些评估计费。 |
| [`E22001`](/docs/api/errors/E22001) | 组织的钱包余额不足以支付此次查询。请充值后重试。不会计费。                                         |
| [`E22002`](/docs/api/errors/E22002) | 查询服务暂时不可用。请使用退避策略重试。不会计费。                                                 |

## 后续步骤

- [查询电话号码](/docs/guides/lookup/phone-numbers)是 Lookup 的另一半功能。
- [Suppressions](/docs/guides/email/suppressions) 可以免费阻止向已退信的地址重复发送。
- [Lookup API 参考文档](/docs/api/reference/create-email-lookup)记录了所有字段。
- [邮箱查询：该地址是否真的能接收邮件](/learn/lookup/email-lookup-will-that-address-actually-accept-mail)是一段视频，演示了对角色地址、拼写错误地址和免费邮箱提供商的查询。

## 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)