billionverify

# BillionVerify API Skill

Call the [BillionVerify](https://billionverify.com/) 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

```
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": "user@example.com",
    "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": ["user1@example.com", "user2@example.com"],
    "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`, `comple...

# BillionVerify Skill

An Agent Skill for verifying email addresses using the [BillionVerify API](https://billionverify.com/).

## Overview

This skill enables AI agents to verify email addresses — single verification, batch verification, bulk file processing, credit management, and webhook configuration — through the BillionVerify API.

## Installation

Install this skill using the `skills` CLI:

```bash
npx skills add BillionVerify/billionverify-skill
```

Or install to specific agents:

```bash
npx skills add BillionVerify/billionverify-skill -a cursor -a claude-code
```

## Setup

Before using this skill, you need to:

1. Get your BillionVerify API key from [https://billionverify.com/auth/sign-in?next=/home/api-keys](https://billionverify.com/auth/sign-in?next=/home/api-keys)
2. Set it as an environment variable:

```bash
export BILLIONVERIFY_API_KEY=your_api_key_here
```

## Usage Examples

Once installed, your AI agent can use this skill to:

### Verify a single email

```
Verify the email address user@example.com
```

### Batch verify multiple emails

```
Verify these emails: alice@gmail.com, bob@company.com, test@tempmail.org
```

### Upload a file for bulk verification

```
Upload emails.csv and verify all the email addresses in it
```

### Check credit balance

```
How many verification credits do I have left?
```

### Download filtered results

```
Download only the valid and risky emails from job task_abc123
```

### Manage webhooks

```
Create a webhook to notify https://myapp.com/hook when file verification completes
```

```
List all my webhooks
```

## Features

- Verify single email addresses in real-time
- Batch verify up to 50 emails per request
- Upload CSV/Excel/TXT files for bulk verification (up to 100,000 emails)
- Track async file verification job status with long-polling
- Download filtered results by verification status
- Check credit balance and usage
- Create, list, and delete webhooks for file completion events
- Health check endpoint...