Bulk endpoint

POST /api/v1/bulk — validate a batch of emails in one request.

Create a bulk job

POST https://mailsentry.dev/api/v1/bulk
Content-Type: application/json
X-API-Key: ms_live_your_key_here

{
  "emails": ["jane@example.com", "bob@tempmail.org", "info@company.co"],
  "filename": "leads-april.csv"
}

The emails field is required (array of strings). filename is optional — it's stored for your reference in job history.

Batch size limits: 100 (Free), 500 (Starter), 1,000 (Pro), 5,000 (Business), 10,000 (Enterprise).

Response

{
  "id": "job_abc123",
  "status": "completed",
  "total": 3,
  "results": [
    { "email": "jane@example.com",  "score": 95, "verdict": "valid",   "issues": [] },
    { "email": "bob@tempmail.org",  "score": 12, "verdict": "invalid", "issues": ["Disposable email"] },
    { "email": "info@company.co",   "score": 72, "verdict": "caution", "issues": ["Role-based address"] }
  ]
}

Retrieve a job

Fetch a previously submitted job by ID:

GET https://mailsentry.dev/api/v1/bulk/{job_id}
X-API-Key: ms_live_your_key_here

Returns the same response shape as the create endpoint. Useful for polling status or downloading results later.

Streaming results

For real-time progress, add ?stream=1 to the request URL. The response is NDJSON (newline-delimited JSON) — one result per line as each email finishes:

{"i":0,"total":3,"email":"jane@example.com","score":95,"verdict":"valid","issues":[]}
{"i":1,"total":3,"email":"bob@tempmail.org","score":12,"verdict":"invalid","issues":["Disposable email"]}
{"i":2,"total":3,"email":"info@company.co","score":72,"verdict":"caution","issues":["Role-based address"]}
{"done":true,"jobId":"job_abc123"}

The dashboard uses this for its live progress display.

← Verify endpoint

Webhooks →