Download Validation Results - Sanitize Email API Docs

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

Complete Email Validation

First use the Validate Email Addresses endpoint to process your file

Verify Validation Status

Ensure the file status is “validated” using the Get File Details endpoint

Request Download URL

Use this endpoint with the file_id to get a secure download URL

Download the File

Use the provided download_url to download your validation results

When to Use This Endpoint

Export Validation Data

Download detailed validation results for analysis, reporting, or integration

Backup Validation Results

Save validation results to your local storage or backup systems

Integration with Analytics

Import validation data into analytics platforms or business intelligence tools

Share Detailed Reports

Provide comprehensive validation reports to team members or clients

Example Usage

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

File ID Required: The file_id must correspond to a file that has been successfully validated and has a status of “validated”.

Response Format

Successful Response

{
  "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

Secure Access

Pre-signed URLs: Download URLs are secure and temporarily accessible without additional authentication

Time-Limited

Expiration: URLs typically expire after a set period for security purposes

Direct Download

Ready to Use: URLs can be used directly in browsers or download tools

CSV Format

Standard Format: Files are provided in CSV format for maximum compatibility

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

Validation Required: This endpoint only works with files that have been processed through the validation workflow and have a status of “validated”.

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

URL Security: Keep download URLs confidential as they provide temporary access to your validation data.

Common Scenarios

Scenario 1: File Not Validated

// If file is still processing:
{
  "error": "File is still being processed",
  "file_status": "processing",
  "progress_percentage": 65
}

Scenario 2: No Validation Results

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

Scenario 3: Successful Download

# 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

Required Steps: 1. Upload file using File Upload 2. Validate file using Validate Email Addresses 3. Wait for validation to complete (status = “validated”) 4. Use this endpoint to get download URL

Download Workflow Example

# 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

Clean List Download

Content: Only valid emails that passed all checks Use Case: Email marketing campaigns, direct outreach File Size: Smaller (filtered data)

Validation Results Download

Content: All emails with detailed validation analysis Use Case: Data analysis, reporting, compliance File Size: Larger (comprehensive data)

Integration Tips

Data Analysis

Business Intelligence: Import into BI tools for email quality insights and trends

Compliance Reporting

Audit Trail: Maintain detailed records of email validation for compliance purposes

Quality Monitoring

Performance Tracking: Monitor email list quality over time with detailed metrics

Integration Workflows

Data Pipelines: Feed validation results into CRM systems or marketing automation platforms

View Validation Results

Use View Validation Results to preview validation data before downloading

Validate Email Addresses

Use Validate Email Addresses to initiate the validation process

Authorizations

X-API-KEY

string

header

required

API key for authentication

Query Parameters

file_id

integer

required

The ID of the file for which to generate a download URL.

Response

Download URL generated successfully

download_url

string<uri>

required

Secure pre-signed URL for downloading the validation results file

filename

string

required

Name of the generated validation results file

file_id

string

required

ID of the original file that was validated

record_count

integer

required

Number of validation records in the downloadable file

format

enum<string>

required

File format of the downloadable file

Available options:

csv

API Documentation

File endpoints

Validation endpoints

Get Results

Download Results

​How it Works

​When to Use This Endpoint

Export Validation Data

Backup Validation Results

Integration with Analytics

Share Detailed Reports

​Example Usage

​Query Parameters

​Response Format

​Successful Response

​Response Fields

​Download URL Characteristics

Secure Access

Time-Limited

Direct Download

CSV Format

​Understanding the Downloaded File

​CSV File Structure

​Important Notes

​Common Scenarios

​Scenario 1: File Not Validated

​Scenario 2: No Validation Results

​Scenario 3: Successful Download

​Error Responses

​Prerequisites

​Download Workflow Example

​Differences from Clean List Download

Clean List Download

Validation Results Download

​Integration Tips

Data Analysis

Compliance Reporting

Quality Monitoring

Integration Workflows

​Related Endpoints

View Validation Results

Validate Email Addresses

Authorizations

Query Parameters

Response

How it Works

When to Use This Endpoint

Example Usage

Query Parameters

Response Format

Successful Response

Response Fields

Download URL Characteristics

Understanding the Downloaded File

CSV File Structure

Important Notes

Common Scenarios

Scenario 1: File Not Validated

Scenario 2: No Validation Results

Scenario 3: Successful Download

Error Responses

Prerequisites

Download Workflow Example

Differences from Clean List Download

Integration Tips

Related Endpoints