{
  "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": {
        "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'.",
        "tags": ["Email Validation"],
        "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"
          }
        }
      },
      "post": {
        "summary": "Validate Email Addresses",
        "description": "Validate one or more email addresses for syntax, domain, deliverability, and SMTP checks",
        "tags": ["Email Validation"],
        "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"
          }
        }
      }
    },
    "/v1/api/filesupload/": {
      "get": {
        "summary": "List Uploaded Files",
        "description": "Retrieve a paginated list of uploaded files with optional filtering by file tag",
        "tags": ["File Upload"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FileTag"
          },
          {
            "$ref": "#/components/parameters/Size"
          },
          {
            "$ref": "#/components/parameters/Page"
          }
        ],
        "responses": {
          "200": {
            "description": "List of files retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "summary": "Upload CSV or XLSX File",
        "description": "Upload CSV or XLSX files for bulk email validation with automatic email column detection",
        "tags": ["File Upload"],
        "requestBody": {
          "description": "File upload with form data",
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/FileUploadRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "File successfully uploaded and queued for processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUploadSuccessResponse"
                }
              }
            }
          },
          "200": {
            "description": "File uploaded but requires email column selection",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUploadColumnSelectionResponse"
                }
              }
            }
          },
          "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"
          }
        }
      }
    },
    "/v1/api/filesupload/{file_id}": {
      "get": {
        "summary": "Get File Details",
        "description": "Retrieve details of a previously uploaded file including processing status, statistics, and metadata",
        "tags": ["File Upload"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FileId"
          }
        ],
        "responses": {
          "200": {
            "description": "File details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileDetailsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/api/cleanemail/": {
      "post": {
        "summary": "Clean Email List",
        "description": "Process and clean an uploaded email list file with comprehensive validation options",
        "tags": ["Email Cleaning"],
        "requestBody": {
          "description": "Email list cleaning request payload",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CleanEmailRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email cleaning job initiated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CleanEmailResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid payload or file reference",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          }
        }
      }
    },
    "/v1/api/cleanedemail/": {
      "get": {
        "summary": "View Clean List Results",
        "description": "This endpoint retrieves the results of a cleaned email list, showing all valid emails that passed the validation process. Use this to access the clean emails after the cleaning job is completed.",
        "tags": ["Email Cleaning"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FileIdQuery"
          },
          {
            "$ref": "#/components/parameters/Size"
          },
          {
            "$ref": "#/components/parameters/Page"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful retrieval of cleaned email list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CleanedEmailListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid file_id or missing parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/api/filesupload/analyze-list/": {
      "post": {
        "summary": "Analyze Email List",
        "description": "Analyze an uploaded email list to get a close estimate of the bounce rate. This analysis provides a nearly accurate result without requiring any credits, making it a free way to gauge list quality before committing to a full cleaning.",
        "tags": ["Email Analysis"],
        "requestBody": {
          "description": "Email list analysis request payload",
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/AnalyzeListRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email list analysis completed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyzeListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid payload or file reference",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          }
        }
      }
    },
    "/v1/api/cleanedemail/download-cleaned-emails/": {
      "get": {
        "summary": "Download Clean Email List",
        "description": "Generates and provides a download URL for the cleaned email list from a processed file. Returns a secure, time-limited URL to download a CSV file containing only valid emails.",
        "tags": ["Email Cleaning"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FileIdQueryRequired"
          }
        ],
        "responses": {
          "200": {
            "description": "Download URL generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CleanEmailDownloadResponse"
                }
              }
            }
          },
          "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": 75
                }
              }
            }
          }
        }
      }
    },
    "/v1/api/email-validation/download-validation-results/": {
      "get": {
        "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.",
        "tags": ["Email Validation"],
        "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": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "User ID"
          },
          "username": {
            "type": "string",
            "description": "Username"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "User email address"
          }
        }
      },
      "Workspace": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Workspace ID"
          },
          "name": {
            "type": "string",
            "description": "Name of the workspace"
          },
          "owner": {
            "type": "integer",
            "description": "ID of the workspace owner"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "Error": {
        "required": ["error", "message"],
        "type": "object",
        "properties": {
          "error": {
            "type": "integer",
            "format": "int32"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "CleanEmailRequest": {
        "type": "object",
        "required": ["file_id", "file", "user", "list_name"],
        "properties": {
          "file_id": {
            "type": "integer",
            "description": "ID of the uploaded file (obtained from file upload response)",
            "example": 739
          },
          "list_name": {
            "type": "string",
            "description": "Name for the cleaned email list",
            "example": "Customer List - Cleaned"
          },
          "options": {
            "type": "object",
            "description": "Validation and cleaning options",
            "properties": {
              "validate_syntax": {
                "type": "boolean",
                "description": "Whether to validate email syntax",
                "default": true
              },
              "check_dmarc": {
                "type": "boolean",
                "description": "Whether to check DMARC records",
                "default": true
              },
              "validate_smtp": {
                "type": "boolean",
                "description": "Whether to perform SMTP validation",
                "default": true
              },
              "validate_mx": {
                "type": "boolean",
                "description": "Whether to validate MX records",
                "default": true
              }
            }
          }
        }
      },
      "CleanEmailResponse": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string",
            "description": "Unique identifier for the cleaning job"
          },
          "status": {
            "type": "string",
            "enum": ["queued", "processing", "completed", "failed"],
            "description": "Current status of the cleaning job"
          },
          "list_name": {
            "type": "string",
            "description": "Name of the email list being cleaned"
          },
          "file_id": {
            "type": "integer",
            "description": "ID of the source file"
          },
          "estimated_completion_time": {
            "type": "string",
            "format": "date-time",
            "description": "Estimated completion time for the cleaning job"
          },
          "options_applied": {
            "type": "object",
            "description": "Validation options that will be applied",
            "properties": {
              "validate_syntax": {
                "type": "boolean"
              },
              "check_dmarc": {
                "type": "boolean"
              },
              "validate_smtp": {
                "type": "boolean"
              },
              "validate_mx": {
                "type": "boolean"
              }
            }
          },
          "total_emails": {
            "type": "integer",
            "description": "Total number of emails to be processed"
          },
          "credits_required": {
            "type": "integer",
            "description": "Number of credits required for this cleaning job"
          }
        }
      },
      "FileDetailsResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique identifier of the file"
          },
          "name": {
            "type": "string",
            "description": "Display name of the file"
          },
          "file_name": {
            "type": "string",
            "description": "Original filename"
          },
          "file_size": {
            "type": "string",
            "description": "File size in bytes"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "processing", "validated", "cleaned", "failed"],
            "description": "Current processing status of the file"
          },
          "user": {
            "$ref": "#/components/schemas/User"
          },
          "file": {
            "type": "string",
            "format": "uri",
            "description": "URL to access the uploaded file"
          },
          "file_tag": {
            "type": "string",
            "enum": ["clean", "validate", "analyze"],
            "description": "Tag associated with the file processing type"
          },
          "total_email": {
            "type": "integer",
            "description": "Total number of emails found in the file"
          },
          "billable_email": {
            "type": "integer",
            "description": "Number of emails that count towards billing"
          },
          "duplicate_email": {
            "type": "integer",
            "description": "Number of duplicate emails found"
          },
          "dropped_email": {
            "type": "integer",
            "description": "Number of emails that were dropped during processing"
          },
          "clean_email_count": {
            "type": "integer",
            "description": "Number of clean/valid emails"
          },
          "bounced_email": {
            "type": "integer",
            "description": "Number of emails that bounced"
          },
          "bounce_rate": {
            "type": "number",
            "format": "float",
            "description": "Bounce rate as a decimal (0.0 to 1.0)"
          },
          "created_date": {
            "type": "string",
            "format": "date-time",
            "description": "Date and time when the file was uploaded"
          },
          "is_file_organised": {
            "type": "boolean",
            "description": "Whether the file was uploaded as organized (with headers)"
          },
          "progress_percentage": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Processing progress percentage"
          },
          "updated_date": {
            "type": "string",
            "format": "date-time",
            "description": "Date and time when the file was last updated"
          },
          "valid_emails_count": {
            "type": "integer",
            "description": "Number of valid emails"
          },
          "invalid_emails_count": {
            "type": "integer",
            "description": "Number of invalid emails"
          },
          "clean_email_id": {
            "type": "integer",
            "nullable": true,
            "description": "ID of the clean email list (if cleaning was performed)"
          },
          "validate_email_id": {
            "type": "integer",
            "nullable": true,
            "description": "ID of the validation job (if validation was performed)"
          }
        }
      },
      "FileListResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Total number of files matching the query"
          },
          "next": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "URL for the next page of results"
          },
          "previous": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "URL for the previous page of results"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FileDetailsResponse"
            },
            "description": "Array of file objects for the current page"
          }
        }
      },
      "CleanedEmailListResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Total number of cleaned emails"
          },
          "next": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "URL for the next page of results"
          },
          "previous": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "URL for the previous page of results"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CleanedEmailResult"
            },
            "description": "Array of cleaned email objects"
          }
        }
      },
      "CleanedEmailResult": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "workspace": { "$ref": "#/components/schemas/Workspace" },
          "clean_email": { "$ref": "#/components/schemas/CleanEmailFileLink" },
          "valid_email": { "type": "string", "format": "email" },
          "created_date": { "type": "string", "format": "date-time" }
        }
      },
      "CleanEmailFileLink": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "file_id": { "$ref": "#/components/schemas/CleanedFileSummary" }
        }
      },
      "CleanedFileSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "file_name": { "type": "string" },
          "status": { "type": "string" },
          "clean_email_count": { "type": "integer" },
          "bounce_rate": { "type": "number" }
        }
      },
      "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"
            }
          }
        }
      },
      "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" }
        }
      },
      "AnalyzeListRequest": {
        "type": "object",
        "required": ["file_id"],
        "properties": {
          "file_id": {
            "type": "integer",
            "description": "ID of the uploaded file (obtained from file upload response)",
            "example": 751
          },
          "name": {
            "type": "string",
            "description": "Name for the analysis request",
            "example": "Customer List Analysis"
          }
        }
      },
      "AnalyzeListResponse": {
        "type": "object",
        "properties": {
          "file_id": {
            "type": "integer",
            "description": "ID of the analyzed file"
          },
          "bounce_rate": {
            "type": "number",
            "format": "float",
            "description": "Estimated bounce rate percentage"
          },
          "status": {
            "type": "string",
            "enum": ["analyzed"],
            "description": "Analysis completion status"
          }
        }
      },
      "CleanEmailDownloadResponse": {
        "type": "object",
        "properties": {
          "download_url": {
            "type": "string",
            "format": "uri",
            "description": "Secure pre-signed URL for downloading the cleaned email file"
          },
          "filename": {
            "type": "string",
            "description": "Name of the generated clean email file"
          },
          "file_id": {
            "type": "string",
            "description": "ID of the original file that was cleaned"
          },
          "record_count": {
            "type": "integer",
            "description": "Number of clean emails 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": "your_cleaned_emails.csv",
          "file_id": "{id}",
          "record_count": 172,
          "format": "csv"
        }
      },
      "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"
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "API key for authentication"
      }
    },
    "parameters": {
      "FileId": {
        "name": "file_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer"
        },
        "description": "Unique identifier of the uploaded file",
        "example": 740
      },
      "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"
      },
      "FileIdQuery": {
        "name": "file_id",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer"
        },
        "description": "The ID of the file for which to retrieve results.",
        "example": 757
      },
      "FileTag": {
        "name": "file_tag",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "enum": ["clean", "validate", "analyze"]
        },
        "description": "Filter files by their processing purpose/tag",
        "example": "validate"
      },
      "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
      },
      "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
      }
    },
    "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"
            }
          }
        }
      },
      "RateLimitExceeded": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}