VoidBounce

API Documentation

Integrate our email validation service into your applications with our RESTful API. Get started with these endpoints and validate emails at scale.

Base URL

http://localhost:8001

For production, replace with your deployed VM1 server URL

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY
POST
/auth/register

Register User

Create a new user account for API access

Headers

Content-Type: application/json

Request Body

{
  "email": "user@example.com",
  "password": "your_password"
}

Response

{
  "id": 1,
  "email": "user@example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "is_active": true
}
POST
/auth/login

Login User

Authenticate user and get access token

Headers

Content-Type: application/json

Request Body

{
  "email": "user@example.com",
  "password": "your_password"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
POST
/validation/order

Create Validation Order

Upload a file containing email addresses for bulk validation

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Request Body

{
  "filename": "emails.txt",
  "file_content": "dXNlckBleGFtcGxlLmNvbQp0ZXN0QGV4YW1wbGUuY29t...",
  "workers": 10
}

Response

{
  "job_id": "7dbf0d69-80ec-4b54-95c0-de0156d1981b",
  "status": "pending",
  "message": "Validation order created successfully"
}
GET
/validation/status/{job_id}

Get Job Status

Check the status of a validation job and get progress information

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Response

{
  "job_id": "7dbf0d69-80ec-4b54-95c0-de0156d1981b",
  "status": "completed",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:35:00Z",
  "file_url": "/api/download/7dbf0d69-80ec-4b54-95c0-de0156d1981b",
  "error_message": null,
  "progress_percentage": 100
}
GET
/validation/jobs

List User Jobs

Get all validation jobs for the authenticated user

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Response

[
  {
    "job_id": "7dbf0d69-80ec-4b54-95c0-de0156d1981b",
    "status": "completed",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:35:00Z",
    "file_url": "/api/download/7dbf0d69-80ec-4b54-95c0-de0156d1981b",
    "error_message": null,
    "progress_percentage": 100
  }
]
GET
/api/download/{job_id}

Download Result File

Download the validation results file for a completed job

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN

Response

"Binary file download (ZIP format)"
POST
/validation/cancel/{job_id}

Cancel Job

Cancel a running or pending validation job

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Response

{
  "job_id": "7dbf0d69-80ec-4b54-95c0-de0156d1981b",
  "status": "cancelled",
  "message": "Validation job cancelled successfully"
}
GET
/health

Health Check

Check the API service health status

Headers

Content-Type: application/json

Response

{
  "status": "healthy",
  "service": "server1-master",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "2.0.0"
}

Rate Limiting

API requests are rate limited based on your plan:

  • Starter: 100 requests per minute
  • Professional: 1,000 requests per minute
  • Enterprise: Custom limits

Error Codes

400 - Bad Request
401 - Unauthorized
429 - Rate Limited
500 - Internal Server Error