Skip to main content
GET
/
v1
/
api
/
cleanedemail
/
download-cleaned-emails
/
Download Clean Email List
curl --request GET \
  --url https://base.sanitizeemail.com/v1/api/cleanedemail/download-cleaned-emails/ \
  --header 'X-API-KEY: <api-key>'
{
  "download_url": "{YOUR_DOWNLOAD_URL}",
  "filename": "your_cleaned_emails.csv",
  "file_id": "{id}",
  "record_count": 172,
  "format": "csv"
}
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

1

Complete Email Cleaning

First use the Clean Email List endpoint to process your file
2

Verify Cleaning Status

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

Request Download URL

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

Download the File

Use the provided download_url to download your cleaned email list

​
When to Use This Endpoint

Export Clean Data

Download validated emails for use in marketing campaigns or CRM systems

Backup Clean Lists

Save cleaned email lists to your local storage or backup systems

Integration with Tools

Import clean email lists into email marketing platforms or databases

Share Clean Results

Provide cleaned email lists to team members or clients

​
Example Usage

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

ParameterTypeRequiredDescription
file_idintegerYesID of the file with cleaned emails
File ID Required: The file_id must correspond to a file that has been successfully cleaned and has a status of “cleaned”.

​
Response Format

​
Successful Response

{
  "download_url": "{YOUR_FILE_URL}",
  "filename": "cleaned_emails_757_1752553258.csv",
  "file_id": "757",
  "record_count": 172,
  "format": "csv"
}

​
Response Fields

FieldTypeDescription
download_urlstringSecure pre-signed URL for downloading the cleaned email file
filenamestringName of the generated clean email file
file_idstringID of the original file that was cleaned
record_countintegerNumber of clean emails in the downloadable file
formatstringFile format (always “csv” for clean email lists)

​
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:
  • 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

Cleaning Required: This endpoint only works with files that have been processed through the cleaning workflow and have a status of “cleaned”.
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 cleaned email data.

​
Common Scenarios

​
Scenario 1: File Not Cleaned

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

​
Scenario 2: No Clean Emails

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

​
Scenario 3: Successful Download

# Use the download_url to get your file
curl -o "my_clean_emails.csv" "{YOUR_FILE_URL}"

​
Error Responses

Status CodeDescriptionAction
400Invalid or missing file_id parameterVerify the file_id value
401Unauthorized accessCheck your API key
404File not found or not accessibleEnsure file exists and belongs to you
409File not ready for downloadWait for cleaning to complete

​
Prerequisites

Required Steps: 1. Upload file using File Upload 2. Clean file using Clean Email List 3. Wait for cleaning to complete (status = “cleaned”) 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/{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

Automated Downloads

Scripting: Integrate this endpoint into automated workflows for regular email list cleaning

Webhook Integration

Event-Driven: Trigger downloads automatically when cleaning jobs complete

Batch Processing

Multiple Files: Process multiple files and download all clean lists in sequence

Data Pipeline

ETL Workflows: Incorporate into data processing pipelines for continuous email hygiene

View Clean Results

Use View Clean List Results to preview clean emails before downloading

Clean Email List

Use Clean Email List to initiate the cleaning 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 cleaned email file

​
filename
string
required

Name of the generated clean email file

​
file_id
string
required

ID of the original file that was cleaned

​
record_count
integer
required

Number of clean emails in the downloadable file

​
format
enum<string>
required

File format of the downloadable file

Available options:
csv