List Cleanser API Documentation

Introduction

Welcome to the List Cleanser API! This API allows you to:

Verify single email addresses.
Upload and verify batches of email addresses.
Retrieve verification results for your email lists.
Check your available verification credits.

Our API is designed to help you integrate email verification seamlessly into your applications, ensuring you maintain a clean and valid email list for your communication needs.

Authentication

All API requests must be authenticated using an API key.

Obtaining an API Key

Sign up for an account on our platform.
Navigate to the API section in your dashboard.
Generate a new API key (public or private).

Using the API Key

Include your API key in the request headers:

X-API-Key: your_api_key_here

Types of API Keys

Public API Keys:
- Intended for client-side applications.
- May have domain restrictions.
Private API Keys:
- Intended for server-side applications.
- May have IP restrictions.
- Must not be exposed in client-side code.

Test API Keys

Test API keys are available for integration testing.
When using a test API key, the API returns predefined test data.
Test keys do not consume real credits.

Error Responses for Authentication

Missing or invalid API keys result in authentication errors.
401 Unauthorized: Authentication failed or was not provided.
403 Forbidden: API key is invalid, expired, or lacks permissions.

Example Error Response

{
  "message": "Unauthorized access"
}

API Endpoints

1. Verify a Single Email

Verify the validity of a single email address.

Endpoint

POST https://api.listcleanser.com/api/v1/verify

Description

This endpoint verifies a single email address and provides detailed information about its validity and associated metadata.

Request Headers

Content-Type: application/json
X-API-Key: your_api_key_here (required if using API key authentication)

Request Body

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

Response

{
  "success": true,
  "data": {
    "email_address": "user@example.com",
    "score": 60,
    "state": "deliverable",
    "reason": "accepted_email",
    "accept_all": false,
    "disposable": false,
    "free": false,
    "role": false,
    "possible_spamtrap": false,
    "did_you_mean": null,
    "user": "user",
    "domain": "example.com",
    "mx_record": "mx.example.com",
    "smtp_provider": "ExampleProvider",
    "duration": 0.5
  }
}

Response Fields

email_address: The email address that was verified.
score: A confidence score (0 to 100) indicating the likelihood of the email being valid.
state: The verification state (deliverable, undeliverable, risky, unknown).
reason: The reason for the verification state.
accept_all: Whether the domain accepts all emails.
disposable: Whether the email is from a disposable email provider.
free: Whether the email is from a free email provider.
role: Whether the email is a role-based address (e.g., admin@, support@).
possible_spamtrap: Whether the email could be a spam trap.
did_you_mean: Suggested correction if a typo is detected.
user: The local part of the email address.
domain: The domain part of the email address.
mx_record: The MX record of the email domain.
smtp_provider: The SMTP provider of the email domain.
duration: Time taken to verify the email (in seconds).

Rate Limits

Limit: 200 requests per minute per IP address.
Note: Exceeding this limit will result in a 429 Too Many Requests error.

2. Upload a Batch of Emails for Verification

Upload a file or a JSON payload containing multiple email addresses for bulk verification.

Endpoint

POST https://api.listcleanser.com/api/v1/batch

Description

This endpoint allows you to upload either a file or a JSON payload with a list of email addresses for bulk verification. Supported file formats include CSV, TXT, XLS, and XLSX, and you can also send a JSON request body with up to 50,000 email addresses.

Request Headers

Content-Type: multipart/form-data or application/json
X-API-Key: your_api_key_here (required if using API key authentication)

Request Body

{
  "emails": ["user1@example.com", "user2@example.com", "user3@example.com", ...]
}

Form Data Parameters

email_list (file): The file containing the list of email addresses.

Constraints

File Size Limit: Up to 1 GB.
JSON Payload Limit: Up to 50,000 email addresses.
Accepted File Types: .csv, .txt, .xls, .xlsx.

Response

{
  "success": true,
  "data": {
    "id": 456,
    "name": "email_list.csv",
    "status": "processing",
    "number_of_total": 1000,
  }
}

Response Fields

success: Indicates whether the request was successful.
data: Information about the uploaded list.
- id: The unique identifier for the email list.
- name: The original name of the uploaded file.
- status: The current status of the verification process (processing, processed, etc.).
- number_of_total: Total number of email addresses in the list.

Rate Limits

Limit: 6 requests per minute per IP address.
Note: Exceeding this limit will result in a 429 Too Many Requests error.

3. Retrieve Verification Results for a Batch

Fetch the verification results or the current state of a previously uploaded email list.

Endpoint

GET https://api.listcleanser.com/api/v1/batch/:listId

Description

This endpoint provides the processing state with progress information until the operation is complete. Once the verification is complete, it returns detailed results for each email in your uploaded list.

Path Parameters

listId (integer, required): The unique identifier of the email list.

Query Parameters

page (integer, optional): Page number for pagination (default: 1).
per_page (integer, optional): Number of results per page (default: 20).
state (string, optional): Filter results by verification state (deliverable, undeliverable, risky, unknown).

Request Headers

X-API-Key: your_api_key_here (required if using API key authentication)

Response (Processing State)

{
  "state": "processing",
  "progress": 10
}

Response Fields

state: Indicates the current state of the request. In this case, it shows "processing".
progress: Represents the percentage of the process that has been completed.

Completed Response

{
  "success": true,
  "stats": {
    "total": 1000,
    "duplicate": 0.0,
    "deliverable": 80.0,
    "undeliverable": 15.0,
    "risky": 3.0,
    "unknown": 2.0
  },
  "data": [
    {
      "id": 1,
      "email": {
        "email_address": "user1@example.com",
        "state": "deliverable",
        // additional email fields...
      }
    },
    // more records...
  ],
  "page": 1,
  "per_page": 20,
  "count": 20,
  "total_pages": 50
}

Response Fields

success: Indicates whether the request was successful.
stats: Statistics about the email list.
- total: Total number of emails in the list.
- duplicate: Percentage of duplicate emails.
- deliverable, undeliverable, risky, unknown: Percentage of emails in each state.
data: Array of email verification results.
- id: Record identifier.
- email: Object containing email verification details (same fields as in single email verification).
page: Current page number.
per_page: Number of results per page.
count: Number of records in the current page.
total_pages: Total number of pages.

Rate Limits

Limit: 200 requests per minute per IP address.
Note: Exceeding this limit will result in a 429 Too Many Requests error.

4. Retrieve Available Verification Credits

Check how many email verification credits you have remaining.

Endpoint

GET https://api.listcleanser.com/api/v1/credits

Description

This endpoint returns the number of email verification credits available in your account.

Request Headers

X-API-Key: your_api_key_here (required if using API key authentication)

Response

{
  "success": true,
  "data": 5000
}

Response Fields

success: Indicates whether the request was successful.
data: Number of available verification credits.

Rate Limits

Limit: 200 requests per minute per IP address.
Note: Exceeding this limit will result in a 429 Too Many Requests error.

Rate Limits Summary

To ensure fair usage and maintain optimal performance, the API enforces rate limits on requests.

Endpoint(s)	Limit	Notes
`/verify`	200 requests per minute per IP address	Standard endpoint
`/batch/:listId`	200 requests per minute per IP address	Standard endpoint
`/credits`	200 requests per minute per IP address	Standard endpoint
`/batch`	6 requests per minute per IP address	Batch upload endpoint

Important Notes

If you exceed the rate limit, you will receive a 429 Too Many Requests response with the message: "Too many requests, please try again after a minute."
Rate limit headers are included in responses to help you monitor your usage.

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Common Status Codes

200 OK: Request was successful.
201 Created: Resource was created successfully.
400 Bad Request: Invalid request parameters.
401 Unauthorized: Missing or invalid authentication.
402 Payment Required: Insufficient credits.
403 Forbidden: Access denied.
404 Not Found: Resource not found.
429 Too Many Requests: Rate limit exceeded.
500 Internal Server Error: Server encountered an error.

Error Response Format

{
  "message": "Description of the error"
}

Support

If you have any questions or need assistance, please contact our support team:

Email: support@listcleanser.com
Website: www.listcleanser.com/support

Thank you for using our List Cleanser API! We look forward to helping you maintain a clean and effective email communication strategy.

Introduction​

Authentication​

Obtaining an API Key​

Using the API Key​

Test API Keys​

Error Responses for Authentication​

API Endpoints​

1. Verify a Single Email​

2. Upload a Batch of Emails for Verification​

3. Retrieve Verification Results for a Batch​

4. Retrieve Available Verification Credits​

Rate Limits Summary​

Error Handling​

Support​

Introduction

Authentication

Obtaining an API Key

Using the API Key

Test API Keys

Error Responses for Authentication

API Endpoints

1. Verify a Single Email

2. Upload a Batch of Emails for Verification

3. Retrieve Verification Results for a Batch

4. Retrieve Available Verification Credits

Rate Limits Summary

Error Handling

Support