BillionVerify 现已在 Vercel Connect 中上线。打开 vercel.com/connect/billionverify，或在 Vercel 控制台的 Connect 中搜索 “BillionVerify”，然后将你的 BillionVerify API 密钥添加到连接器中一次。之后，你链接的任何 Vercel 项目都可以在运行时验证邮箱地址：代码需要密钥时会向 Vercel Connect 请求，因此密钥不会存放在环境变量或源代码中。
BillionVerify Vercel 连接器使用你现有的相同 REST API、额度和验证历史记录。它是我们 Claude 连接器 的 Vercel 对应版本：Claude 用户通过在聊天中提问来验证地址，而 Vercel 开发者则可以从他们部署在 Vercel 上的注册表单、后台任务和 AI 代理中验证地址。
为什么使用 Vercel Connect 进行邮箱验证
大多数团队通过将 API 密钥粘贴到每个项目的环境变量中来添加邮箱验证。项目较少时这样做没有问题，但当你拥有多个项目、预览环境和生产环境，以及几个能够读取这些变量的人员时，问题就会出现。之后轮换密钥，就意味着要找到每一份副本。
Vercel Connect 将密钥移至团队级别的一个位置：
- 一个密钥，多个项目。 你只需在连接器上存储一次 BillionVerify API 密钥。每个链接到它的项目都可以使用该密钥，而且不会保留自己的副本。
- 由你选择谁可以使用它。 连接器只会响应来自你链接到它的项目和环境的令牌请求。请参阅 Vercel 文档中的项目链接。
- 请求都会被记录。 每个连接器都有一个 Observability 标签页，可按项目、环境和主体记录令牌请求。
- 轮换只需编辑一次。 在 BillionVerify 中创建新密钥，更新连接器，所有已链接的项目都会自动获取新密钥。
对于 AI 代理而言，这一点比经典 Web 应用更重要。能够调用工具的代理不应读取其环境中的原始凭据。使用 Vercel Connect 时，代理的代码会在调用 BillionVerify 的瞬间请求密钥，而密钥从不会成为部署的一部分。
如何在 Vercel Connect 中找到 BillionVerify
有两种方式可以进入 BillionVerify Vercel 连接器。两种方式都会进入相同的设置流程。
从公开的 Vercel Connect 目录进入
打开 vercel.com/connect/browse，在搜索框中输入 “billionverify”，或者直接前往 vercel.com/connect/billionverify。该条目会显示连接方式（API 密钥）和简短说明：逐个、批量或通过批量文件上传验证电子邮件地址。
从你的 Vercel 控制台进入
如果你已经登录 Vercel，请在团队的控制台中打开 Connect，在搜索字段中输入 “billionverify”，然后从所有连接器中选择 BillionVerify。当你要设置一个已经部署在 Vercel 上的项目时，这是最快的方式。
如何将 BillionVerify 连接器添加到您的 Vercel 项目
该连接器使用您 BillionVerify 账户中的 API 密钥。如果您还没有账户，请先在 billionverify.com 注册；免费套餐每天使用账户时可获得 20 个额度，每月最多 600 个额度，无需信用卡。
第 1 步：创建 BillionVerify API 密钥
登录并在 BillionVerify 控制面板中打开 API 密钥页面。创建密钥，并为其命名以说明使用位置，例如 "vercel-production"，这样您稍后可以在使用历史记录中识别它。
第 2 步：在 Vercel 中配置连接
在 Vercel Connect 中点击 BillionVerify 以打开“添加连接”，然后填写“配置”步骤：
- 名称。 Vercel 会建议一个随机名称，例如
chestnut-fence。将其替换为您能识别的名称，例如billionverify-prod。该名称与服务名称一起构成代码使用的连接器 ID：billionverify/billionverify-prod。 - UID（可选）。 留空，Vercel 会根据服务名称和连接器名称生成 UID。
- 共享 API 密钥或每用户 API 密钥。 共享 API 密钥会在连接器上存储一个供您应用所有用户使用的密钥。每用户 API 密钥则要求您的每位用户在授权时提供自己的 BillionVerify 密钥。下一节将说明何时选择哪种方式。
- 密钥。 粘贴第 1 步中的 API 密钥。
- 范围和过期时间（可选）。 如果您的团队按计划轮换密钥，请设置过期时间；否则保留默认设置。
点击“创建连接器”进行保存。
第 3 步：关联可能使用它的项目
将连接器关联到应获准进行邮箱验证的 Vercel 项目和环境，例如 Web 应用的生产环境和预览环境，但不要关联到没有理由调用 BillionVerify 的内部工具。未关联的项目会收到错误，而不是获得密钥。
更喜欢使用终端？使用 Vercel CLI
相同的设置也可以通过 Vercel CLI 完成。在将使用该连接器的项目中运行：
vercel link vercel connect create billionverify --name billionverify-prod vercel env pull
vercel env pull 会将一个短期开发令牌下载到 .env.local 中，因此您在自己的计算机上运行应用时，getToken 也能正常工作。该文件保存的是 Vercel 令牌，而不是您的 BillionVerify 密钥。
共享 API 密钥还是按用户 API 密钥？
当由你自己的产品执行验证时，请选择 共享 API 密钥：例如，拒绝一次性地址的注册表单、清理新潜在客户的夜间任务，或团队使用的内部代理。所有验证都会使用你的 BillionVerify 账户和额度。
当你为拥有自己 BillionVerify 账户的其他用户构建产品时，请选择 按用户 API 密钥：例如 CRM 插件、冷邮件工具或代理模板。每位用户在授权期间提供自己的密钥，因此他们的验证会使用自己的额度，并显示在各自的 BillionVerify 历史记录中。
从你的代码中调用 BillionVerify
在你的项目中安装 Vercel Connect SDK：
npm install @vercel/connect
然后使用 getToken 请求密钥，并将其放入 BV-API-KEY 请求头中。下面是一个使用实时 SMTP 检查单个地址的 Next.js 路由处理程序：
// app/api/verify-email/route.ts
import { getToken } from '@vercel/connect';
export async function POST(req: Request) {
const { email } = await req.json();
const apiKey = await getToken('billionverify/billionverify-prod', {
subject: { type: 'app' },
});
const res = await fetch('https://api.billionverify.com/v1/verify/single', {
method: 'POST',
headers: { 'BV-API-KEY': apiKey, 'Content-Type': 'application/json' },
body: JSON.stringify({ email, check_smtp: true }),
});
const body = await res.json();
return Response.json(body.data);
}
响应中的 data 对象包含 status（valid、invalid、catchall、role、disposable 或 unknown）、is_deliverable、is_disposable、is_catchall、is_role 以及 reason。注册表单通常会阻止无效地址和一次性地址，接受有效地址，并允许 catch-all 和 unknown 地址通过，同时添加标记，以便你观察它们的表现。
SDK 会将密钥缓存在内存中并重复使用，因此不会在你验证每个地址时都再次调用 Vercel Connect。
验证批量地址或整个文件
同一个密钥适用于每个 BillionVerify 端点：
POST /v1/verify/single验证一个地址，如上所示。POST /v1/verify/bulk在一次请求中验证最多 50 个地址。发送{"emails": [...], "check_smtp": true}。POST /v1/verify/file上传 CSV 以创建后台任务。轮询GET /v1/verify/file/{id}，并从GET /v1/verify/file/{id}/results下载结果。
在 Vercel 上，一种常见做法是使用 cron 任务收集当天新增的潜在客户，将其按每组 50 个地址发送到 /v1/verify/bulk，然后把状态写回数据库。请求和响应详情请参阅 API 参考。
代码中的每用户密钥
使用 Per-User API Keys 时，将已登录用户的 ID 作为 subject 传递：
const apiKey = await getToken('billionverify/billionverify-prod', {
subject: { type: 'user', id: session.user.id },
});
如果该用户尚未提供密钥，SDK 会抛出 UserAuthorizationRequiredError。捕获此错误，并在 UI 中显示“连接你的 BillionVerify 账户”的步骤。其他错误类别列在 Vercel 的 令牌文档中。
在 Vercel 的 AI 智能代理中使用 BillionVerify
如果你在 Vercel 上构建智能代理，请为其提供一个“验证邮箱”工具，让工具代码调用 getToken，然后调用 BillionVerify，完全按照上面的路由处理程序实现。模型会决定何时验证地址；密钥保留在 Vercel Connect 中，绝不会出现在提示词、工具输出或智能代理的环境中。
同一个 API 密钥还支持我们的其他智能代理集成：
- MCP 服务器。
BILLIONVERIFY_API_KEY=your-key npx billionverify-mcp可在本地运行我们的 MCP 服务器，提供与托管版本相同的 11 个工具。每个客户端的设置方法请参阅 MCP 指南。 - 智能代理技能。 编程智能代理可以使用
npx skills add BillionVerify/billionverify-skill安装 BillionVerify 技能。更多信息请参阅 智能代理技能。
Credits 的工作原理
通过 Vercel 连接器进行验证的费用与在 BillionVerify 中其他位置进行验证相同：获得明确结果需消耗 1 个 credit。未知、一次性和格式错误的地址免费，并且在 24 小时内再次检查同一地址也免费。Catch-all 地址会被报告为 catch-all，不会计入有效地址，因此由你决定如何处理。
Vercel 会根据 Vercel Connect 定价 单独收取其自身 token 请求的费用。由于 SDK 会缓存密钥，通常 1 次 token 请求即可支持多次验证。
BillionVerify 也已接入 Claude
本月早些时候，BillionVerify 被列入 Claude 的连接器目录。如果你或你的团队使用 Claude，可以将 BillionVerify 连接到你的账户，无需 API 密钥，并在聊天中请求 Claude 验证一个地址，或清理最多 50 个地址的列表。阅读 BillionVerify 现已进入 Claude 连接器目录 了解设置方法。
Claude 适合在工作过程中检查地址。Vercel 连接器则用于运行在你自己的应用和代理中的检查。
常见问题
什么是 BillionVerify Vercel 连接器？
它是 BillionVerify 在 Vercel Connect 中的条目。你只需在连接器中存储一次 BillionVerify API 密钥，与其关联的 Vercel 项目即可在运行时请求该密钥，以调用 BillionVerify 邮箱验证 API。
我还需要将 API 密钥放入环境变量吗？
不需要。密钥存储在连接器中。你的代码通过 @vercel/connect 中的 getToken 获取密钥，该方法会自动对你的部署进行身份验证，使其连接到 Vercel Connect。
通过 Vercel 验证邮箱需要额外付费吗？
BillionVerify 不会额外收费。验证使用你 BillionVerify 账户中的额度，并按正常费率扣费。Vercel 会根据其 Vercel Connect 定价，对自身的令牌请求收费。
我应该选择 Shared API Keys 还是 Per-User API Keys？
当你使用自己的账户验证地址时，选择 Shared API Keys。当你构建的产品中每位用户都有自己的 BillionVerify 账户，并且应为自己的验证付费时，选择 Per-User API Keys。
我可以在 Vercel 部署之外使用该连接器吗？
可以。在本地开发时，vercel env pull 会为你提供开发令牌。在其他环境中，例如外部 CI，你可以通过 vercelToken 选项将 Vercel 访问令牌传递给 getToken。你也可以直接使用自己的密钥调用 BillionVerify API，而无需使用 Vercel Connect。
Vercel 连接器是否支持托管 MCP 服务器？
位于 mcp.billionverify.com 的托管 MCP 服务器通过 OAuth 为你登录，这正是 Claude 连接器所使用的方式。Vercel 连接器持有 API 密钥，可与 REST API、billionverify-mcp npm 软件包和代理技能配合使用。
在 Vercel Connect 中添加 BillionVerify
打开 vercel.com/connect/billionverify，粘贴你的 BillionVerify API 密钥，关联你的项目，并在下一个注册或潜在客户进入你的列表之前验证其邮箱。