一次 API 验证费用多少？

一次成功的 POST /verify 恰好使用 1 credit。GET 请求（余额、历史）免费。积分永不过期 — 按需购买。

可以多次验证同一邮箱吗？

可以。每次 API /verify 调用使用 1 credit，即使同一地址。计费可预测且与实际用量一致。

如何生成 API 密钥？

创建账户，打开 API tokens (/account/api)，点击「New token」并复制 ev_live_… 或 ev_test_… (sandbox) secret。完整密钥仅显示一次。

API 是否支持批量邮箱验证？

支持。POST /bulk 最多接受 50,000 个地址。N 封邮件消耗 N 积分。通过 GET /bulk/:id 跟踪进度并下载 CSV 结果。

valid、invalid 和 risky 是什么意思？

valid — 可发送；invalid — 移除；risky — disposable 或 role account；catch_all — 域名接受所有地址。见状态章节。

是否有每分钟请求限制？

默认每个 API 密钥 60 请求/分钟。429 响应返回 error: rate_limit_exceeded。重试 POST /verify 时使用 Idempotency-Key。

完整 OpenAPI 规范在哪里？

在 /api/v1/openapi.yaml 下载 openapi-v1.yaml，或使用 /zh/dokumentacja-api/reference 的交互式 Redoc。

开发者中心 · REST API v1

邮箱地址验证 API

以编程方式验证邮件列表 — 更少退信，更高送达率

将注册表单、CRM 和落地页连接到 EmailVerifier。通过 REST API 实时或批量验证邮箱 — 透明计费 1 request = 1 credit。

实时验证
批量最多 50,000 封邮件
1 次请求 = 1 积分

生成 API 密钥创建账户 OpenAPI / Redoc

请求示例

curl -X POST https://propercheck.pl/api/v1/verify \
  -H "Authorization: Bearer ev_live_…" \
  -d '{"email":"user@company.com"}'

API 知识库

选择主题 — 从认证和积分到批量任务、webhooks 和错误码。

API邮箱验证 API

POST /verify — 单个地址，亚秒级结果，valid/invalid/risky 状态。

了解更多

API批量邮箱验证

批量验证 CSV 列表 — 任务队列、进度轮询和 CSV 导出。

了解更多

API积分与计费

余额、API 用量、1 credit = 1 次验证、HTTP 402 处理。

了解更多

APIAPI 密钥与认证

Bearer ev_live_、令牌面板、安全存储最佳实践。

了解更多

APIWebhooks 与集成

verification.completed、HMAC 签名、CRM 和营销自动化。

了解更多

APIOpenAPI 参考

完整 YAML 规范、Redoc UI 和 HTTP 错误目录。

了解更多

什么是邮箱验证 API？

在发送营销活动前验证地址的 REST 接口。

邮箱验证 API 检查地址是否存在、域名是否接收邮件、邮箱是否为 disposable 或 catch-all。您降低退信率、保护发件人声誉并改善收件箱送达。

API 通过 HTTPS 在 /api/v1 提供服务。使用 Bearer 密钥 (ev_live_…) 或面板会话认证。每次成功的 POST /verify 消耗一个 credit — 无订阅，GET 请求无隐藏费用。

何时使用邮箱验证 API

B2B 产品和营销栈中的常见集成场景。

注册表单

注册时实时验证邮箱 — 在写入列表前拒绝 invalid 和 disposable。

CRM 与潜客捕获

清理落地页和 webhook 的潜客 — 仅可投递地址进入 pipeline。

活动前的列表清洗

Newsletter 发送前使用 Bulk API — 更少退信、更高打开率、更低 ESP 成本。

SaaS 平台

在产品中嵌入邮箱检查 — 基于 credit 的计费简化客户定价。

API 积分模型

简单定价：一次验证请求 = 一个 credit。

POST /verify 对每个成功请求 (HTTP 200) 使用 ev_live_ 密钥收取 1 credit，即使同一地址曾通过 API 验证过。Sandbox 密钥 (ev_test_) 返回 mock 结果且不扣积分。
GET 操作 — 余额、历史、批量任务状态、CSV 导出 — 免费。
余额不足返回 HTTP 402 (insufficient_credits)。引擎错误 (503) 不扣 credit。

认证与 API 密钥

通过 Authorization 头安全访问。

登录面板并打开 API tokens (/account/api)。
在面板创建生产密钥 (ev_live_) 或 sandbox 测试密钥 (ev_test_) — 完整 secret 仅显示一次。
以 Authorization: Bearer ev_live_… 发送密钥 — 切勿放在 URL 或客户端代码中。

Authorization: Bearer ev_live_YOUR_API_KEY
Content-Type: application/json

快速开始 — 邮箱验证 API

两次调用：余额检查和首次验证。

1. 检查积分余额

curl https://propercheck.pl/api/v1/credits \
  -H "Authorization: Bearer ev_live_YOUR_KEY"

2. 验证单个邮箱地址

curl -X POST https://propercheck.pl/api/v1/verify \
  -H "Authorization: Bearer ev_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"john@company.com"}'

单条验证（实时）

POST /api/v1/verify 接受带 email 字段的 JSON。响应包含 status、score 0–100、provider (Google, Microsoft, 区域主机) 和 enrichment (MX, catch-all)。

POST /api/v1/verify

JSON 响应结构

成功验证后返回的字段。

{
  "verificationId": "ver_abc123",
  "email": "john@company.com",
  "status": "valid",
  "score": 92,
  "provider": "google",
  "enrichment": { "mxRecords": ["aspmx.l.google.com"], "catchAll": false },
  "creditsRemaining": 149
}

邮箱验证状态

API、面板和 CSV 导出中使用的分类。

valid

valid — 地址存在且可接收邮件；可安全发送。

invalid

invalid — 地址不存在或域名无邮件；从列表移除。

risky

risky — 低置信度（如 disposable、role account）；活动中需谨慎。

catch_all

catch_all — 服务器接受域名上所有地址；退信风险更高。

unknown

unknown — SMTP 响应不确定；可考虑稍后重新验证。

REST 端点参考

完整 API v1 路径列表及 credit 成本。

方法	路径	积分	说明
POST	/verify	1	实时单条邮箱验证
GET	/verify/:id	0	按 verificationId 获取结果
GET	/verifications	0	验证历史和 30 天统计
GET	/credits	0	当前账户积分余额
POST	/bulk	N	创建批量任务 (N 积分)
GET	/bulk/:id	0	批量任务状态和进度
GET	/bulk/:id/export	0	下载 CSV 结果
GET/POST/PATCH/DELETE	/api-keys	0	API 令牌管理（会话）
GET/POST/DELETE	/webhooks	0	Webhook 配置（会话）
GET	/usage	0	API 和积分使用统计

批量邮件验证 API

在一个任务中验证数千地址 — 适合大型活动前使用。

POST /bulk 带 emails 数组或 CSV 文本 — 为 N 个唯一地址预留积分。
GET /bulk/:id — 轮询状态 (queued → processing → completed)。
GET /bulk/:id/export — 下载含 email、status、score、provider 列的 CSV。

curl -X POST https://propercheck.pl/api/v1/bulk \
  -H "Authorization: Bearer ev_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["a@b.co","c@d.co"]}'

Webhook — verification.completed

验证完成时向您的 URL 发送 POST。Header X-EV-Signature 包含 body 的 HMAC-SHA256 — 处理前请验证签名。

X-EV-Event: verification.completed
X-EV-Signature: <hmac-sha256 of body>

速率限制

默认每个 API 密钥每分钟 60 次请求。超出返回 HTTP 429 及 rate_limit_exceeded。限制按密钥 — 每个集成使用独立令牌。

POST /verify 的可选头 — 相同键安全重试，24h TTL 内不重复扣 credit。

X-Request-Id

每个 API 响应包含 X-Request-Id — 联系支持调试集成时请提供。

HTTP 错误码

HTTP	代码	说明
401	unauthorized	请求中缺少会话或 API 密钥。
401	invalid_api_key	API 密钥无效、过期或已撤销。
400	invalid_request	JSON 无效、缺少 email 字段或地址格式错误。
402	insufficient_credits	积分不足 — 在 /account/credits 充值。
429	rate_limit_exceeded	超出速率限制 — 默认每个 API 密钥 60 请求/分钟。
503	engine_unavailable	验证引擎不可用 — 不扣 credit。

集成示例

常用语言中的相同验证流程。

curl -X POST https://propercheck.pl/api/v1/verify \
  -H "Authorization: Bearer ev_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"john@company.com"}'

FAQ — 邮箱验证 API

开发者和营销人员的常见问题。

OpenAPI 3.1 与 Redoc

机器可读规范，用于 codegen、契约测试和 CI 流水线。

下载 openapi-v1.yaml 交互式 Redoc 参考

开始通过 API 验证邮箱

注册即送试用积分。一分钟内在面板获取 API 密钥。

创建账户 API 令牌

在账户面板生成密钥。