Validate email lists with the same allow, block, or review decision model used by the real-time API. Use batch jobs for imports, pre-send quality checks, and CRM cleanup workflows.
Batch lifecycle
Batch validation is best for known lists. Real-time signup gates should continue to use the validate email endpoint.
Batch endpoints require a bearer token with the validate scope. Credits are reserved when the job is created and reconciled as rows are consumed, left unused, or cancelled.
| Method | Path | Use |
|---|---|---|
| POST | /api/v1/batch | Create a batch validation job from a JSON emails array and optional name. |
| GET | /api/v1/batch | List batch jobs for the authenticated team. |
| GET | /api/v1/batch/{id} | Read batch status, counts, and processing metadata. |
| GET | /api/v1/batch/{id}/results | Read validation results with decision, reason code, score, and checks. |
| GET | /api/v1/batch/{id}/export | Download CSV columns: row_number, email, status, decision, reason_code, decision_message, score, and error_message. |
| GET | /api/v1/batch/{id}/credits | Review credit usage and validation counts for a batch job. |
| POST | /api/v1/batch/{id}/cancel | Cancel a batch job that should no longer process. |
The API create endpoint accepts JSON. File upload is available from the Soryxa batch jobs screen, not as a separate public file-upload API endpoint.
POST /api/v1/batch
Authorization: Bearer $SORYXA_API_KEY
Content-Type: application/json
{
"name": "June CRM import",
"emails": [
"user@example.com",
"review@example.org"
]
}Export or sync the decision fields that your workflow uses downstream.
GET /api/v1/batch/{id}/results
Authorization: Bearer $SORYXA_API_KEY
{
"success": true,
"data": {
"job": {
"id": 42,
"status": "completed"
},
"results": [
{
"row_number": 1,
"email": "user@example.com",
"status": "completed",
"decision": "allow",
"reason_code": "CLASSIFICATION_VALID",
"score": 96
}
]
},
"pagination": {
"current_page": 1,
"last_page": 1,
"per_page": 50,
"total": 1
}
}Batch creation reserves credits for the submitted rows. Completed rows consume credits, while cancelled or unused rows stay visible in the batch credits summary.
The results endpoint can be filtered by row status and decision. The CSV export downloads every row for a terminal batch.
row_number, email, status, decision, reason_code, decision_message, score, and error_message.
Soryxa echoes X-Soryxa-Correlation-Id on batch create responses when the caller supplies one.
The Soryxa batch jobs screen adds operational controls on top of the public JSON API, especially when teams need to compare policy changes or keep known lists fresh.
Requeues pending rows after a partial batch without revalidating completed allow, block, or review rows.
Creates a new batch from reusable email hashes and records source and target policy revision metadata for comparison.
Downloads a CSV comparing previous and current decisions, reason codes, changed flags, and changed-risk contacts.
Maintains weekly, monthly, or quarterly schedules with next run, last metered rows, and changed-risk counters.
Treat file problems, credit limits, and partial jobs as operational states. Treat allow, block, and review as email-quality decisions.
| Issue | Recommended action |
|---|---|
| File will not upload | Check the file type, header row, row count, and whether the email column is mapped. |
| Partial job | Export completed rows, inspect failed rows, and retry only rows that were not validated. |
| Usage limit reached | Pause new batches, check credits, and choose a plan with enough allowance before retrying. |
| Too many review results | Review rule thresholds and reason codes before changing bulk automation behavior. |
| Export missing fields | The CSV contract contains eight columns and does not include checks or decision_reasons; read those fields from the results endpoint. |