邮箱实时检测

POST/v1/realtime/check/email

同步检测一个邮箱地址，最多可同时指定 10 个实时邮箱产品。引擎、计费契约和响应结构与手机号端点完全一致，区别只在系列和标识格式。

请求参数

字段	类型	必填	说明
`identifier`	string	是	一个邮箱地址，例如 `user@example.com`。
`country`	string	否	邮箱必须不传。邮箱产品带国家码会被直接拒绝。
`product_ids`	array<int>	是	实时邮箱产品 ID 数组，1 到 10 个。

怎么选产品

邮箱产品和手机号产品是两个系列，不能放在同一次请求里。请到实时产品列表读取 mode 为 realtime 且系列为邮箱的条目的 id（该页由 GET /v1/products 驱动）。这里填 slug 无效，把手机号产品的 ID 放进邮箱请求同样会被判为系列不匹配。

响应示例

{
  "request_id": "b7d2a1c4-9f3e-4a1b-8c5d-2e6f7a8b9c0d",
  "identifier": "user@example.com",
  "status": "succeeded",
  "request_status": "completed",
  "replayed": false,
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "results": [
    {
      "product_id": 49,
      "product": "insemailvalid-rt",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-13T10:00:00Z",
      "error_code": null
    }
  ]
}

上面的 product_id 只是示例值——真正发请求前，请到实时产品列表确认当前的邮箱产品 ID。request_id 是 UUID，cached 在每条 result 内部，不在顶层。

cURL 示例

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"user@example.com","product_ids":[49]}'

邮箱特有的错误

HTTP	code	含义 / 处理
400	`invalid_realtime_request`	地址格式不合法、传了 `country`、ID 属于另一个系列，或者没给 ID。不会提交，也不扣费。
400	`idempotency_key_required`	缺少 `Idempotency-Key` 请求头。
402	`insufficient_balance`	余额不足以覆盖预扣；任何产品都不会开始。
409	`request_in_progress` / `idempotency_conflict`	相同 Key 仍在执行，或相同 Key 换了请求体。

其余状态码——401、403、429、503、500——与手机号端点的说明完全相同。