> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emailr.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Import contacts from CSV

> Import contacts from a CSV file with column mappings. Creates new contacts or updates existing ones based on email.



## OpenAPI

````yaml /openapi.json post /v1/contacts/import
openapi: 3.0.3
info:
  title: Emailr API
  version: 1.0.0
servers:
  - url: https://api.emailr.dev
    description: Production
security: []
tags:
  - name: emails
    description: Email sending and management
  - name: contacts
    description: Contact management
  - name: templates
    description: Email template management
  - name: domains
    description: Domain verification and management
  - name: webhooks
    description: Webhook configuration
  - name: broadcasts
    description: Broadcast campaign management
  - name: segments
    description: Contact segmentation
paths:
  /v1/contacts/import:
    post:
      tags:
        - import
      summary: Import contacts from CSV
      description: >-
        Import contacts from a CSV file with column mappings. Creates new
        contacts or updates existing ones based on email.
      operationId: csvImport
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CSVImportRequest'
      responses:
        '200':
          description: Import completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CSVImportResponse'
        '400':
          description: Validation error or CSV parsing error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    CSVImportRequest:
      type: object
      properties:
        file_content:
          type: string
          description: Base64 encoded CSV content
          example: >-
            ZW1haWwsZmlyc3RfbmFtZSxsYXN0X25hbWUKam9obkBleGFtcGxlLmNvbSxKb2huLERvZQ==
        column_mappings:
          type: array
          items:
            $ref: '#/components/schemas/ColumnMapping'
          description: Mappings from CSV columns to contact properties
          example:
            - csv_column: Email Address
              property_name: email
            - csv_column: First Name
              property_name: first_name
            - csv_column: Company
              property_name: company
        handle_missing:
          type: string
          enum:
            - create
            - skip
          default: create
          description: >-
            How to handle emails not found in contacts: 'create' to add new
            contacts, 'skip' to ignore them
          example: create
        segment_id:
          type: string
          format: uuid
          description: Optional segment ID to add imported contacts to
          example: 123e4567-e89b-12d3-a456-426614174000
      required:
        - file_content
        - column_mappings
    CSVImportResponse:
      type: object
      properties:
        created:
          type: integer
          description: Number of new contacts created
          example: 45
        updated:
          type: integer
          description: Number of existing contacts updated
          example: 10
        skipped:
          type: integer
          description: Number of rows skipped (invalid data or handle_missing='skip')
          example: 3
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ImportError'
          description: List of errors encountered during import
          example:
            - row: 5
              email: invalid-email
              error: Invalid email format
      required:
        - created
        - updated
        - skipped
        - errors
    Error:
      type: object
      properties:
        error:
          type: string
          example: An error occurred
        code:
          type: string
          example: VALIDATION_ERROR
        details: {}
      required:
        - error
    ColumnMapping:
      type: object
      properties:
        csv_column:
          type: string
          description: Column header from the CSV file
          example: Email Address
        property_name:
          type: string
          nullable: true
          description: Contact property to map to. Use null to skip this column.
          example: email
      required:
        - csv_column
        - property_name
    ImportError:
      type: object
      properties:
        row:
          type: integer
          description: Row number in the CSV (1-indexed, excluding header)
          example: 5
        email:
          type: string
          description: The email value that caused the error
          example: invalid-email
        error:
          type: string
          description: Description of the error
          example: Invalid email format
      required:
        - row
        - email
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API key authentication. Use your API key as the bearer token.

````