# VeriMails API Documentation

Base URL: `https://verimails.com`

VeriMails provides email verification, bulk CSV verification, and Email Finder endpoints. The API is designed for teams that need to verify addresses before signup, import, enrichment, CRM sync, or outbound sending.

## Authentication

Send an API key as a Bearer token:

```http
Authorization: Bearer YOUR_API_KEY
```

Public documentation does not require an account. API requests require a valid key and sufficient credits.

## Credits

- Single verification: 1 credit per submitted email address.
- Batch verification: 1 credit per submitted email address.
- Bulk CSV verification: 1 credit is reserved for each address when the job is created.
- Email Finder: 10 credits are charged only when a verified email is found.
- New accounts receive 100 signup credits. Prepaid credits never expire.

## Verify One Email

```bash
curl -X POST https://verimails.com/api/verify/single \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com"}'
```

Response:

```json
{
  "email": "person@example.com",
  "safe_to_send": true,
  "status": "valid",
  "confidence_score": 0.95,
  "reason": "Verification completed",
  "domain": "example.com",
  "is_disposable": false,
  "is_role_based": false,
  "is_free": false,
  "is_catch_all": false,
  "mx_records": ["mx1.example.com"],
  "smtp_response": null,
  "verification_time_ms": 642,
  "api_version": "1.0"
}
```

`safe_to_send` is `true` only when the returned status is `valid`.

## Verify a Small Batch

```bash
curl -X POST https://verimails.com/api/verify/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["person@example.com","team@example.com"]}'
```

The batch endpoint accepts up to 500 addresses per request.

## Bulk Verification CSV

Upload a CSV and optionally provide `email_column` when your email field is not named `email`.

```bash
curl -X POST https://verimails.com/api/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@leads.csv" \
  -F "email_column=Email Address"
```

Supported automatic email headers include `email`, `Email`, `Email Address`, `emails`, `work_email`, `business_email`, and `contact_email`. Headerless one-column CSV files are also supported.

Poll the job:

```bash
curl https://verimails.com/api/bulk/123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Download results:

```bash
curl https://verimails.com/api/bulk/123/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o results.csv
```

The full results download preserves the original CSV columns and appends `Safe to Send` with `Yes` or `No`.

## Email Finder

The finder requires first name, last name, and company domain. It returns a verified person-level email when one can be confirmed.

```bash
curl -X POST https://verimails.com/api/find-email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jane","last_name":"Doe","domain":"example.com"}'
```

Success response:

```json
{
  "found": true,
  "email": "jane.doe@example.com",
  "status": "found",
  "confidence": 0.95,
  "elapsed_ms": 812,
  "credits_used": 10
}
```

No verified hit:

```json
{
  "found": false,
  "email": null,
  "status": "not_found",
  "confidence": 0,
  "elapsed_ms": 4300,
  "credits_used": 0
}
```

## Finder CSV

```bash
curl -X POST https://verimails.com/api/find-email/csv \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@people.csv" \
  -F "first_name_column=First Name" \
  -F "last_name_column=Last Name" \
  -F "domain_column=Company Domain"
```

Poll and download:

```bash
curl https://verimails.com/api/find-email/csv/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://verimails.com/api/find-email/csv/JOB_ID/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o finder_results.csv
```

## Errors

- `401`: missing or invalid authentication.
- `402`: insufficient credits.
- `403`: access denied or feature unavailable for the account.
- `409`: job exists but is not complete yet.
- `422`: invalid request body or missing required field.
- `429`: rate limit exceeded.