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


## OpenAPI

````yaml GET /v1/api/email-validation/download-validation-results/
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/email-validation/download-validation-results/:
    get:
      tags:
        - Email Validation
      summary: Download Validation Results
      description: >-
        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.
      parameters:
        - $ref: '#/components/parameters/FileIdQueryRequired'
      responses:
        '200':
          description: Download URL generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResultsDownloadResponse'
        '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: 65
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:
    ValidationResultsDownloadResponse:
      type: object
      properties:
        download_url:
          type: string
          format: uri
          description: Secure pre-signed URL for downloading the validation results file
        filename:
          type: string
          description: Name of the generated validation results file
        file_id:
          type: string
          description: ID of the original file that was validated
        record_count:
          type: integer
          description: Number of validation records 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: validation_results_740_1752553784.csv
        file_id: '740'
        record_count: 4
        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

````