API Documentation

Learn how to use SuperList's email verification API in your applications.

Authentication

The API supports two authentication methods:

1. API Key

For programmatic access, use your API key with Bearer token authentication. You can find your API key in the dashboard under Account settings.

Authorization: Bearer your_api_key_here

2. Session Authentication

For browser-based requests, the API automatically uses your logged-in session. No additional headers are required if you're already authenticated.

Single Email Verification

POST https://superlist.email/api/verify/single

Request body:

{
  "email": "test@example.com"
}

Bulk Email Verification

POST https://superlist.email/api/verify/bulk

Request body:

{
  "emails": ["test1@example.com", "test2@example.com"]
}

Response Format

{
  "email": "test@example.com",
  "status": "VALID" | "INVALID" | "UNKNOWN",
  "result": {
    "input": "test@example.com",
    "is_reachable": "safe" | "invalid" | "risky",
    "misc": {
      "is_disposable": boolean,
      "is_role_account": boolean
    },
    "syntax": {
      "is_valid_syntax": boolean,
      "domain": string,
      "username": string,
      "suggestion": string | null
    }
  }
}

Bulk Response Format

{
  "success": true,
  "message": "Batch verification started",
  "batchId": "uuid-of-batch"
}

Bulk verifications are processed asynchronously. You can track the status of your batch using the batchId. Each email in the batch consumes one credit.

Batch Status Tracking

You can track the status of your batch verification using the batchId returned from the bulk verification endpoint.

GET https://superlist.email/api/verify/batch/:batchId

Response Format

{
  "id": "uuid-of-batch",
  "filename": "uploaded-file.csv",
  "email_count": 100,
  "verified_count": 45,
  "status": "processing" | "completed" | "failed",
  "created_at": "2024-02-20T15:30:00Z",
  "completed_at": null
}

Batch Status Values

  • processing - Batch is currently being processed
  • completed - All emails in the batch have been verified
  • failed - Batch processing encountered an error

Export Results

Once a batch is completed, you can export the results in CSV format.

GET https://superlist.email/api/verify/export?batch_id=:batchId

Rate Limits

API requests are limited based on your account's credit balance. Each verification consumes one credit. The API has a default rate limit of 100 requests per minute.

Error Codes

  • 401 - Invalid or missing API key
  • 402 - Insufficient credits
  • 429 - Rate limit exceeded
  • 500 - Internal server error