> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sanitizeemail.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Download Clean List

> 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 cols={2}>
  <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 cols={2}>
  <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 cols={2}>
  <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 cols={2}>
  <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>


## OpenAPI

````yaml GET /v1/api/cleanedemail/download-cleaned-emails/
openapi: 3.1.0
info:
  title: Sanitize-Email API (v1)
  description: Welcome to the Sanitize-Email API Documentation
  license:
    name: Proprietary License
  version: 1.0.0
servers:
  - url: https://base.sanitizeemail.com
security:
  - apiKeyAuth: []
paths:
  /v1/api/cleanedemail/download-cleaned-emails/:
    get:
      tags:
        - Email Cleaning
      summary: Download Clean Email List
      description: >-
        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.
      parameters:
        - $ref: '#/components/parameters/FileIdQueryRequired'
      responses:
        '200':
          description: Download URL generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CleanEmailDownloadResponse'
        '400':
          description: Bad Request - Invalid or missing file_id parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict - File not ready for download
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: File is still being processed
                file_status: processing
                progress_percentage: 75
components:
  parameters:
    FileIdQueryRequired:
      name: file_id
      in: query
      required: true
      schema:
        type: integer
      description: The ID of the file for which to generate a download URL.
      example: 757
  schemas:
    CleanEmailDownloadResponse:
      type: object
      properties:
        download_url:
          type: string
          format: uri
          description: Secure pre-signed URL for downloading the cleaned email file
        filename:
          type: string
          description: Name of the generated clean email file
        file_id:
          type: string
          description: ID of the original file that was cleaned
        record_count:
          type: integer
          description: Number of clean emails in the downloadable file
        format:
          type: string
          enum:
            - csv
          description: File format of the downloadable file
      required:
        - download_url
        - filename
        - file_id
        - record_count
        - format
      example:
        download_url: '{YOUR_DOWNLOAD_URL}'
        filename: your_cleaned_emails.csv
        file_id: '{id}'
        record_count: 172
        format: csv
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: File not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

````