Bulk Lists API

Submit a list of email addresses for bulk validation, check its progress, and download the results, all from your own code. For the dashboard workflow, see Bulk Validation.

Endpoints

POST https://api.mailcop.net/v1/lists
GET  https://api.mailcop.net/v1/lists/:id
GET  https://api.mailcop.net/v1/lists/:id/export

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Create a list

Parameters

Element rules

Each element of emails must be one address:

• No whitespace, control characters, commas, or semicolons inside the element (leading and trailing whitespace is trimmed, and empty elements are ignored)
• At most 254 characters
• Send one address per element. A single string such as "[email protected],[email protected]" is rejected

Duplicates are removed automatically, ignoring case, and are not charged. They are reported as a count in duplicates; the duplicate addresses themselves are not returned. Elements with no recognizable address are dropped and not charged. The total in the response reflects the rows actually created.

Limits

• At most 50,000 elements per request
• Request body at most 5 MB

Both return 413. Split larger lists across several requests.

Example request

curl -X POST https://api.mailcop.net/v1/lists \
  -H "Authorization: Bearer tm_live_abc123..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-11-06-001" \
  -d '{
    "title": "November signups",
    "validation_type": "mx",
    "emails": ["[email protected]", "[email protected]"]
  }'

Success (202 Accepted)

The list is queued for validation. The Location header holds the URL of the new list.

{
  "id": "k3x9m2p7q4w8z5n6r1ta",
  "title": "November signups",
  "status": "pending",
  "validation_type": "mx",
  "total": 2,
  "good": 0,
  "bad": 0,
  "pending": 0,
  "duplicates": 0,
  "failure_reason": null,
  "created_at": "2026-11-06T10:15:00Z",
  "completed_at": null,
  "export_url": "https://api.mailcop.net/v1/lists/k3x9m2p7q4w8z5n6r1ta/export"
}

Idempotency

Send an Idempotency-Key header (up to 255 characters) to make retries safe. Within 24 hours, a repeat request with the same key and the same body returns 200 with the existing list (not 202) instead of creating another one and charging again. Reusing a key with a different emails array or validation_type returns 422. If a request with the same key is still being processed, you get 409 Conflict with a Retry-After header (in seconds). Wait and retry.

A failed list is never replayed; the same key creates a new list. The failed list’s unused credits were already refunded.

Credits

Credits for the unique addresses are locked when validation starts. The 402 for a short balance is checked at request time, so a list accepted with 202 can still fail later with email_list.failed if your credits run out before it starts. SMTP validation on a non-Premium plan also returns 402.

Check a list

curl https://api.mailcop.net/v1/lists/k3x9m2p7q4w8z5n6r1ta \
  -H "Authorization: Bearer tm_live_abc123..."

Response (200 OK)

Validation can wait in a queue under heavy load, so a list may stay pending for a while before it starts. Poll no more often than every 15 seconds, or use webhooks instead.

Export results

curl "https://api.mailcop.net/v1/lists/k3x9m2p7q4w8z5n6r1ta/export?output=csv&good_only=true" \
  -H "Authorization: Bearer tm_live_abc123..." \
  -o good_emails.csv

Parameters

CSV output always includes the extended columns: email, status, validation_type, reason, reason_code, role_account, free_provider, catch_all_domain, and result. JSONL output has one JSON object per line with email, the full validation result, and status.

In JSONL, email is the lowercased address from the result once the address is validated. In CSV, email keeps the spelling you submitted.

For spreadsheet safety, CSV cells that start with =, +, -, @, a tab, or a carriage return are prefixed with '. Use JSONL when you join results back to your data by machine.

The X-Total-Count response header holds the number of rows in the export.

Partial export

You can export a list while it is still running. Addresses not yet validated appear with their current status, and on a failed list they appear as not_validated. Those addresses were not charged.

One export at a time

Each account can run one export at a time. A second export while another is streaming returns 429 with Retry-After: 120. Wait and retry.

Webhooks

• email_list.started fires when processing begins, after the file is parsed and with the real total. It does not fire when credits are short.
• email_list.completed fires when validation finishes.
• email_list.failed fires when a list fails: no valid addresses, insufficient credits, validation could not start, or a stall with no progress for 30 minutes.

See Webhooks for payloads.

Errors

See Error Handling for details.