API Reference

Verification Endpoints

Email verification in Cleanmails is handled through the lead validation system. Upload a lead list and trigger validation as a background job.

Validate Leads

bash

POST /api/v1/workspaces/:wid/leads/validate

Triggers email validation on uploaded leads. This enqueues a background job that processes leads through the validation pipeline.

bash

curl -X POST https://YOUR_SERVER/api/v1/workspaces/1/leads/validate \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN" \
  -d '{"list_id": 1}'

Validation Pipeline

Each email goes through a multi-step validation process:

Step	Check	Description
1	Regex syntax	RFC 5322 compliant format check
2	Disposable domain	Checked against 120,000+ known disposable providers
3	Role-based filter	Detects info@, admin@, support@, etc.
4	Free email flag	Identifies Gmail, Yahoo, Outlook addresses
5	DNS MX lookup	Verifies domain has mail servers (5s timeout)
6	DNS A-record fallback	Falls back to A record if no MX found
7	Gravatar check	MD5 ping to verify human account exists

Score Output

Each lead receives a score from 0–100 with a detailed breakdown:

Score Range	Status	Meaning
80–100	Valid (green)	High confidence deliverable
50–79	Risky (amber)	May bounce, use with caution
0–49	Invalid (red)	Likely to bounce, do not send

Upload + Validate Flow

The typical workflow is to upload a CSV list, then trigger validation:

bash

# Step 1: Upload CSV lead list
curl -X POST https://YOUR_SERVER/api/v1/workspaces/1/leads/upload \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN" \
  -F "file=@leads.csv"

# Step 2: Trigger validation on the uploaded list
curl -X POST https://YOUR_SERVER/api/v1/workspaces/1/leads/validate \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN" \
  -d '{"list_id": 1}'

# Step 3: Check lead status (results update in real-time)
curl https://YOUR_SERVER/api/v1/workspaces/1/leads \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN"

Background processing

Validation runs as a background job in the worker's default priority queue. Results are written to the database as each lead is processed. The frontend shows a real-time progress bar.

CSV Format

The uploaded CSV should include at minimum an email column. Additional supported columns:

Column	Description
`email`	Email address (required)
`first_name`	First name
`last_name`	Last name
`company`	Company name
`job_title`	Job title
`phone`	Phone number

Duplicate emails within the same workspace are automatically deduplicated (enforced by a database unique index).

See Validation Overview for more details on the verification engine.