View Validation Results - Sanitize Email API Docs

Get Validation Results for a File

curl --request GET \
  --url https://base.sanitizeemail.com/v1/api/email-validation/ \
  --header 'X-API-KEY: <api-key>'

{
  "count": 123,
  "next": "<string>",
  "previous": "<string>",
  "results": [
    {
      "id": 123,
      "file_id": {
        "id": 123,
        "name": "<string>",
        "file_name": "<string>",
        "file_size": "<string>",
        "status": "<string>",
        "file": "<string>",
        "file_tag": "<string>",
        "total_email": 123,
        "total_processed": 123,
        "billable_email": 123,
        "dropped_email": 123,
        "is_file_organised": true,
        "duplicate_email": 123,
        "clean_emails": {},
        "email_column": "<string>",
        "invalid_emails_count": 123,
        "clean_email_count": 123,
        "bounced_email": 123,
        "progress_percentage": 123,
        "smtp_unreachable_count": 123,
        "bounce_rate": 123,
        "created_date": "2023-11-07T05:31:56Z",
        "created_at": "2023-12-25",
        "updated_date": "2023-11-07T05:31:56Z",
        "collected_emails_file": "<string>",
        "extracted_email_count": 123,
        "workspace": 123,
        "user": 123
      },
      "validation_stats": {
        "total_uploaded": 123,
        "processed": 123,
        "valid": 123,
        "invalid": 123,
        "unknown": 123,
        "error": 123,
        "dropped": 123
      },
      "email": "jsmith@example.com",
      "normalized_email": "jsmith@example.com",
      "reason": "<string>",
      "is_disposable": true,
      "type": "<string>",
      "is_role_account": true,
      "mx_records": "<string>",
      "dns_validation_time": 123,
      "smtp_validation_time": 123,
      "dmarc_record": {},
      "created_date": "2023-11-07T05:31:56Z",
      "created_at": "2023-12-25",
      "updated_date": "2023-11-07T05:31:56Z",
      "metadata": {
        "source": "<string>"
      },
      "user": 123,
      "workspace": 123
    }
  ]
}

GET

api

email-validation

Get Validation Results for a File

curl --request GET \
  --url https://base.sanitizeemail.com/v1/api/email-validation/ \
  --header 'X-API-KEY: <api-key>'

{
  "count": 123,
  "next": "<string>",
  "previous": "<string>",
  "results": [
    {
      "id": 123,
      "file_id": {
        "id": 123,
        "name": "<string>",
        "file_name": "<string>",
        "file_size": "<string>",
        "status": "<string>",
        "file": "<string>",
        "file_tag": "<string>",
        "total_email": 123,
        "total_processed": 123,
        "billable_email": 123,
        "dropped_email": 123,
        "is_file_organised": true,
        "duplicate_email": 123,
        "clean_emails": {},
        "email_column": "<string>",
        "invalid_emails_count": 123,
        "clean_email_count": 123,
        "bounced_email": 123,
        "progress_percentage": 123,
        "smtp_unreachable_count": 123,
        "bounce_rate": 123,
        "created_date": "2023-11-07T05:31:56Z",
        "created_at": "2023-12-25",
        "updated_date": "2023-11-07T05:31:56Z",
        "collected_emails_file": "<string>",
        "extracted_email_count": 123,
        "workspace": 123,
        "user": 123
      },
      "validation_stats": {
        "total_uploaded": 123,
        "processed": 123,
        "valid": 123,
        "invalid": 123,
        "unknown": 123,
        "error": 123,
        "dropped": 123
      },
      "email": "jsmith@example.com",
      "normalized_email": "jsmith@example.com",
      "reason": "<string>",
      "is_disposable": true,
      "type": "<string>",
      "is_role_account": true,
      "mx_records": "<string>",
      "dns_validation_time": 123,
      "smtp_validation_time": 123,
      "dmarc_record": {},
      "created_date": "2023-11-07T05:31:56Z",
      "created_at": "2023-12-25",
      "updated_date": "2023-11-07T05:31:56Z",
      "metadata": {
        "source": "<string>"
      },
      "user": 123,
      "workspace": 123
    }
  ]
}

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

File-Based Results
Individual Email History

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.

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.

How it Works

Choose Your Method

Decide whether you want file-based validation results or individual validation history

For File-Based Results

Use file_id parameter with the ID from a previously uploaded and validated file

For Individual History

Use type=list parameter to retrieve your individual email validation records

Navigate Results

Use pagination parameters to browse through large result sets

Example Usage

File-Based Validation Results

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

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

Mutually Exclusive: You must provide either file_id OR type=list, but not both.

Response Formats

File-Based Validation Results

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

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

File-Based Results

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

Individual History

Use When: You want to review individual emails validated directly Best For: - Validation history audit - API usage tracking - Individual email analysis

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

Valid

Email passed all validation checks and is deliverable

Invalid

Email failed one or more validation checks

Unknown

Validation result inconclusive (temporary issues)

Understanding Validation Reasons

File-Based Results (JSON String Format)

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

{
  "format": {
    "status": "pass",
    "reason": "Valid email format"
  },
  "dns": {
    "status": "pass",
    "reason": "Domain exists"
  },
  "mx": {
    "status": "fail",
    "reason": "No MX records found"
  }
}

Prerequisites

For File-Based Results
For Individual History

Required Steps: 1. Upload file using File Upload 2. Validate file using Validate Email Addresses 3. Wait for processing to complete 4. Retrieve results with this endpoint

Required Steps: 1. Perform individual validations using Validate Email Addresses with emails array 2. Use this endpoint with type=list to view history

Empty Results Scenarios

Empty Results: If the response contains no results, check the following:

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

Validate Emails

Use Validate Emails to perform new validations

File Upload

Use File Upload to upload files for validation

Clean List Results

Use Clean List Results for cleaned email lists

Authorizations

X-API-KEY

string

header

required

API key for authentication

Query Parameters

file_id

integer

The ID of the file for which to retrieve results.

type

enum<string>

Type of validation results to retrieve. Use 'list' to get individual email validation history.

Available options:

list

size

integer

default:10

Number of results to return per page.

Required range: 1 <= x <= 100

page

integer

default:1

Page number for pagination.

Required range: x >= 1

Response

A paginated list of validation results for the specified file.

count

integer

string<uri> | null

results

object[]

Show child attributes

View Clean List Results Download Clean List

​Validation Result Types

​How it Works

​Example Usage

​File-Based Validation Results

​Individual Email Validation History

​Query Parameters

​Response Formats

​File-Based Validation Results

​Individual Email Validation History

​When to Use Each Method

File-Based Results

Individual History

​Key Differences Between Response Types

​Validation Status Types

Valid

Invalid

Unknown

​Understanding Validation Reasons

​File-Based Results (JSON String Format)

​Individual History (Object Format)

​Prerequisites

​Empty Results Scenarios

​For File-Based Results

​For Individual History

​Error Responses

​Related Endpoints

Validate Emails

File Upload

Clean List Results

Authorizations

Query Parameters

Response

Validation Result Types

How it Works

Example Usage

File-Based Validation Results

Individual Email Validation History

Query Parameters

Response Formats

File-Based Validation Results

Individual Email Validation History

When to Use Each Method

Key Differences Between Response Types

Validation Status Types

Understanding Validation Reasons

File-Based Results (JSON String Format)

Individual History (Object Format)

Prerequisites

Empty Results Scenarios

For File-Based Results

For Individual History

Error Responses

Related Endpoints