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

# Analyze Email List

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

This endpoint provides a quick analysis of an uploaded email list to estimate bounce rates and validation statistics without consuming credits. It performs intelligent sampling to deliver fast, approximate results that are close to actual values.

## How it Works

<Steps>
  <Step title="Upload File First">
    Use the [File Upload endpoint](/api-reference/endpoint/file_upload) to
    upload your CSV or XLSX file and obtain the `file_id`
  </Step>

  <Step title="Submit Analysis Request">
    Send the analysis request with the file ID and list name
  </Step>

  <Step title="Get Instant Results">
    Receive bounce rate estimates and status immediately
  </Step>
</Steps>

## Key Features

<CardGroup cols={2}>
  <Card title="No Credits Required" icon="free">
    Analyze your email lists without consuming any validation credits
  </Card>

  <Card title="Fast Results" icon="bolt">
    Get bounce rate estimates in seconds, not minutes
  </Card>

  <Card title="Smart Sampling" icon="chart-line">
    Uses intelligent analysis to provide close approximations of actual rates
  </Card>

  <Card title="Pre-Validation Insights" icon="eye">
    Make informed decisions before running full validation
  </Card>
</CardGroup>

## Use Cases

* **Quick Quality Assessment**: Get a rapid overview of your email list quality
* **Budget Planning**: Estimate validation costs before processing
* **List Comparison**: Compare multiple lists without credit consumption
* **Pre-Processing Insights**: Understand your data before full validation

## Example Usage

```bash theme={null}
curl -X POST https://base.sanitizeemail.com/v1/api/filesupload/analyze-list/ \
  -H "X-API-KEY: YOUR_API_KEY" \
  -F "file_id=751" \
  -F "name=Customer List Analysis"
```

## Response Format

```json theme={null}
{
  "file_id": 751,
  "bounce_rate": 66.67,
  "status": "analyzed"
}
```

## Important Notes

<Note>
  **Approximation Method**: This endpoint uses intelligent sampling techniques
  to provide bounce rate estimates. While results are close to actual values,
  they are approximations and may vary from precise validation results.
</Note>

<Tip>
  **Zero Cost Analysis**: Perfect for getting insights into your email list
  quality without spending credits. Use this before deciding whether to proceed
  with full validation.
</Tip>

<Warning>
  **Not 100% Accurate**: Results are estimates based on analysis patterns. For
  exact validation results, use the [Clean Email
  List](/api-reference/endpoint/clean_list) endpoint.
</Warning>

## When to Use This vs Full Validation

| Use Analyze List When      | Use Full Validation When        |
| -------------------------- | ------------------------------- |
| Quick quality check needed | Exact results required          |
| Budget planning            | Preparing final email campaigns |
| Comparing multiple lists   | Compliance requirements         |
| Initial assessment         | Production email sends          |

## Prerequisites

<Note>
  **File Upload Required**: You must first upload a file using the
  `/v1/api/filesupload/` endpoint to obtain the required `file_id`.
</Note>


## OpenAPI

````yaml POST /v1/api/filesupload/analyze-list/
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/analyze-list/:
    post:
      tags:
        - Email Analysis
      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.
      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'
components:
  schemas:
    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
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  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'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

````