# VeriMails Agent Resources

Machine-readable VeriMails documentation for coding agents, developer tools, and integration workflows.

## Entry Points

- Human docs: https://verimails.com/docs
- Agent docs index: https://verimails.com/docs/llms.txt
- Full Markdown docs bundle: https://verimails.com/llms-full.txt
- Docs summary: https://verimails.com/docs.md
- OpenAPI JSON: https://verimails.com/openapi.json
- OpenAPI YAML: https://verimails.com/openapi.yaml

## Markdown Docs

- Overview: https://verimails.com/docs/index.md
- Quick start: https://verimails.com/docs/quickstart.md
- Authentication: https://verimails.com/docs/authentication.md
- Core API reference: https://verimails.com/docs/api.md
- Code examples: https://verimails.com/docs/examples.md
- Single verification: https://verimails.com/docs/single-verification.md
- Bulk verification: https://verimails.com/docs/bulk-verification.md
- Email Finder: https://verimails.com/docs/email-finder.md
- Result codes: https://verimails.com/docs/result-codes.md
- Credits and usage: https://verimails.com/docs/credits.md
- Rate limits: https://verimails.com/docs/rate-limits.md
- Error handling: https://verimails.com/docs/errors.md

## Implementation Order

1. Create an API key in the VeriMails dashboard.
2. Call `POST /api/verify/single` with one address.
3. Add handling for `valid`, `invalid`, `catch_all`, `unknown`, `disposable`, and `role_based` results.
4. Add credit and rate-limit error handling.
5. Move to `POST /api/bulk` for CSV list processing.
6. Use Email Finder endpoints only when a workflow needs to find a missing business contact email.

## Authentication

Use a Bearer token:

```http
Authorization: Bearer YOUR_API_KEY
```

## Core Endpoints

- `POST /api/verify/single` - verify one email address.
- `POST /api/verify/batch` - verify up to 500 email addresses in one JSON request.
- `POST /api/bulk` - upload a CSV and create an asynchronous bulk verification job.
- `GET /api/bulk/{job_id}` - check a bulk job.
- `GET /api/bulk/{job_id}/download` - download all bulk results.
- `GET /api/bulk/{job_id}/download/safe` - download safe-to-send bulk results.
- `POST /api/find-email` - find and verify one business contact email.
- `POST /api/find-email/bulk` - process a small JSON batch for Email Finder.
- `POST /api/find-email/csv` - create an asynchronous Email Finder CSV job.

## Notes For Agents

- Do not assume every response is safe to send. Treat `safe_to_send` and `status` as the decision fields.
- Do not retry `402` insufficient-credit responses automatically.
- Retry `429` responses only after a backoff delay.
- Preserve customer CSV columns when explaining bulk workflows; VeriMails appends verification result fields to the output.