# Bulk Email Verification

> Docs index for AI agents: [https://mailvalid.io/llms.txt](https://mailvalid.io/llms.txt). Every docs page is also available as Markdown: add `.md` to its URL.

Verify up to 10,000 emails in a single request. Jobs run asynchronously: poll for status, or get a [webhook](https://mailvalid.io/docs/webhooks) when the job completes.

```
POST https://mailvalid.io/api/v1/verify/bulk
```

## Request body

| Parameter | Type | Required | Description |
|---|---|---|---|
| `emails` | array | Required | Array of email addresses (max 10,000) |
| `webhook_url` | string | Optional | URL to receive completion webhook |

## Submit a bulk job

```bash
curl -X POST https://mailvalid.io/api/v1/verify/bulk \
  -H "X-API-Key: mv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "john@company.com",
      "jane@example.org",
      "info@business.net"
    ],
    "webhook_url": "https://yourapp.com/webhooks/mailvalid"
  }'
```

## Response (job created)

```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "total_emails": 3,
  "credits_reserved": 3,
  "webhook_url": "https://yourapp.com/webhooks/mailvalid"
}
```

`credits_reserved` is the maximum possible charge and is reserved at submit time. Unused credits are released after processing. The final charge is returned as `credits_used` when the job completes.

## Check job status

```bash
curl https://mailvalid.io/api/v1/verify/bulk/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: mv_live_your_key_here"
```

## Completed job response

```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "total_emails": 3,
  "processed_emails": 3,
  "valid_count": 2,
  "invalid_count": 1,
  "credits_used": 3,
  "results": [
    {
      "email": "john@company.com",
      "status": "valid",
      "is_valid": true
    }
  ]
}
```

Each entry in `results` has the same fields as a [single verification](https://mailvalid.io/docs/verify-single) result.

## Limits

Free accounts can submit up to 100 emails per bulk job. Every paid plan can submit up to 10,000. See [Rate limits](https://mailvalid.io/docs/rate-limits).

## Related

- [Job management](https://mailvalid.io/docs/job-management): list, download and cancel jobs
- [Webhooks](https://mailvalid.io/docs/webhooks): get notified when a job completes