# VeriMails API Docs

VeriMails provides REST API endpoints for email verification, bulk CSV verification, and Email Finder workflows.

## Start Here
- [Quick Start](https://verimails.com/docs/quickstart)
- [Authentication](https://verimails.com/docs/authentication)
- [OpenAPI JSON](https://verimails.com/openapi.json)
- [OpenAPI YAML](https://verimails.com/openapi.yaml)
- [Core API reference](https://verimails.com/docs/api.md)
- [Code examples](https://verimails.com/docs/examples.md)

## API Documentation
- [Single Email Verification](https://verimails.com/docs/single-verification)
- [Bulk Verification](https://verimails.com/docs/bulk-verification)
- [Email Finder](https://verimails.com/docs/email-finder)
- [Result Codes](https://verimails.com/docs/result-codes)
- [Credits and Usage](https://verimails.com/docs/credits)
- [Rate Limits](https://verimails.com/docs/rate-limits)
- [Error Handling](https://verimails.com/docs/errors)
- [Agent Resources](https://verimails.com/docs/agent-resources)

## LLM and Agent Resources
- [Docs index for agents](https://verimails.com/docs/llms.txt)
- [Full Markdown docs bundle](https://verimails.com/llms-full.txt)
- [Agent resources](https://verimails.com/docs/agent-resources)
- [OpenAPI JSON](https://verimails.com/openapi.json)
- [OpenAPI YAML](https://verimails.com/openapi.yaml)


---

# Quick Start

This quick start verifies one email address with the VeriMails API.

## 1. Create an API Key

Create an API key in your VeriMails dashboard.

## 2. Send a Verification Request

```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"}'
```

## 3. Read the Result

```json
{
  "email": "person@example.com",
  "status": "valid",
  "safe_to_send": true,
  "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"
}
```

Use `safe_to_send: true` as the primary filter for sendable records. When `safe_to_send` is false, review the `status` and supporting fields before sending.

## Next Steps
- [Single Verification](https://verimails.com/docs/single-verification)
- [Bulk Verification](https://verimails.com/docs/bulk-verification)
- [Result Codes](https://verimails.com/docs/result-codes)


---

# Authentication

All API requests require a VeriMails API key in the `Authorization` header.

```http
Authorization: Bearer YOUR_API_KEY
```

Keep API keys server-side. Do not expose them in browser JavaScript, public repositories, or client-side mobile apps.

## Example

```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"}'
```

## Errors
- `401` means the key is missing or invalid.
- `403` means the key or account cannot access the requested resource.


---

# Single Email Verification

Verify one email address with `POST /api/verify/single`.

## Endpoint

```http
POST https://verimails.com/api/verify/single
```

## Request

```json
{"email":"person@example.com"}
```

## Response Fields

- `email`: verified address.
- `status`: verification result, such as `valid`, `invalid`, `catchall`, `disposable`, `unknown`, or `risky`.
- `safe_to_send`: boolean recommendation. It is true only when the returned status is `valid`.
- `confidence_score`: overall confidence for the result.
- `reason`: human-readable explanation.
- `domain`: domain extracted from the address.
- `is_disposable`: disposable email provider flag.
- `is_role_based`: role inbox flag such as `info@` or `support@`.
- `is_free`: free email provider flag such as Gmail or Outlook.
- `is_catch_all`: catch-all domain flag.
- `mx_records`: MX records observed for the domain.
- `verification_time_ms`: request processing time in milliseconds.

## Example

```json
{
  "email": "jane.doe@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"
}
```


---

# Bulk Verification

Upload a CSV and create an asynchronous verification job with `POST /api/bulk`.

## Upload

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

The CSV should contain an email column. VeriMails also auto-detects common headers such as `email`, `Email Address`, `work_email`, `business_email`, and `contact_email`.

## Poll Status

```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 download preserves the original CSV columns and appends `Safe to Send` with `Yes` or `No`.


---

# Email Finder API

Find a verified business contact email from first name, last name, and company domain.

## Endpoint

```http
POST https://verimails.com/api/find-email
```

## Request

```json
{
  "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
}
```

Email Finder costs 10 credits only when a verified email is found.

## CSV Finder

```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"
```


---

# Result Codes

VeriMails returns a `status` and `safe_to_send` recommendation for each verification.

## Statuses

- `valid`: mailbox appears reachable. `safe_to_send` is true.
- `invalid`: the address should not be contacted.
- `disposable`: temporary or disposable email provider.
- `catchall`: domain accepts broadly, so the individual mailbox cannot be confirmed.
- `unknown`: verification could not produce a confident result.
- `risky`: address should be reviewed or segmented before sending.

For most workflows, use `safe_to_send: true` as the primary filter.


---

# Credits and Usage

VeriMails uses credits for verification and finder workflows.

## Credit Rules

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

Paid plans and credit packs are available at https://verimails.com/pricing.


---

# Rate Limits

VeriMails applies request limits to protect API reliability.

## Limits

- Free accounts: 60 requests per minute and 5,000 requests per day.
- Paid accounts: 300 requests per minute, with usage governed by plan allocation and credit balance.
- Batch verification: up to 500 emails per request.

When the API returns `429`, back off and retry after the period indicated by the response when present.


---

# Error Handling

VeriMails uses standard HTTP status codes.

## Common Errors

- `400`: malformed request.
- `401`: missing or invalid authentication.
- `402`: insufficient credits.
- `403`: access denied or feature unavailable for the account.
- `404`: resource not found.
- `409`: job is not complete yet.
- `422`: required field missing or invalid.
- `429`: rate limit exceeded.
- `500`: temporary server error.

Retry only retryable failures such as temporary network errors, rate limits, or 5xx responses.


---

# Webhooks

Webhook documentation is reserved for production webhook events. Use polling endpoints for current bulk and finder jobs unless your account has a separately configured webhook workflow.

## Current Polling Endpoints

- `GET /api/bulk/{job_id}`
- `GET /api/find-email/csv/{job_id}`

When webhook documentation is expanded, this page should include event types, payload examples, signature verification, retries, and idempotency guidance.


---

# 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.


---

# VeriMails API Examples

Use `https://verimails.com` as the base URL and send `Authorization: Bearer YOUR_API_KEY` with API requests.

## JavaScript: Verify One Email

```js
const response = await fetch("https://verimails.com/api/verify/single", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.VERIMAILS_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ email: "person@example.com" })
});

const result = await response.json();
if (result.safe_to_send) {
  console.log("Use this address", result.email);
}
```

## Python: Verify One Email

```python
import os
import requests

response = requests.post(
    "https://verimails.com/api/verify/single",
    headers={"Authorization": f"Bearer {os.environ['VERIMAILS_API_KEY']}"},
    json={"email": "person@example.com"},
    timeout=30,
)
response.raise_for_status()
result = response.json()
print(result["status"], result["safe_to_send"])
```

## JavaScript: Upload a Bulk CSV

```js
import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("leads.csv")]), "leads.csv");
form.append("email_column", "Email Address");

const response = await fetch("https://verimails.com/api/bulk", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.VERIMAILS_API_KEY}` },
  body: form
});

const job = await response.json();
console.log(job.job_id, job.status);
```

## Python: Poll and Download Bulk Results

```python
import os
import requests

api_key = os.environ["VERIMAILS_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}
job_id = 123

status = requests.get(f"https://verimails.com/api/bulk/{job_id}", headers=headers, timeout=30)
status.raise_for_status()
print(status.json())

results = requests.get(f"https://verimails.com/api/bulk/{job_id}/download", headers=headers, timeout=120)
results.raise_for_status()
open("results.csv", "wb").write(results.content)
```

## JavaScript: Find a Verified Business Email

```js
const response = await fetch("https://verimails.com/api/find-email", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.VERIMAILS_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    first_name: "Jane",
    last_name: "Doe",
    domain: "example.com"
  })
});

const result = await response.json();
if (result.found) {
  console.log("Verified email:", result.email);
}
```

## Python: Find a Verified Business Email

```python
import os
import requests

response = requests.post(
    "https://verimails.com/api/find-email",
    headers={"Authorization": f"Bearer {os.environ['VERIMAILS_API_KEY']}"},
    json={"first_name": "Jane", "last_name": "Doe", "domain": "example.com"},
    timeout=60,
)
response.raise_for_status()
print(response.json())
```