Billionverify Skill

Verify email addresses using the BillionVerify API. Use when user wants to verify single emails, batch verify email lists, upload files for bulk verification, check credit balance, or manage webhooks.

BillionVerify API Skill

Call the BillionVerify API to verify email addresses — single, batch, or bulk file processing.

Setup

API key must be set in environment variable BILLIONVERIFY_API_KEY. Get your API key at: https://billionverify.com/auth/sign-in?next=/home/api-keys

Base URL

text

https://api.billionverify.com

Authentication

All requests require an API key header:

bash

-H "BV-API-KEY: $BILLIONVERIFY_API_KEY"

Endpoints

Verify Single Email

bash

curl -X POST "https://api.billionverify.com/v1/verify/single" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "check_smtp": true
  }'

Response includes: status (valid/invalid/unknown/risky/disposable/catchall/role), score (0-1), is_deliverable, is_disposable, is_catchall, is_role, is_free, domain, domain_age, mx_records, domain_reputation, smtp_check, reason, suggestion, response_time, credits_used.

Verify Batch Emails (max 50)

bash

curl -X POST "https://api.billionverify.com/v1/verify/bulk" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["[e-mail]", "[e-mail]"],
    "check_smtp": true
  }'

Upload File for Bulk Verification

Upload CSV, Excel (.xlsx/.xls), or TXT files (max 20MB, 100,000 emails):

bash

curl -X POST "https://api.billionverify.com/v1/verify/file" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \
  -F "file=@/path/to/emails.csv" \
  -F "check_smtp=true" \
  -F "email_column=email" \
  -F "preserve_original=true"

Returns task_id for tracking the async job.

Get File Job Status

Supports long-polling with timeout parameter (0-300 seconds):

bash

curl -X GET "https://api.billionverify.com/v1/verify/file/{task_id}?timeout=30" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY"

Status values: pending, processing, completed, failed.

Download Verification Results

Without filters returns redirect to full result file. With filters returns CSV of matching emails (filters combined with OR logic):

bash

curl -X GET "https://api.billionverify.com/v1/verify/file/{task_id}/results?valid=true&invalid=true" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \
  -L -o results.csv

Filter parameters: valid, invalid, catchall, role, unknown, disposable, risky.

Get Credit Balance

bash

curl -X GET "https://api.billionverify.com/v1/credits" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY"

Create Webhook

bash

curl -X POST "https://api.billionverify.com/v1/webhooks" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/billionverify",
    "events": ["file.completed", "file.failed"]
  }'

The secret is only returned on creation — store it securely.

List Webhooks

bash

curl -X GET "https://api.billionverify.com/v1/webhooks" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY"

Delete Webhook

bash

curl -X DELETE "https://api.billionverify.com/v1/webhooks/{webhook_id}" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY"

Health Check (no auth required)

bash

curl -X GET "https://api.billionverify.com/health"

Credits & Billing

• Invalid / Unknown: 0 credits (free)
• All other statuses (valid, risky, disposable, catchall, role): 1 credit each

Rate Limits

Endpoint	Limit
Single Verification	6,000/min
Batch Verification	1,500/min
File Upload	300/min
Other endpoints	200/min

User Request

$ARGUMENTS