# Analyze Email List
Source: https://docs.sanitizeemail.com/api-reference/endpoint/analyze_list

POST /v1/api/filesupload/analyze-list/
Analyze an uploaded email list to get a close estimate of the bounce rate. This analysis provides a nearly accurate result without requiring any credits, making it a free way to gauge list quality before committing to a full cleaning.

This endpoint provides a quick analysis of an uploaded email list to estimate bounce rates and validation statistics without consuming credits. It performs intelligent sampling to deliver fast, approximate results that are close to actual values.

## How it Works

<Steps>
  <Step title="Upload File First">
    Use the [File Upload endpoint](/api-reference/endpoint/file_upload) to
    upload your CSV or XLSX file and obtain the `file_id`
  </Step>

  <Step title="Submit Analysis Request">
    Send the analysis request with the file ID and list name
  </Step>

  <Step title="Get Instant Results">
    Receive bounce rate estimates and status immediately
  </Step>
</Steps>

## Key Features

<CardGroup>
  <Card title="No Credits Required" icon="free">
    Analyze your email lists without consuming any validation credits
  </Card>

  <Card title="Fast Results" icon="bolt">
    Get bounce rate estimates in seconds, not minutes
  </Card>

  <Card title="Smart Sampling" icon="chart-line">
    Uses intelligent analysis to provide close approximations of actual rates
  </Card>

  <Card title="Pre-Validation Insights" icon="eye">
    Make informed decisions before running full validation
  </Card>
</CardGroup>

## Use Cases

* **Quick Quality Assessment**: Get a rapid overview of your email list quality
* **Budget Planning**: Estimate validation costs before processing
* **List Comparison**: Compare multiple lists without credit consumption
* **Pre-Processing Insights**: Understand your data before full validation

## Example Usage

```bash theme={null}
curl -X POST https://base.sanitizeemail.com/v1/api/filesupload/analyze-list/ \
  -H "X-API-KEY: YOUR_API_KEY" \
  -F "file_id=751" \
  -F "name=Customer List Analysis"
```

## Response Format

```json theme={null}
{
  "file_id": 751,
  "bounce_rate": 66.67,
  "status": "analyzed"
}
```

## Important Notes

<Note>
  **Approximation Method**: This endpoint uses intelligent sampling techniques
  to provide bounce rate estimates. While results are close to actual values,
  they are approximations and may vary from precise validation results.
</Note>

<Tip>
  **Zero Cost Analysis**: Perfect for getting insights into your email list
  quality without spending credits. Use this before deciding whether to proceed
  with full validation.
</Tip>

<Warning>
  **Not 100% Accurate**: Results are estimates based on analysis patterns. For
  exact validation results, use the [Clean Email
  List](/api-reference/endpoint/clean_list) endpoint.
</Warning>

## When to Use This vs Full Validation

| Use Analyze List When      | Use Full Validation When        |
| -------------------------- | ------------------------------- |
| Quick quality check needed | Exact results required          |
| Budget planning            | Preparing final email campaigns |
| Comparing multiple lists   | Compliance requirements         |
| Initial assessment         | Production email sends          |

## Prerequisites

<Note>
  **File Upload Required**: You must first upload a file using the
  `/v1/api/filesupload/` endpoint to obtain the required `file_id`.
</Note>


# Clean Email List
Source: https://docs.sanitizeemail.com/api-reference/endpoint/clean_list

POST /v1/api/cleanemail/
Process and clean an uploaded email list file with comprehensive validation options

This endpoint processes and cleans an uploaded email list file with comprehensive validation options. It requires a previously uploaded file from the [File Upload](/api-reference/endpoint/file_upload) endpoint.

## How it Works

<Steps>
  <Step title="Upload File First">
    Use the [File Upload endpoint](/api-reference/endpoint/file_upload) to
    upload your CSV or XLSX file and obtain the `file_id` and `file` URL
  </Step>

  <Step title="Configure Cleaning Options">
    Set your desired validation options (syntax, DMARC, SMTP, MX records)
  </Step>

  <Step title="Submit Cleaning Job">
    Send the cleaning request with the file reference and options
  </Step>

  <Step title="Monitor Progress">
    Use the returned `job_id` to track the cleaning progress
  </Step>
</Steps>

## Prerequisites

<Note>
  **File Upload Required**: You must first upload a file using the
  `/v1/api/filesupload/` endpoint to obtain the required `file_id` and `file`
  URL parameters.
</Note>

## Validation Options

The cleaning process supports multiple validation levels:

* **validate\_syntax**: Checks email format and structure
* **check\_dmarc**: Validates DMARC policy records
* **validate\_smtp**: Performs SMTP server validation
* **validate\_mx**: Checks MX record existence

<Tip>
  **Comprehensive Cleaning**: Enable all validation options for the most
  thorough email list cleaning, though this will consume more credits and take
  longer to process.
</Tip>

## Example Workflow

```json theme={null}
// 1. First upload a file
POST /v1/api/filesupload/
// Response includes: { "id": 739, "file": "https://s3.../file.csv" }

// 2. Then clean the uploaded file
POST /v1/api/cleanemail/
{
  "file_id": 739,
  "file": "https://s3.us-east-1.amazonaws.com/sanitizeemail/email_validation_files/Book_Sheet1_e5FL41X.csv",
  "user": 100,
  "list_name": "Customer List - Cleaned",
  "options": {
    "validate_syntax": true,
    "check_dmarc": true,
    "validate_smtp": true,
    "validate_mx": true
  }
}
```

<Warning>
  **Credits Consumption**: The cleaning process consumes credits based on the
  number of emails and validation options selected. More comprehensive
  validation uses more credits.
</Warning>


# View Clean List Results
Source: https://docs.sanitizeemail.com/api-reference/endpoint/clean_list_result

GET /v1/api/cleanedemail/
This endpoint retrieves the results of a cleaned email list, showing all valid emails that passed the validation process. Use this to access the clean emails after the cleaning job is completed.

This endpoint retrieves the results of a cleaned email list, showing all valid emails that passed the validation process. Use this to access the clean emails after the cleaning job is completed.

## How it Works

<Steps>
  <Step title="Complete Email Cleaning">
    First use the [Clean Email List](/api-reference/endpoint/clean_list)
    endpoint to process your file
  </Step>

  <Step title="Check Processing Status">
    Monitor the cleaning progress using the [View
    File](/api-reference/endpoint/view_file) endpoint
  </Step>

  <Step title="Retrieve Clean Results">
    Once status is "cleaned", use this endpoint to get the valid emails
  </Step>

  <Step title="Handle Pagination">
    Navigate through results using the pagination parameters
  </Step>
</Steps>

## When to Use This Endpoint

<CardGroup>
  <Card title="After Cleaning Complete" icon="circle-check">
    Retrieve results only after the file status shows "cleaned"
  </Card>

  <Card title="Access Valid Emails" icon="envelope-circle-check">
    Get the list of emails that passed all validation checks
  </Card>

  <Card title="Download Clean Data" icon="download">
    Access validated emails for your marketing campaigns
  </Card>

  <Card title="Review Cleaning Results" icon="magnifying-glass">
    Examine the quality and quantity of your clean email list
  </Card>
</CardGroup>

## Example Usage

```bash theme={null}
curl -X GET "https://base.sanitizeemail.com/v1/api/cleanedemail/?file_id=757&size=20&page=1" \
  -H "X-API-KEY: YOUR_API_KEY"
```

## Response Format

### Successful Response (With Results)

```json theme={null}
{
  "count": 168,
  "next": "https://base.sanitizeemail.com/v1/api/cleanedemail/?file_id=757&page=2&size=20",
  "previous": null,
  "results": [
    {
      "id": 3796123,
      "workspace": {
        "id": 100,
        "name": "asim's Team",
        "owner": 100
      },
      "clean_email": {
        "id": 188,
        "file_id": {
          "id": 757,
          "name": "Structured cleaned",
          "file_name": "Marketing Agency Australia.xlsx",
          "status": "cleaned",
          "clean_email_count": 173,
          "bounce_rate": 0
        }
      },
      "valid_email": "info@agent6.com.au",
      "created_date": "2025-07-14T15:41:41.921862+05:45"
    }
  ]
}
```

### Empty Response (No Clean Results)

```json theme={null}
{
  "count": 0,
  "next": null,
  "previous": null,
  "results": []
}
```

## Understanding Empty Results

<Warning>
  **Empty Results**: If the response contains no results, check the file
  processing status using the [View File](/api-reference/endpoint/view_file)
  endpoint to determine the cause:
</Warning>

| File Status  | Meaning                            | Action Required           |
| ------------ | ---------------------------------- | ------------------------- |
| `processing` | Cleaning in progress               | Wait for completion       |
| `cleaned`    | Cleaning complete, no valid emails | All emails were invalid   |
| `failed`     | Processing failed                  | Check error logs or retry |

## Important Notes

<Note>
  **File ID Required**: The `file_id` parameter is mandatory. You can only
  retrieve results for files you have uploaded and processed.
</Note>

<Tip>
  **Check Status First**: Always verify the file status is "cleaned" using the
  [View File](/api-reference/endpoint/view_file) endpoint before expecting
  results.
</Tip>

<Card title="Pagination" icon="list">
  **Large Result Sets**: Use `size` and `page` parameters to navigate through
  large numbers of clean emails efficiently.
</Card>

## Common Scenarios

### Scenario 1: Processing Still in Progress

```json theme={null}
// File status check shows:
{
  "status": "processing",
  "progress_percentage": 75
}
// Clean results will be empty until processing completes
```

### Scenario 2: All Emails Invalid

```json theme={null}
// File status shows:
{
  "status": "cleaned",
  "clean_email_count": 0,
  "invalid_emails_count": 150
}
// Clean results will be empty because no emails passed validation
```

### Scenario 3: Successful Cleaning

```json theme={null}
// File status shows:
{
  "status": "cleaned",
  "clean_email_count": 173,
  "bounce_rate": 0
}
// Clean results will contain the valid emails
```

## Error Responses

| Status Code | Description                           | Action                                |
| ----------- | ------------------------------------- | ------------------------------------- |
| `400`       | Invalid file\_id or missing parameter | Check the file\_id value              |
| `401`       | Unauthorized access                   | Verify your API key                   |
| `404`       | File not found                        | Ensure file exists and belongs to you |

## Prerequisites

<Note>
  **Required Steps**: 1. Upload file using [File
  Upload](/api-reference/endpoint/file_upload) 2. Clean file using [Clean Email
  List](/api-reference/endpoint/clean_list) 3. Wait for processing to complete
  4\. Retrieve results with this endpoint
</Note>


# Download Clean List
Source: https://docs.sanitizeemail.com/api-reference/endpoint/download_clean_list

GET /v1/api/cleanedemail/download-cleaned-emails/
Generates and provides a download URL for the cleaned email list from a processed file. Returns a secure, time-limited URL to download a CSV file containing only valid emails.

This endpoint generates and provides a download URL for the cleaned email list from a processed file. Use this to download a CSV file containing only the valid emails that passed the cleaning process.

## How it Works

<Steps>
  <Step title="Complete Email Cleaning">
    First use the [Clean Email List](/api-reference/endpoint/clean_list)
    endpoint to process your file
  </Step>

  <Step title="Verify Cleaning Status">
    Ensure the file status is "cleaned" using the [Get File
    Details](/api-reference/endpoint/view_file) endpoint
  </Step>

  <Step title="Request Download URL">
    Use this endpoint with the file\_id to get a secure download URL
  </Step>

  <Step title="Download the File">
    Use the provided download\_url to download your cleaned email list
  </Step>
</Steps>

## When to Use This Endpoint

<CardGroup>
  <Card title="Export Clean Data" icon="download">
    Download validated emails for use in marketing campaigns or CRM systems
  </Card>

  <Card title="Backup Clean Lists" icon="shield-check">
    Save cleaned email lists to your local storage or backup systems
  </Card>

  <Card title="Integration with Tools" icon="arrows-rotate">
    Import clean email lists into email marketing platforms or databases
  </Card>

  <Card title="Share Clean Results" icon="share">
    Provide cleaned email lists to team members or clients
  </Card>
</CardGroup>

## Example Usage

```bash theme={null}
curl -X GET "https://base.sanitizeemail.com/v1/api/cleanedemail/download-cleaned-emails/?file_id={id}" \
  -H "X-API-KEY: YOUR_API_KEY"
```

## Query Parameters

| Parameter | Type    | Required | Description                        |
| --------- | ------- | -------- | ---------------------------------- |
| `file_id` | integer | Yes      | ID of the file with cleaned emails |

<Note>
  **File ID Required**: The file\_id must correspond to a file that has been
  successfully cleaned and has a status of "cleaned".
</Note>

## Response Format

### Successful Response

```json theme={null}
{
  "download_url": "{YOUR_FILE_URL}",
  "filename": "cleaned_emails_757_1752553258.csv",
  "file_id": "757",
  "record_count": 172,
  "format": "csv"
}
```

### Response Fields

| Field          | Type    | Description                                                  |
| -------------- | ------- | ------------------------------------------------------------ |
| `download_url` | string  | Secure pre-signed URL for downloading the cleaned email file |
| `filename`     | string  | Name of the generated clean email file                       |
| `file_id`      | string  | ID of the original file that was cleaned                     |
| `record_count` | integer | Number of clean emails in the downloadable file              |
| `format`       | string  | File format (always "csv" for clean email lists)             |

## Download URL Characteristics

<CardGroup>
  <Card title="Secure Access" icon="lock">
    **Pre-signed URLs**: Download URLs are secure and temporarily accessible
    without additional authentication
  </Card>

  <Card title="Time-Limited" icon="clock">
    **Expiration**: URLs typically expire after a set period for security
    purposes
  </Card>

  <Card title="Direct Download" icon="download">
    **Ready to Use**: URLs can be used directly in browsers or download tools
  </Card>

  <Card title="CSV Format" icon="file-csv">
    **Standard Format**: Files are provided in CSV format for maximum
    compatibility
  </Card>
</CardGroup>

## Understanding the Downloaded File

The downloaded CSV file contains:

* **Clean Email Addresses**: Only emails that passed all validation checks
* **Standard CSV Format**: Compatible with spreadsheet applications and databases
* **No Headers**: Simple list format with one email per line
* **UTF-8 Encoding**: Supports international characters and domains

## Important Notes

<Note>
  **Cleaning Required**: This endpoint only works with files that have been
  processed through the cleaning workflow and have a status of "cleaned".
</Note>

<Tip>
  **Download Immediately**: For best results, download the file as soon as you
  receive the URL to avoid potential expiration.
</Tip>

<Warning>
  **URL Security**: Keep download URLs confidential as they provide temporary
  access to your cleaned email data.
</Warning>

## Common Scenarios

### Scenario 1: File Not Cleaned

```json theme={null}
// If file is still processing:
{
  "error": "File is still being processed",
  "file_status": "processing",
  "progress_percentage": 75
}
```

### Scenario 2: No Clean Emails

```json theme={null}
// If cleaning found no valid emails:
{
  "download_url": null,
  "message": "No clean emails found in this file",
  "record_count": 0
}
```

### Scenario 3: Successful Download

```bash theme={null}
# Use the download_url to get your file
curl -o "my_clean_emails.csv" "{YOUR_FILE_URL}"
```

## Error Responses

| Status Code | Description                           | Action                                |
| ----------- | ------------------------------------- | ------------------------------------- |
| `400`       | Invalid or missing file\_id parameter | Verify the file\_id value             |
| `401`       | Unauthorized access                   | Check your API key                    |
| `404`       | File not found or not accessible      | Ensure file exists and belongs to you |
| `409`       | File not ready for download           | Wait for cleaning to complete         |

## Prerequisites

<Note>
  **Required Steps**: 1. Upload file using [File
  Upload](/api-reference/endpoint/file_upload) 2. Clean file using [Clean Email
  List](/api-reference/endpoint/clean_list) 3. Wait for cleaning to complete
  (status = "cleaned") 4. Use this endpoint to get download URL
</Note>

## Download Workflow Example

```bash theme={null}
# 1. Check file status first
curl -X GET "https://base.sanitizeemail.com/v1/api/filesupload/{id}" \
  -H "X-API-KEY: YOUR_API_KEY"

# Response should show: "status": "cleaned"

# 2. Get download URL
curl -X GET "https://base.sanitizeemail.com/v1/api/cleanedemail/download-cleaned-emails/?file_id={id}" \
  -H "X-API-KEY: YOUR_API_KEY"

# 3. Download the file
curl -o "clean_emails.csv" "DOWNLOAD_URL_FROM_RESPONSE"
```

## Integration Tips

<CardGroup>
  <Card title="Automated Downloads" icon="robot">
    **Scripting**: Integrate this endpoint into automated workflows for regular
    email list cleaning
  </Card>

  <Card title="Webhook Integration" icon="webhook">
    **Event-Driven**: Trigger downloads automatically when cleaning jobs
    complete
  </Card>

  <Card title="Batch Processing" icon="layer-group">
    **Multiple Files**: Process multiple files and download all clean lists in
    sequence
  </Card>

  <Card title="Data Pipeline" icon="diagram-project">
    **ETL Workflows**: Incorporate into data processing pipelines for continuous
    email hygiene
  </Card>
</CardGroup>

## Related Endpoints

<CardGroup>
  <Card title="View Clean Results" icon="list">
    Use [View Clean List Results](/api-reference/endpoint/clean_list_result) to
    preview clean emails before downloading
  </Card>

  <Card title="Clean Email List" icon="broom">
    Use [Clean Email List](/api-reference/endpoint/clean_list) to initiate the
    cleaning process
  </Card>
</CardGroup>


# Download Validation Results
Source: https://docs.sanitizeemail.com/api-reference/endpoint/download_validated_list

GET /v1/api/email-validation/download-validation-results/
Generates and provides a download URL for the validation results from a processed file. Returns a secure, time-limited URL to download a CSV file containing detailed validation results for all processed emails.

This endpoint generates and provides a download URL for the validation results from a processed file. Use this to download a CSV file containing detailed validation results for all emails that were processed.

## How it Works

<Steps>
  <Step title="Complete Email Validation">
    First use the [Validate Email
    Addresses](/api-reference/endpoint/validate_emails) endpoint to process your
    file
  </Step>

  <Step title="Verify Validation Status">
    Ensure the file status is "validated" using the [Get File
    Details](/api-reference/endpoint/view_file) endpoint
  </Step>

  <Step title="Request Download URL">
    Use this endpoint with the file\_id to get a secure download URL
  </Step>

  <Step title="Download the File">
    Use the provided download\_url to download your validation results
  </Step>
</Steps>

## When to Use This Endpoint

<CardGroup>
  <Card title="Export Validation Data" icon="download">
    Download detailed validation results for analysis, reporting, or integration
  </Card>

  <Card title="Backup Validation Results" icon="shield-check">
    Save validation results to your local storage or backup systems
  </Card>

  <Card title="Integration with Analytics" icon="chart-line">
    Import validation data into analytics platforms or business intelligence
    tools
  </Card>

  <Card title="Share Detailed Reports" icon="share">
    Provide comprehensive validation reports to team members or clients
  </Card>
</CardGroup>

## Example Usage

```bash theme={null}
curl -X GET "https://base.sanitizeemail.com/v1/api/email-validation/download-validation-results/?file_id=740" \
  -H "X-API-KEY: YOUR_API_KEY"
```

## Query Parameters

| Parameter | Type    | Required | Description                            |
| --------- | ------- | -------- | -------------------------------------- |
| `file_id` | integer | Yes      | ID of the file with validation results |

<Note>
  **File ID Required**: The file\_id must correspond to a file that has been
  successfully validated and has a status of "validated".
</Note>

## Response Format

### Successful Response

```json theme={null}
{
  "download_url": "{YOUR_FILE_URL}",
  "filename": "validation_results_740_1752553784.csv",
  "file_id": "740",
  "record_count": 4,
  "format": "csv"
}
```

### Response Fields

| Field          | Type    | Description                                                       |
| -------------- | ------- | ----------------------------------------------------------------- |
| `download_url` | string  | Secure pre-signed URL for downloading the validation results file |
| `filename`     | string  | Name of the generated validation results file                     |
| `file_id`      | string  | ID of the original file that was validated                        |
| `record_count` | integer | Number of validation records in the downloadable file             |
| `format`       | string  | File format (always "csv" for validation results)                 |

## Download URL Characteristics

<CardGroup>
  <Card title="Secure Access" icon="lock">
    **Pre-signed URLs**: Download URLs are secure and temporarily accessible
    without additional authentication
  </Card>

  <Card title="Time-Limited" icon="clock">
    **Expiration**: URLs typically expire after a set period for security
    purposes
  </Card>

  <Card title="Direct Download" icon="download">
    **Ready to Use**: URLs can be used directly in browsers or download tools
  </Card>

  <Card title="CSV Format" icon="file-csv">
    **Standard Format**: Files are provided in CSV format for maximum
    compatibility
  </Card>
</CardGroup>

## Understanding the Downloaded File

The downloaded CSV file contains comprehensive validation data:

* **Email Address**: Original email addresses that were validated
* **Validation Status**: Valid, invalid, or unknown status for each email
* **Detailed Reasons**: Specific reasons for validation results (syntax, DNS, MX, SMTP, DMARC)
* **Email Classification**: Type (business/personal), disposable status, role account detection
* **Technical Details**: MX records, validation timing, DMARC policy information
* **Standard CSV Format**: Compatible with spreadsheet applications and databases
* **UTF-8 Encoding**: Supports international characters and domains

## CSV File Structure

The validation results CSV typically includes these columns:

| Column               | Description                                       |
| -------------------- | ------------------------------------------------- |
| `email`              | Original email address                            |
| `status`             | Overall validation result (valid/invalid/unknown) |
| `normalized_email`   | Cleaned/normalized version of the email           |
| `is_disposable`      | Whether email is from disposable service          |
| `is_role_account`    | Whether email is a role-based account             |
| `type`               | Email type classification                         |
| `mx_records`         | MX records for the domain                         |
| `validation_reasons` | Detailed breakdown of validation checks           |
| `dmarc_policy`       | DMARC policy information                          |
| `created_date`       | When the validation was performed                 |

## Important Notes

<Note>
  **Validation Required**: This endpoint only works with files that have been
  processed through the validation workflow and have a status of "validated".
</Note>

<Tip>
  **Download Immediately**: For best results, download the file as soon as you
  receive the URL to avoid potential expiration.
</Tip>

<Warning>
  **URL Security**: Keep download URLs confidential as they provide temporary
  access to your validation data.
</Warning>

## Common Scenarios

### Scenario 1: File Not Validated

```json theme={null}
// If file is still processing:
{
  "error": "File is still being processed",
  "file_status": "processing",
  "progress_percentage": 65
}
```

### Scenario 2: No Validation Results

```json theme={null}
// If validation found no processable emails:
{
  "download_url": null,
  "message": "No validation results found for this file",
  "record_count": 0
}
```

### Scenario 3: Successful Download

```bash theme={null}
# Use the download_url to get your file
curl -o "validation_results.csv" "{YOUR_FILE_URL}"
```

## Error Responses

| Status Code | Description                           | Action                                |
| ----------- | ------------------------------------- | ------------------------------------- |
| `400`       | Invalid or missing file\_id parameter | Verify the file\_id value             |
| `401`       | Unauthorized access                   | Check your API key                    |
| `404`       | File not found or not accessible      | Ensure file exists and belongs to you |
| `409`       | File not ready for download           | Wait for validation to complete       |

## Prerequisites

<Note>
  **Required Steps**: 1. Upload file using [File
  Upload](/api-reference/endpoint/file_upload) 2. Validate file using [Validate
  Email Addresses](/api-reference/endpoint/validate_emails) 3. Wait for
  validation to complete (status = "validated") 4. Use this endpoint to get
  download URL
</Note>

## Download Workflow Example

```bash theme={null}
# 1. Check file status first
curl -X GET "https://base.sanitizeemail.com/v1/api/filesupload/740" \
  -H "X-API-KEY: YOUR_API_KEY"

# Response should show: "status": "validated"

# 2. Get download URL
curl -X GET "https://base.sanitizeemail.com/v1/api/email-validation/download-validation-results/?file_id=740" \
  -H "X-API-KEY: YOUR_API_KEY"

# 3. Download the file
curl -o "validation_results.csv" "DOWNLOAD_URL_FROM_RESPONSE"
```

## Differences from Clean List Download

<CardGroup>
  <Card title="Clean List Download" icon="broom">
    **Content**: Only valid emails that passed all checks **Use Case**: Email
    marketing campaigns, direct outreach **File Size**: Smaller (filtered data)
  </Card>

  <Card title="Validation Results Download" icon="chart-bar">
    **Content**: All emails with detailed validation analysis **Use Case**: Data
    analysis, reporting, compliance **File Size**: Larger (comprehensive data)
  </Card>
</CardGroup>

## Integration Tips

<CardGroup>
  <Card title="Data Analysis" icon="magnifying-glass-chart">
    **Business Intelligence**: Import into BI tools for email quality insights
    and trends
  </Card>

  <Card title="Compliance Reporting" icon="file-contract">
    **Audit Trail**: Maintain detailed records of email validation for
    compliance purposes
  </Card>

  <Card title="Quality Monitoring" icon="gauge-high">
    **Performance Tracking**: Monitor email list quality over time with detailed
    metrics
  </Card>

  <Card title="Integration Workflows" icon="arrows-rotate">
    **Data Pipelines**: Feed validation results into CRM systems or marketing
    automation platforms
  </Card>
</CardGroup>

## Related Endpoints

<CardGroup>
  <Card title="View Validation Results" icon="list">
    Use [View Validation Results](/api-reference/endpoint/validation_result) to
    preview validation data before downloading
  </Card>

  <Card title="Validate Email Addresses" icon="envelope-circle-check">
    Use [Validate Email Addresses](/api-reference/endpoint/validate_emails) to
    initiate the validation process
  </Card>
</CardGroup>


# Upload CSV or XLSX
Source: https://docs.sanitizeemail.com/api-reference/endpoint/file_upload

POST /v1/api/filesupload/
Upload CSV or XLSX files for bulk email validation with automatic email column detection

This endpoint allows users to upload CSV or XLSX files for bulk email validation. It supports both organized files (with headers) and unorganized files, with intelligent email column detection.

## How it Works

<Steps>
  <Step title="Upload File">
    Submit your CSV or XLSX file with the required parameters
  </Step>

  <Step title="Column Detection">
    If `is_file_organised` is true, the API automatically detects email columns
  </Step>

  <Step title="Column Selection (if needed)">
    If no email column is found, you'll receive suggestions to choose the
    correct column
  </Step>

  <Step title="Processing">
    Resubmit with the chosen `email_column` to start validation
  </Step>
</Steps>

## Important Notes

<Note>
  **Column Selection**: You can always provide an `email_column` parameter, even
  on the first upload. It's particularly useful when you know the exact column
  name containing email addresses.
</Note>

<Warning>
  **File Resubmission**: If you receive a 200 response with `available_columns`,
  resubmit the same file with the chosen `email_column` to proceed with
  processing.
</Warning>

<Tip>
  **File Organization**: Set `is_file_organised=false` for files without headers
  or with inconsistent structure. The API will attempt to detect emails from the
  raw data.
</Tip>


# Validate Emails
Source: https://docs.sanitizeemail.com/api-reference/endpoint/validate_emails

POST /v1/api/email-validation/
Validate one or more email addresses for syntax, domain, deliverability, and SMTP checks

This endpoint validates email addresses using two different methods: direct email validation or file-based validation. You can either provide individual email addresses or reference a previously uploaded file.

## Validation Methods

<Tabs>
  <Tab title="Direct Email Validation">
    Validate individual email addresses by providing them directly in the request.

    ```json theme={null}
    {
      "emails": ["test@example.com", "user@domain.com"],
      "options": {
        "validate_smtp": true,
        "validate_syntax": true,
        "check_dmarc": true,
        "validate_mx": true
      }
    }
    ```
  </Tab>

  <Tab title="File-Based Validation">
    Validate emails from a previously uploaded file using the file ID.

    ```json theme={null}
    {
      "file_id": 740,
      "file_tag": "validate",
      "options": {
        "validate_smtp": true,
        "validate_syntax": true,
        "check_dmarc": true,
        "validate_mx": true
      }
    }
    ```
  </Tab>
</Tabs>

## How it Works

<Steps>
  <Step title="Choose Validation Method">
    Decide whether to validate individual emails directly or use a file-based
    approach
  </Step>

  <Step title="For File-Based: Upload File First (Optional)">
    If using file-based validation, first upload your CSV or XLSX file using the
    [File Upload endpoint](/api-reference/endpoint/file_upload) to obtain the
    `file_id`
  </Step>

  <Step title="Configure Validation Options">
    Set your desired validation options (syntax, DMARC, SMTP, MX records)
  </Step>

  <Step title="Submit Validation Request">
    Send either `emails` array OR `file_id` (not both)
  </Step>

  <Step title="Receive Results">
    Get validation results for the submitted emails
  </Step>
</Steps>

## Request Parameters

<Note>
  **Either/Or Requirement**: You must provide either `emails` OR `file_id`, but
  not both in the same request.
</Note>

### Direct Email Validation

* **emails**: Array of email addresses to validate
* **options**: Validation options object

### File-Based Validation

* **file\_id**: ID from a previously uploaded file
* **file\_tag**: Tag for categorizing the validation type
* **options**: Validation options object

## Validation Options

Configure which validation checks to perform:

* **validate\_syntax**: Checks email format and structure (default: true)
* **validate\_smtp**: Performs SMTP server validation (default: false)
* **check\_dmarc**: Validates DMARC policy records (default: false)
* **validate\_mx**: Checks MX record existence (default: false)

## Example Workflows

### Direct Email Validation

```json theme={null}
POST /v1/api/email-validation/
{
  "emails": ["john@example.com", "sarah@company.com"],
  "options": {
    "validate_syntax": true,
    "validate_smtp": true,
    "check_dmarc": false,
    "validate_mx": true
  }
}
```

### File-Based Validation

```json theme={null}
// 1. First upload a file (if not already done)
POST /v1/api/filesupload/
// Response includes: { "id": 740, "file": "https://s3.../file.csv" }

// 2. Then validate the uploaded file
POST /v1/api/email-validation/
{
  "file_id": 740,
  "file_tag": "validate",
  "options": {
    "validate_smtp": true,
    "validate_syntax": true,
    "check_dmarc": true,
    "validate_mx": true
  }
}
```

<Warning>
  **Credits Consumption**: Validation consumes credits based on the number of
  emails and validation options selected. More comprehensive validation uses
  more credits.
</Warning>

<Tip>
  **Bulk Processing**: For validating large lists of emails, use the file-based
  approach with the File Upload endpoint for better performance and easier
  management.
</Tip>


# View Validation Results
Source: https://docs.sanitizeemail.com/api-reference/endpoint/validation_result

GET /v1/api/email-validation/
Retrieves a paginated list of detailed validation results for a file that has been processed. This endpoint should be used after a file's status is 'validated'.

This endpoint retrieves validation results in two different modes: file-based validation results or individual email validation history. The response format changes based on the query parameters you provide.

## Validation Result Types

<Tabs>
  <Tab title="File-Based Results">
    Get detailed validation results for emails processed from an uploaded file.
    **Required Parameter**: `file_id` Use this to review the outcome for each
    email after a file validation job is complete.
  </Tab>

  <Tab title="Individual Email History">
    Get a history of all individual emails you've validated directly through the
    API. **Required Parameter**: `type=list` Use this to review your validation
    history for emails submitted via the `emails` array.
  </Tab>
</Tabs>

## How it Works

<Steps>
  <Step title="Choose Your Method">
    Decide whether you want file-based validation results or individual
    validation history
  </Step>

  <Step title="For File-Based Results">
    Use `file_id` parameter with the ID from a previously uploaded and validated
    file
  </Step>

  <Step title="For Individual History">
    Use `type=list` parameter to retrieve your individual email validation
    records
  </Step>

  <Step title="Navigate Results">
    Use pagination parameters to browse through large result sets
  </Step>
</Steps>

## Example Usage

### File-Based Validation Results

```bash theme={null}
curl -X GET "https://base.sanitizeemail.com/v1/api/email-validation/?file_id=740&size=20&page=1" \
  -H "X-API-KEY: YOUR_API_KEY"
```

### Individual Email Validation History

```bash theme={null}
curl -X GET "https://base.sanitizeemail.com/v1/api/email-validation/?type=list&size=20&page=1" \
  -H "X-API-KEY: YOUR_API_KEY"
```

## Query Parameters

| Parameter | Type    | Required | Description                            | Default |
| --------- | ------- | -------- | -------------------------------------- | ------- |
| `file_id` | integer | No\*     | File ID for file-based results         | -       |
| `type`    | string  | No\*     | Set to `"list"` for individual history | -       |
| `size`    | integer | No       | Number of results per page (1-100)     | 10      |
| `page`    | integer | No       | Page number for pagination             | 1       |

<Note>
  **Mutually Exclusive**: You must provide either `file_id` OR `type=list`, but
  not both.
</Note>

## Response Formats

### File-Based Validation Results

```json theme={null}
{
  "count": 245,
  "next": "https://base.sanitizeemail.com/v1/api/email-validation/?file_id=740&page=2&size=20",
  "previous": null,
  "results": [
    {
      "id": 2847291,
      "file_id": {
        "id": 740,
        "name": "Marketing Campaign List",
        "file_name": "prospects.xlsx",
        "status": "validated",
        "total_email": 250,
        "clean_email_count": 198,
        "bounce_rate": 0.208
      },
      "validation_stats": {
        "total_uploaded": 250,
        "processed": 245,
        "valid": 198,
        "invalid": 47,
        "unknown": 0,
        "error": 0,
        "dropped": 5
      },
      "email": "contact@example.com",
      "normalized_email": "contact@example.com",
      "status": "valid",
      "reason": "{\"format\":{\"status\":\"pass\",\"reason\":\"Valid email format\"},\"dns\":{\"status\":\"pass\",\"reason\":\"Domain exists\"},\"mx\":{\"status\":\"pass\",\"reason\":\"MX records found\"},\"smtp\":{\"status\":\"pass\",\"reason\":\"Mailbox exists\"},\"dmarc\":{\"status\":\"pass\",\"reason\":\"DMARC policy found\"}}",
      "is_disposable": false,
      "type": "business",
      "is_role_account": false,
      "mx_records": "mx1.example.com,mx2.example.com",
      "dns_validation_time": 0.125,
      "smtp_validation_time": 0.34,
      "dmarc_record": {
        "policy": "quarantine",
        "subdomain_policy": "none"
      },
      "created_date": "2025-07-14T10:30:15.123456+05:45"
    }
  ]
}
```

### Individual Email Validation History

```json theme={null}
{
  "count": 15,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 23992475,
      "file_id": null,
      "validation_stats": {
        "total_uploaded": 15,
        "processed": 15,
        "valid": 12,
        "invalid": 3,
        "unknown": 0,
        "error": 0,
        "dropped": 0
      },
      "email": "hi@vrittechnologies.com",
      "normalized_email": "hi@vrittechnologies.com",
      "status": "valid",
      "reason": {
        "mx": {
          "reason": "MX records found: aspmx.l.google.com, alt1.aspmx.l.google.com, alt2.aspmx.l.google.com, alt3.aspmx.l.google.com, alt4.aspmx.l.google.com",
          "status": "pass"
        },
        "dns": {
          "reason": "Resolved domain successfully",
          "status": "pass"
        },
        "smtp": {
          "reason": "SMTP check passed",
          "status": "pass"
        },
        "dmarc": {
          "reason": "DMARC policy = none",
          "status": "pass"
        },
        "format": {
          "reason": "Valid email syntax and domain format",
          "status": "pass"
        }
      },
      "is_disposable": false,
      "type": "list",
      "is_role_account": false,
      "mx_records": "aspmx.l.google.com,alt1.aspmx.l.google.com,alt2.aspmx.l.google.com,alt3.aspmx.l.google.com,alt4.aspmx.l.google.com",
      "dns_validation_time": null,
      "smtp_validation_time": null,
      "dmarc_record": {
        "v": "dmarc1",
        "policy": "none",
        "record": "v=DMARC1; p=none;"
      },
      "created_date": "2025-07-14T15:17:18.996710+05:45",
      "created_at": "2025-07-14",
      "updated_date": "2025-07-14T15:17:18.996765+05:45",
      "metadata": {
        "validation_options": {
          "mx": true,
          "role": true,
          "smtp": true,
          "dmarc": true,
          "syntax": true,
          "blacklist": true,
          "disposable": true
        }
      },
      "user": 100,
      "workspace": 100
    }
  ]
}
```

## When to Use Each Method

<CardGroup>
  <Card title="File-Based Results" icon="file-text">
    **Use When**: You want detailed results for emails from an uploaded file
    **Best For**: - Bulk validation analysis - File processing review - Detailed
    email-by-email breakdown
  </Card>

  <Card title="Individual History" icon="user">
    **Use When**: You want to review individual emails validated directly **Best
    For**: - Validation history audit - API usage tracking - Individual email
    analysis
  </Card>
</CardGroup>

## Key Differences Between Response Types

| Feature    | File-Based Results                   | Individual History          |
| ---------- | ------------------------------------ | --------------------------- |
| `file_id`  | Contains file details object         | Always `null`               |
| `type`     | Shows email type (business/personal) | Always `"list"`             |
| `reason`   | JSON string format                   | Object format               |
| `metadata` | Basic source info                    | Detailed validation options |
| Use Case   | Bulk file analysis                   | Individual tracking         |

## Validation Status Types

<CardGroup>
  <Card title="Valid" icon="circle-check">
    Email passed all validation checks and is deliverable
  </Card>

  <Card title="Invalid" icon="circle-xmark">
    Email failed one or more validation checks
  </Card>

  <Card title="Unknown" icon="circle-question">
    Validation result inconclusive (temporary issues)
  </Card>
</CardGroup>

## Understanding Validation Reasons

### File-Based Results (JSON String Format)

```json theme={null}
"{\"format\":{\"status\":\"pass\",\"reason\":\"Valid email format\"},\"dns\":{\"status\":\"pass\",\"reason\":\"Domain exists\"},\"mx\":{\"status\":\"fail\",\"reason\":\"No MX records found\"}}"
```

### Individual History (Object Format)

```json theme={null}
{
  "format": {
    "status": "pass",
    "reason": "Valid email format"
  },
  "dns": {
    "status": "pass",
    "reason": "Domain exists"
  },
  "mx": {
    "status": "fail",
    "reason": "No MX records found"
  }
}
```

## Prerequisites

<Tabs>
  <Tab title="For File-Based Results">
    <Note>
      **Required Steps**: 1. Upload file using [File
      Upload](/api-reference/endpoint/file_upload) 2. Validate file using
      [Validate Email Addresses](/api-reference/endpoint/validate_emails) 3.
      Wait for processing to complete 4. Retrieve results with this endpoint
    </Note>
  </Tab>

  <Tab title="For Individual History">
    <Note>
      **Required Steps**: 1. Perform individual validations using [Validate
      Email Addresses](/api-reference/endpoint/validate_emails) with `emails`
      array 2. Use this endpoint with `type=list` to view history
    </Note>
  </Tab>
</Tabs>

## Empty Results Scenarios

<Warning>
  **Empty Results**: If the response contains no results, check the following:
</Warning>

### For File-Based Results

| File Status  | Meaning                              | Action Required           |
| ------------ | ------------------------------------ | ------------------------- |
| `processing` | Validation in progress               | Wait for completion       |
| `validated`  | Validation complete, no valid emails | All emails were invalid   |
| `failed`     | Processing failed                    | Check error logs or retry |

### For Individual History

* **No individual validations performed**: You haven't used the direct email validation method yet
* **All validations were file-based**: Individual history only shows direct `emails` array validations

## Error Responses

| Status Code | Description                                      | Action                                   |
| ----------- | ------------------------------------------------ | ---------------------------------------- |
| `400`       | Invalid parameters or missing required parameter | Check `file_id` or `type=list` parameter |
| `401`       | Unauthorized access                              | Verify your API key                      |
| `404`       | File not found (for file-based requests)         | Ensure file exists and belongs to you    |

## Related Endpoints

<CardGroup>
  <Card title="Validate Emails" icon="envelope">
    Use [Validate Emails](/api-reference/endpoint/validate_emails) to perform
    new validations
  </Card>

  <Card title="File Upload" icon="upload">
    Use [File Upload](/api-reference/endpoint/file_upload) to upload files for
    validation
  </Card>

  <Card title="Clean List Results" icon="broom">
    Use [Clean List Results](/api-reference/endpoint/clean_list_result) for
    cleaned email lists
  </Card>
</CardGroup>


# List Uploaded Files
Source: https://docs.sanitizeemail.com/api-reference/endpoint/view_all_files

GET /v1/api/filesupload/
Retrieve a paginated list of uploaded files with optional filtering by file tag

This endpoint retrieves a paginated list of uploaded files with optional filtering capabilities. You can filter by file purpose and control pagination through query parameters.

## Query Parameters

All parameters are optional and can be combined:

* **file\_tag**: Filter files by their processing purpose (`clean`, `validate`, `analyze`)
* **size**: Number of files to return per page (1-100, default: 10)
* **page**: Page number for pagination (starts from 1)

## How it Works

<Steps>
  <Step title="Set Filter Criteria (Optional)">
    Choose a file\_tag to filter by processing purpose, or omit to see all files
  </Step>

  <Step title="Configure Pagination (Optional)">
    Set size and page parameters to control how many files are returned and
    which page to view
  </Step>

  <Step title="Make Request">
    Send a GET request with your chosen parameters
  </Step>

  <Step title="Navigate Results">
    Use the next/previous URLs in the response for easy pagination
  </Step>
</Steps>

## Response Structure

The response follows a standard pagination format:

### Pagination Meta

* **count**: Total number of files matching your query
* **next**: URL for the next page (null if on last page)
* **previous**: URL for the previous page (null if on first page)

### File Results

Each file in the results array contains the same detailed information as the [individual file endpoint](/api-reference/endpoint/view_file).

## Example Usage

<Tabs>
  <Tab title="All Files">
    Get all files with default pagination: `bash GET /v1/api/filesupload/ `
  </Tab>

  <Tab title="Filter by Purpose">
    Get only validation files: `bash GET
            /v1/api/filesupload/?file_tag=validate `
  </Tab>

  <Tab title="Custom Pagination">
    Get 6 files per page, starting from page 2: `bash GET
            /v1/api/filesupload/?size=6&page=2 `
  </Tab>

  <Tab title="Combined Filters">
    Get analyze files with custom pagination: `bash GET
            /v1/api/filesupload/?file_tag=analyze&size=6&page=2 `
  </Tab>
</Tabs>

## File Tag Filtering

Use the `file_tag` parameter to filter files by their processing purpose:

<CardGroup>
  <Card title="Clean Files" icon="broom">
    **file\_tag=clean** Files uploaded for email cleaning and removal of invalid
    addresses
  </Card>

  <Card title="Validate Files" icon="check-circle">
    **file\_tag=validate** Files uploaded for email validation and deliverability
    checking
  </Card>

  <Card title="Analyze Files" icon="chart-line">
    **file\_tag=analyze** Files uploaded for detailed email analysis and insights
  </Card>
</CardGroup>

## Response Example

```json theme={null}
{
  "count": 7,
  "next": "https://base.sanitizeemail.com/v1/api/filesupload/?file_tag=validate&page=3&size=6",
  "previous": "https://base.sanitizeemail.com/v1/api/filesupload/?file_tag=validate&page=1&size=6",
  "results": [
    {
      "id": 745,
      "name": "Customer Email List",
      "file_name": "customers.csv",
      "file_size": "328",
      "status": "validated",
      "user": {
        "id": 100,
        "username": "asim",
        "email": "cool@gmail.com"
      },
      "file": "https://s3.us-east-1.amazonaws.com/sanitizeemail/email_validation_files/customers_uJWaJWs.csv",
      "file_tag": "validate",
      "total_email": 8,
      "billable_email": 4,
      "duplicate_email": 4,
      "dropped_email": 0,
      "clean_email_count": 4,
      "bounced_email": 0,
      "bounce_rate": 0,
      "created_date": "2025-07-13T10:35:04.351377+05:45",
      "is_file_organised": false,
      "progress_percentage": 100,
      "updated_date": "2025-07-13T10:35:07.923638+05:45",
      "valid_emails_count": 4,
      "invalid_emails_count": 0,
      "clean_email_id": null,
      "validate_email_id": 23990312
    }
  ]
}
```

## Use Cases

<CardGroup>
  <Card title="File Management" icon="folder">
    Browse and manage all your uploaded files in one place
  </Card>

  <Card title="Status Monitoring" icon="activity">
    Check the processing status of multiple files at once
  </Card>

  <Card title="Filtered Views" icon="filter">
    View files by their processing purpose (clean, validate, analyze)
  </Card>

  <Card title="Batch Operations" icon="layers">
    Prepare for batch operations by getting file IDs and URLs
  </Card>
</CardGroup>

<Note>
  **Pagination**: The API uses cursor-based pagination. Use the `next` and
  `previous` URLs provided in the response for seamless navigation between
  pages.
</Note>

<Tip>
  **Performance**: For large file collections, use filtering and pagination to
  improve response times and reduce bandwidth usage.
</Tip>


# View File Details
Source: https://docs.sanitizeemail.com/api-reference/endpoint/view_file

GET /v1/api/filesupload/{file_id}
Retrieve details of a previously uploaded file including processing status, statistics, and metadata

This endpoint retrieves detailed information about a previously uploaded file, including processing status, email statistics, and metadata.

## Path Parameters

The file ID is required in the URL path:

* **file\_id**: The unique identifier of the uploaded file (obtained from the file upload response)

## How it Works

<Steps>
  <Step title="Get File ID">
    Obtain the file ID from a previous file upload response or file listing
  </Step>

  <Step title="Make Request">
    Send a GET request to `/v1/api/filesupload/{file_id}` replacing `{file_id}`
    with the actual file ID
  </Step>

  <Step title="Receive File Details">
    Get comprehensive information about the file including processing status and
    statistics
  </Step>
</Steps>

## Response Information

The response includes comprehensive file information:

### File Metadata

* **Basic Info**: ID, name, filename, size, status
* **User Info**: Owner details (ID, username, email)
* **File URL**: Direct link to access the uploaded file
* **Timestamps**: Creation and last update dates

### Processing Statistics

* **Email Counts**: Total, billable, duplicate, dropped emails
* **Validation Results**: Valid, invalid, clean email counts
* **Quality Metrics**: Bounce rate, progress percentage
* **Job IDs**: References to cleaning or validation jobs

### File Status

The `status` field indicates the current processing state:

* **pending**: File uploaded but not yet processed
* **processing**: File is currently being processed
* **validated**: Email validation completed
* **cleaned**: Email cleaning completed
* **failed**: Processing failed

## Example Usage

```bash theme={null}
# Get details for file ID 740
GET /v1/api/filesupload/740/
```

```json theme={null}
{
  "id": 740,
  "name": "Customer Email List",
  "file_name": "Book Sheet1.csv",
  "file_size": "328",
  "status": "validated",
  "user": {
    "id": 100,
    "username": "test_user",
    "email": "cool@gmail.com"
  },
  "file": "https://s3.us-east-1.amazonaws.com/sanitizeemail/email_validation_files/Book_Sheet1_wsLgoJw.csv",
  "file_tag": "validate",
  "total_email": 8,
  "billable_email": 4,
  "duplicate_email": 4,
  "dropped_email": 0,
  "clean_email_count": 4,
  "bounced_email": 0,
  "bounce_rate": 0,
  "created_date": "2025-07-11T16:58:10.078456+05:45",
  "is_file_organised": false,
  "progress_percentage": 100,
  "updated_date": "2025-07-11T16:59:00.456247+05:45",
  "valid_emails_count": 4,
  "invalid_emails_count": 0,
  "clean_email_id": null,
  "validate_email_id": 23990312
}
```

## Use Cases

<CardGroup>
  <Card title="Check Processing Status" icon="clock">
    Monitor the progress of file processing and validation jobs
  </Card>

  <Card title="Get Email Statistics" icon="chart-bar">
    Retrieve detailed statistics about email quality and counts
  </Card>

  <Card title="Access File URL" icon="link">
    Get the direct URL to download or access the processed file
  </Card>

  <Card title="Track Job References" icon="list-check">
    Find associated cleaning or validation job IDs for further operations
  </Card>
</CardGroup>

<Note>
  **File ID Source**: The file ID is returned when you upload a file using the
  [File Upload endpoint](/api-reference/endpoint/file_upload). Make sure to save
  this ID for future reference.
</Note>

<Tip>
  **Status Monitoring**: Use this endpoint to poll for status updates when
  processing large files. Check the `progress_percentage` field for real-time
  progress updates.
</Tip>


# Introduction
Source: https://docs.sanitizeemail.com/api-reference/introduction

Sanitize-Email API Documentation - Powerful email validation and management tool

## Welcome to the Sanitize-Email API.

The Sanitize-Email API provides a comprehensive email validation and management solutions for developers and businesses. Our API offers powerful tools for email validation, subscription management, API key administration, and payment integration.

<Card title="Get Your API Key" icon="key" href="https://app.sanitizeemail.com/api-key">
  Access your API key from this URL [https://app.sanitizeemail.com/api-key](https://app.sanitizeemail.com/api-key). You can use this API key in this docs or in your own app to validate emails and manage your account.
</Card>

## Core Features

<CardGroup>
  <Card title="Email Validation" icon="envelope-circle-check">
    Validate email addresses for syntax, domain, and deliverability with bulk
    validation support
  </Card>

  <Card title="API Key Management" icon="shield-keyhole">
    Securely generate and manage API keys for authentication
  </Card>
</CardGroup>

## Authentication

All API endpoints require authentication using your API key. Include your API key in the `X-API-KEY` header with every request:

```http theme={null}
X-API-KEY: YOUR_API_KEY
```

<Warning>
  Keep your API key secure and never expose it in client-side code. You can
  obtain your API key from the [Sanitize-Email
  dashboard](https://app.sanitizeemail.com/api-key).
</Warning>

## Getting Started

1. **Get Your API Key**: Visit [https://app.sanitizeemail.com/api-key](https://app.sanitizeemail.com/api-key) to retrieve your API key
2. **Choose Your Plan**: Select from subscription plans or use pay-as-you-go credits
3. **Start Validating**: Use our endpoints to validate emails and manage your account

## Support & Contact

<CardGroup>
  <Card title="Contact Us" icon="envelope">
    **Email**: [support@sanitizeemail.com](mailto:support@sanitizeemail.com)
  </Card>

  <Card title="Visit Our Website" icon="globe">
    **URL**: [sanitizeemail.com](https://sanitizeemail.com)
  </Card>
</CardGroup>

<Note>
  This API operates under a Proprietary License. Please review our [Terms of
  service](https://sanitizeemail.com/terms-of-service) before integration.
</Note>

## What's Next?

Explore our API endpoints to start validating emails


# Introduction
Source: https://docs.sanitizeemail.com/index

Powerful email validation and management API for developers and businesses

<img alt="Cover" />

## Welcome to Sanitize-Email API

The Sanitize-Email API provides comprehensive email validation and management solutions for developers and businesses. Validate email addresses for syntax, domain deliverability, and SMTP checks with our powerful REST API.

<CardGroup>
  <Card title="Get Started Quickly" icon="rocket" href="/quickstart">
    Start validating emails in minutes with our quickstart guide
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore our complete API documentation and endpoints
  </Card>
</CardGroup>

## Core Features

<CardGroup>
  <Card title="Email Validation" icon="envelope-circle-check">
    Validate email addresses for syntax, domain, and deliverability with bulk
    validation support
  </Card>

  <Card title="SMTP Verification" icon="server">
    Real-time SMTP checks to verify email deliverability
  </Card>

  <Card title="Bulk Processing" icon="list">
    Process thousands of emails efficiently with batch validation
  </Card>

  <Card title="API Key Management" icon="shield-keyhole">
    Securely generate and manage API keys for authentication
  </Card>
</CardGroup>

## Quick Example

Here's a simple example of validating an email address:

```bash theme={null}
curl -X POST https://base.sanitizeemail.com/v1/api/email-validation/ \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "emails": ["test@example.com"],
    "options": {
      "validate_smtp": true
    }
  }'
```

## Authentication

All API endpoints require authentication using your API key in the `X-API-KEY` header:

```http theme={null}
X-API-KEY: YOUR_API_KEY
```

<Card title="Get Your API Key" icon="key" href="https://app.sanitizeemail.com/api-key">
  Access your API key from the Sanitize-Email dashboard
</Card>

## Support & Contact

<CardGroup>
  <Card title="Contact Us" icon="envelope">
    **Email**: [support@sanitizeemail.com](mailto:support@sanitizeemail.com)
  </Card>

  <Card title="Visit Our Website" icon="globe">
    **URL**: [sanitizeemail.com](https://sanitizeemail.com)
  </Card>
</CardGroup>

<Note>
  This API operates under a Proprietary License. Please review our [Terms of
  Service](https://sanitizeemail.com/terms-of-service) before integration.
</Note>


# Quickstart Guide
Source: https://docs.sanitizeemail.com/quickstart

Start validating emails with Sanitize-Email API in under 5 minutes

## Get Your API Key

Before you can start validating emails, you'll need to get your API key from the Sanitize-Email dashboard.

<Steps>
  <Step title="Visit the Dashboard">
    Go to
    [https://app.sanitizeemail.com/api-key](https://app.sanitizeemail.com/api-key)
    to access your API key.
  </Step>

  <Step title="Copy Your API Key">
    Copy the API key from your dashboard - you'll need this for authentication.
  </Step>

  <Step title="Choose Your Plan">
    Select from subscription plans or use pay-as-you-go credits based on your
    needs.
  </Step>
</Steps>

## Make Your First Request

Once you have your API key, you can start validating emails immediately. Here's how to validate a single email address:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://base.sanitizeemail.com/v1/api/email-validation/ \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_API_KEY" \
    -d '{
      "emails": ["user@example.com"],
      "options": {
        "validate_smtp": true
      },
      "file_tag": "quickstart-test"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://base.sanitizeemail.com/v1/api/email-validation/",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "YOUR_API_KEY",
      },
      body: JSON.stringify({
        emails: ["user@example.com"],
        options: {
          validate_smtp: true,
        },
        file_tag: "quickstart-test",
      }),
    },
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://base.sanitizeemail.com/v1/api/email-validation/"
  headers = {
      "Content-Type": "application/json",
      "X-API-KEY": "YOUR_API_KEY"
  }
  data = {
      "emails": ["user@example.com"],
      "options": {
          "validate_smtp": True
      },
      "file_tag": "quickstart-test"
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  print(result)
  ```
</CodeGroup>

## Understanding the Response

The API will return detailed validation results for each email:

```json theme={null}
{
  "results": [
    {
      "email": "user@example.com",
      "status": "valid",
      "normalized_email": "user@example.com",
      "is_disposable": false,
      "is_role_account": false,
      "reason": {
        "format": {
          "status": "pass",
          "reason": "Valid email format"
        },
        "dns": {
          "status": "pass",
          "reason": "Domain exists"
        },
        "mx": {
          "status": "pass",
          "reason": "MX records found"
        },
        "smtp": {
          "status": "pass",
          "reason": "SMTP server responds"
        }
      },
      "mx_records": ["mx1.example.com", "mx2.example.com"]
    }
  ],
  "stats": {
    "total": 1,
    "valid": 1,
    "invalid": 0,
    "disposable": 0,
    "role_accounts": 0
  },
  "credits_used": 1,
  "remaining_processing": 0,
  "batch_size": 1
}
```

## Bulk Email Validation

You can validate multiple emails in a single request for efficient bulk processing:

```json theme={null}
{
  "emails": ["user1@example.com", "user2@domain.com", "test@company.org"],
  "options": {
    "validate_smtp": true
  },
  "file_tag": "bulk-validation"
}
```

## Validation Options

<AccordionGroup>
  <Accordion title="SMTP Validation">
    Set `validate_smtp: true` to perform real-time SMTP checks. This provides
    the most accurate validation but takes longer.
  </Accordion>

  <Accordion title="File Tags">
    Use `file_tag` to organize and identify your validation batches for easier
    tracking.
  </Accordion>

  <Accordion title="Rate Limits">
    The API has rate limits to ensure optimal performance. Check the response
    headers for rate limit information.
  </Accordion>
</AccordionGroup>

## Error Handling

Always check for errors in your API responses:

* **400**: Bad request - Invalid payload format
* **401**: Unauthorized - Missing or invalid API key
* **403**: Forbidden - API key is inactive
* **429**: Rate limit exceeded

<Warning>
  Keep your API key secure and never expose it in client-side code. Store it as
  an environment variable or in a secure configuration file.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Explore API Reference" icon="book" href="/api-reference/introduction">
    Dive deeper into our complete API documentation
  </Card>

  <Card title="Email Validation Endpoint" icon="envelope-circle-check" href="/api-reference/endpoint/validate_emails">
    Learn about all validation parameters and response fields
  </Card>
</CardGroup>

## Need Help?

<CardGroup>
  <Card title="Contact Support" icon="envelope">
    **Email**: [support@sanitizeemail.com](mailto:support@sanitizeemail.com)
  </Card>

  <Card title="Visit Our Website" icon="globe">
    **URL**: [sanitizeemail.com](https://sanitizeemail.com)
  </Card>
</CardGroup>