> ## 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.
# Upload CSV or XLSX
> Upload CSV or XLSX files for bulk email validation with automatic email column detection
This endpoint allows users to upload CSV or XLSX files for bulk email validation. It supports both organized files (with headers) and unorganized files, with intelligent email column detection.
## How it Works
Submit your CSV or XLSX file with the required parameters
If `is_file_organised` is true, the API automatically detects email columns
If no email column is found, you'll receive suggestions to choose the
correct column
Resubmit with the chosen `email_column` to start validation
## Important Notes
**Column Selection**: You can always provide an `email_column` parameter, even
on the first upload. It's particularly useful when you know the exact column
name containing email addresses.
**File Resubmission**: If you receive a 200 response with `available_columns`,
resubmit the same file with the chosen `email_column` to proceed with
processing.
**File Organization**: Set `is_file_organised=false` for files without headers
or with inconsistent structure. The API will attempt to detect emails from the
raw data.
## OpenAPI
````yaml POST /v1/api/filesupload/
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/filesupload/:
post:
tags:
- File Upload
summary: Upload CSV or XLSX File
description: >-
Upload CSV or XLSX files for bulk email validation with automatic email
column detection
requestBody:
description: File upload with form data
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/FileUploadRequest'
responses:
'200':
description: File uploaded but requires email column selection
content:
application/json:
schema:
$ref: '#/components/schemas/FileUploadColumnSelectionResponse'
'201':
description: File successfully uploaded and queued for processing
content:
application/json:
schema:
$ref: '#/components/schemas/FileUploadSuccessResponse'
'400':
description: Bad request - Invalid file format or missing required parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'413':
description: File too large
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/RateLimitExceeded'
components:
schemas:
FileUploadRequest:
type: object
required:
- file
- name
- is_file_organised
- file_tag
properties:
file:
type: string
format: binary
description: The CSV or XLSX file to upload for email validation
name:
type: string
description: Display name for the uploaded file
example: Customer List
email_column:
type: string
description: >-
Name of the column containing email addresses. Optional on first
upload, but required if the API returns column suggestions.
example: email_address
is_file_organised:
type: boolean
description: >-
Whether the file has a structured format with column headers. Set to
true for files with headers, false for unorganized data.
example: true
file_tag:
type: string
enum:
- clean
- validate
- analyze
description: >-
Tag to categorize the file processing type. 'clean' removes invalid
emails, 'validate' checks email validity, 'analyze' provides
detailed email insights.
example: clean
FileUploadColumnSelectionResponse:
type: object
properties:
error:
type: string
description: Error message indicating no email columns found
is_first_time:
type: boolean
description: Whether this is the first upload attempt
available_columns:
type: array
items:
type: string
description: List of available column names in the file
sample_first_3_rows:
type: array
items:
type: object
additionalProperties: true
description: Sample of first 3 rows to help identify the correct email column
FileUploadSuccessResponse:
type: object
properties:
id:
type: integer
description: Unique identifier for the uploaded file
name:
type: string
description: Display name of the file
file:
type: string
format: uri
description: URL to the uploaded file
status:
type: string
enum:
- pending
- processing
- completed
- failed
description: Current processing status of the file
file_tag:
type: string
enum:
- clean
- validate
- analyze
description: Tag associated with the file processing type
file_name:
type: string
description: Original filename
file_size:
type: string
description: File size in bytes
stats:
$ref: '#/components/schemas/FileProcessingStats'
clean_emails_available:
type: boolean
description: Whether clean emails are available for download
workspace:
type: string
description: Workspace name where the file was uploaded
Error:
required:
- error
- message
type: object
properties:
error:
type: integer
format: int32
message:
type: string
FileProcessingStats:
type: object
properties:
total_processed:
type: integer
description: Total number of rows processed
total_emails:
type: integer
description: Total number of email addresses found
unique_emails:
type: integer
description: Number of unique email addresses
duplicate_emails:
type: integer
description: Number of duplicate email addresses
dropped_emails:
type: integer
description: Number of emails that were dropped due to invalid format
email_columns_used:
type: array
items:
type: string
description: Names of columns used for email extraction
email_domains:
type: object
additionalProperties:
type: integer
description: Count of emails per domain
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
````