# VeriMails API

Base URL: https://verimails.com

## Human Docs
- https://verimails.com/docs
- https://verimails.com/docs/quickstart
- https://verimails.com/docs/authentication
- https://verimails.com/docs/single-verification
- https://verimails.com/docs/bulk-verification
- https://verimails.com/docs/email-finder
- https://verimails.com/docs/result-codes
- https://verimails.com/docs/rate-limits
- https://verimails.com/docs/errors
- https://verimails.com/docs/agent-resources

## Agent-Readable Docs
- https://verimails.com/docs/index.md
- https://verimails.com/docs/agent-resources.md
- https://verimails.com/docs/quickstart.md
- https://verimails.com/docs/authentication.md
- https://verimails.com/docs/single-verification.md
- https://verimails.com/docs/bulk-verification.md
- https://verimails.com/docs/email-finder.md
- https://verimails.com/docs/result-codes.md
- https://verimails.com/docs/rate-limits.md
- https://verimails.com/docs/errors.md
- https://verimails.com/docs/api.md
- https://verimails.com/docs/examples.md
- https://verimails.com/llms-full.txt
- https://verimails.com/openapi.json
- https://verimails.com/openapi.yaml

## Authentication
API requests use a Bearer token:

```http
Authorization: Bearer YOUR_API_KEY
```

## Credits
- Email verification: 1 credit verifies 1 submitted email address.
- Bulk verification: 1 credit is reserved for each submitted address when a 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.

## Core Endpoints
- `POST /api/verify/single` - verify one address.
- `POST /api/verify/batch` - verify up to 500 addresses in one request.
- `POST /api/bulk` - upload a CSV and create an asynchronous bulk job.
- `GET /api/bulk/{job_id}` - check bulk job status.
- `GET /api/bulk/{job_id}/download` - download all bulk results as CSV.
- `GET /api/bulk/{job_id}/download/safe` - download safe-to-send rows.
- `GET /api/bulk/{job_id}/download/unsafe` - download rows not marked safe.
- `POST /api/find-email` - find and verify one business contact email.
- `POST /api/find-email/bulk` - find emails for a small JSON batch.
- `POST /api/find-email/csv` - upload a CSV for asynchronous Email Finder processing.
- `GET /api/find-email/csv/{job_id}` - check finder CSV status.
- `GET /api/find-email/csv/{job_id}/download` - download finder CSV results.

## Common Errors
- `401`: missing or invalid API key/session.
- `402`: insufficient credits.
- `403`: access denied or feature unavailable for the account.
- `409`: requested file exists but the job is not complete yet.
- `422`: request body is missing required fields or has invalid input.
- `429`: rate limit exceeded.