> ## 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.

# View Validation Results

> 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 cols={2}>
  <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 cols={3}>
  <Card title="Valid" icon="circle-check" color="#22c55e">
    Email passed all validation checks and is deliverable
  </Card>

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

  <Card title="Unknown" icon="circle-question" color="#f59e0b">
    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 cols={3}>
  <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>


## OpenAPI

````yaml GET /v1/api/email-validation/
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/:
    get:
      tags:
        - Email Validation
      summary: Get Validation Results for a File
      description: >-
        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'.
      parameters:
        - $ref: '#/components/parameters/FileIdQuery'
        - $ref: '#/components/parameters/ValidationTypeQuery'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of validation results for the specified file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileValidationResponse'
        '400':
          description: Bad Request - Invalid or missing file_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    FileIdQuery:
      name: file_id
      in: query
      required: false
      schema:
        type: integer
      description: The ID of the file for which to retrieve results.
      example: 757
    ValidationTypeQuery:
      name: type
      in: query
      required: false
      schema:
        type: string
        enum:
          - list
      description: >-
        Type of validation results to retrieve. Use 'list' to get individual
        email validation history.
      example: list
    Size:
      name: size
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
      description: Number of results to return per page.
      example: 20
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Page number for pagination.
      example: 1
  schemas:
    FileValidationResponse:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          format: uri
          nullable: true
        previous:
          type: string
          format: uri
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/FileValidationResultDetail'
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    FileValidationResultDetail:
      type: object
      properties:
        id:
          type: integer
        file_id:
          $ref: '#/components/schemas/ValidationFileDetail'
        validation_stats:
          $ref: '#/components/schemas/ValidationRunStats'
        email:
          type: string
          format: email
        normalized_email:
          type: string
          format: email
        status:
          type: string
          enum:
            - valid
            - invalid
            - unknown
        reason:
          type: string
          description: >-
            A JSON string containing the detailed results for each validation
            check (format, dns, mx, dmarc, smtp).
        is_disposable:
          type: boolean
        type:
          type: string
        is_role_account:
          type: boolean
        mx_records:
          type: string
          description: Comma-separated list of MX records.
        dns_validation_time:
          type: number
        smtp_validation_time:
          type: number
        dmarc_record:
          type: object
        created_date:
          type: string
          format: date-time
        created_at:
          type: string
          format: date
        updated_date:
          type: string
          format: date-time
        metadata:
          type: object
          properties:
            source:
              type: string
        user:
          type: integer
        workspace:
          type: integer
    ValidationFileDetail:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        file_name:
          type: string
        file_size:
          type: string
        status:
          type: string
        file:
          type: string
          format: uri
        file_tag:
          type: string
        total_email:
          type: integer
        total_processed:
          type: integer
        billable_email:
          type: integer
        dropped_email:
          type: integer
        is_file_organised:
          type: boolean
        duplicate_email:
          type: integer
        clean_emails:
          type: object
        email_column:
          type: string
        invalid_emails_count:
          type: integer
        clean_email_count:
          type: integer
        bounced_email:
          type: integer
        progress_percentage:
          type: integer
        smtp_unreachable_count:
          type: integer
        bounce_rate:
          type: number
        created_date:
          type: string
          format: date-time
        created_at:
          type: string
          format: date
        updated_date:
          type: string
          format: date-time
        collected_emails_file:
          type: string
          format: uri
        extracted_email_count:
          type: integer
        workspace:
          type: integer
        user:
          type: integer
    ValidationRunStats:
      type: object
      properties:
        total_uploaded:
          type: integer
        processed:
          type: integer
        valid:
          type: integer
        invalid:
          type: integer
        unknown:
          type: integer
        error:
          type: integer
        dropped:
          type: integer
  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

````