> ## 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.
# Validate Emails
> Validate one or more email addresses for syntax, domain, deliverability, and SMTP checks
This endpoint validates email addresses using two different methods: direct email validation or file-based validation. You can either provide individual email addresses or reference a previously uploaded file.
## Validation Methods
Validate individual email addresses by providing them directly in the request.
```json theme={null}
{
"emails": ["test@example.com", "user@domain.com"],
"options": {
"validate_smtp": true,
"validate_syntax": true,
"check_dmarc": true,
"validate_mx": true
}
}
```
Validate emails from a previously uploaded file using the file ID.
```json theme={null}
{
"file_id": 740,
"file_tag": "validate",
"options": {
"validate_smtp": true,
"validate_syntax": true,
"check_dmarc": true,
"validate_mx": true
}
}
```
## How it Works
Decide whether to validate individual emails directly or use a file-based
approach
If using file-based validation, first upload your CSV or XLSX file using the
[File Upload endpoint](/api-reference/endpoint/file_upload) to obtain the
`file_id`
Set your desired validation options (syntax, DMARC, SMTP, MX records)
Send either `emails` array OR `file_id` (not both)
Get validation results for the submitted emails
## Request Parameters
**Either/Or Requirement**: You must provide either `emails` OR `file_id`, but
not both in the same request.
### Direct Email Validation
* **emails**: Array of email addresses to validate
* **options**: Validation options object
### File-Based Validation
* **file\_id**: ID from a previously uploaded file
* **file\_tag**: Tag for categorizing the validation type
* **options**: Validation options object
## Validation Options
Configure which validation checks to perform:
* **validate\_syntax**: Checks email format and structure (default: true)
* **validate\_smtp**: Performs SMTP server validation (default: false)
* **check\_dmarc**: Validates DMARC policy records (default: false)
* **validate\_mx**: Checks MX record existence (default: false)
## Example Workflows
### Direct Email Validation
```json theme={null}
POST /v1/api/email-validation/
{
"emails": ["john@example.com", "sarah@company.com"],
"options": {
"validate_syntax": true,
"validate_smtp": true,
"check_dmarc": false,
"validate_mx": true
}
}
```
### File-Based Validation
```json theme={null}
// 1. First upload a file (if not already done)
POST /v1/api/filesupload/
// Response includes: { "id": 740, "file": "https://s3.../file.csv" }
// 2. Then validate the uploaded file
POST /v1/api/email-validation/
{
"file_id": 740,
"file_tag": "validate",
"options": {
"validate_smtp": true,
"validate_syntax": true,
"check_dmarc": true,
"validate_mx": true
}
}
```
**Credits Consumption**: Validation consumes credits based on the number of
emails and validation options selected. More comprehensive validation uses
more credits.
**Bulk Processing**: For validating large lists of emails, use the file-based
approach with the File Upload endpoint for better performance and easier
management.
## OpenAPI
````yaml POST /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/:
post:
tags:
- Email Validation
summary: Validate Email Addresses
description: >-
Validate one or more email addresses for syntax, domain, deliverability,
and SMTP checks
requestBody:
description: Email validation request payload
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmailValidationRequest'
responses:
'200':
description: Email validation results
content:
application/json:
schema:
$ref: '#/components/schemas/EmailValidationResponse'
'400':
description: Bad request - Invalid payload
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden - Invalid or inactive API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Invalid or inactive API key
'429':
$ref: '#/components/responses/RateLimitExceeded'
components:
schemas:
EmailValidationRequest:
type: object
properties:
emails:
type: array
description: >-
Array of email addresses to validate (required for direct
validation)
items:
type: string
format: email
example:
- test@example.com
- user@domain.com
file_id:
type: integer
description: >-
ID of the uploaded file (obtained from file upload response) -
required for file-based validation
example: 740
options:
type: object
description: Validation options
properties:
validate_smtp:
type: boolean
description: Whether to perform SMTP validation
default: false
validate_syntax:
type: boolean
description: Whether to validate email syntax
default: true
check_dmarc:
type: boolean
description: Whether to check DMARC records
default: false
validate_mx:
type: boolean
description: Whether to validate MX records
default: false
file_tag:
type: string
enum:
- clean
- validate
- analyze
description: >-
Tag for categorizing the file processing type (required when using
file_id)
example: validate
EmailValidationResponse:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/EmailValidationResult'
stats:
$ref: '#/components/schemas/ValidationStats'
file_id:
type: string
nullable: true
description: File ID for batch processing
credits_used:
type: integer
description: Number of credits consumed
remaining_processing:
type: integer
description: Remaining emails to process
batch_size:
type: integer
description: Size of the current batch
Error:
required:
- error
- message
type: object
properties:
error:
type: integer
format: int32
message:
type: string
EmailValidationResult:
type: object
properties:
email:
type: string
description: The validated email address
status:
type: string
enum:
- valid
- invalid
- unknown
description: Overall validation status
reason:
$ref: '#/components/schemas/ValidationReason'
normalized_email:
type: string
description: Normalized version of the email
is_disposable:
type: boolean
description: Whether the email is from a disposable email service
is_role_account:
type: boolean
description: Whether the email is a role-based account
mx_records:
type: array
items:
type: string
description: MX records for the domain
ValidationStats:
type: object
properties:
total:
type: integer
description: Total emails processed
valid:
type: integer
description: Number of valid emails
invalid:
type: integer
description: Number of invalid emails
disposable:
type: integer
description: Number of disposable emails
role_accounts:
type: integer
description: Number of role-based accounts
ValidationReason:
type: object
properties:
format:
$ref: '#/components/schemas/CheckResult'
dns:
$ref: '#/components/schemas/CheckResult'
mx:
$ref: '#/components/schemas/CheckResult'
smtp:
$ref: '#/components/schemas/CheckResult'
dmarc:
$ref: '#/components/schemas/CheckResult'
CheckResult:
type: object
properties:
status:
type: string
enum:
- pass
- fail
- skipped
description: Status of the specific check
reason:
type: string
description: Detailed reason for the check result
responses:
Unauthorized:
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimitExceeded:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
description: API key for authentication
````