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

# Get Emails

> Retrieve a list of email addresses with advanced filtering, sorting, and include capabilities. This endpoint supports:

**Default behavior**: Returns email addresses with basic information (IDs only for relationships).

**Trailing slashes**: Works with or without trailing slashes '/'.

**Include functionality**: Use the `include` parameter to get detailed relationship data.

**Date filtering**: Filter by creation, update, or deletion date ranges.

**Relationship filtering**: Filter by related entities using various identifiers.

**Contact filtering**: Filter by contact information and verification status.

**Company filtering**: Filter by company registration details.

**Email filtering**: Filter by primary status, verification, and label.

**Sorting**: Sort results by date fields in ascending or descending order.

## Complex Usage Example

### Advanced Email Filtering with Full Context

This example demonstrates advanced filtering with multiple parameters, relationship inclusion, sorting, and pagination:

```bash theme={null}
curl -X GET "https://api.well.com/v1/emails?include=persons,companies,workspaces&filter[company_id]=550e8400-e29b-41d4-a716-446655440000&filter[is_verified]=true&filter[label]=work&filter[created_at_from]=2023-01-01T00:00:00Z&filter[created_at_to]=2023-12-31T23:59:59Z&sort=-created_at&page[limit]=10&page[cursor]=eyJjcmVhdGVkX2F0IjoiMjAyMy0xMS0wMlQxMDozMDowMFoiLCJpZCI6ImVtYWlsOS11dWlkIn0=" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Filtering & sorting on related objects

Filter and sort on a **related (included) object** by nesting into the relationship — the same relationships you pass to `include`.

* **To-one** relations nest directly: `{ "issuer": { "name": { "_eq": "Acme" } } }`, and sort by a dot-path: `"orderBy": { "field": "issuer.name", "direction": "asc" }`.
* **To-many** relations must be quantified with `_some`, `_every`, or `_none`: `{ "items": { "_some": { "quantity": { "_gt": 1 } } } }`. They are **not** directly sortable (a to-many sort needs an aggregate proxy).
* **Composite** `composite_*` columns are virtual — filter and sort on their underlying source fields, not on the composite.

Workspace row-level security applies at every hop, so a related-object filter never widens your tenant scope. Full operator set, deep-nesting rules, and pagination notes: [Filtering & sorting](/api-reference/filtering-and-sorting).

This resource's related objects (the ones you can `include`) and how to filter or sort on each:

| Relationship     | Cardinality              | Filter on a field                                                   | Sort by a field               |
| ---------------- | ------------------------ | ------------------------------------------------------------------- | ----------------------------- |
| `workspace`      | to-one (workspace)       | `{ "workspace": { "name": { "_eq": … } } }`                         | `"field": "workspace.name"` ✅ |
| `company_emails` | to-many (company\_email) | `{ "company_emails": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️       |
| `person_emails`  | to-many (person\_email)  | `{ "person_emails": { "_some": { "field_name": { "_eq": … } } } }`  | aggregate proxy only ⚠️       |

Replace `field_name` with any field of the related object. See its object-reference page for the full field list.

**Filter by a to-one relation** (and sort by it):

```json theme={null}
{
  "root": "emails",
  "whereClause": { "workspace": { "name": { "_ilike": "%acme%" } } },
  "orderBy": { "field": "workspace.name", "direction": "asc" }
}
```

**Filter by a to-many relation** (quantified — bare nesting is invalid):

```json theme={null}
{
  "root": "emails",
  "whereClause": { "company_emails": { "_some": { "field_name": { "_gt": 0 } } } }
}
```


## OpenAPI

````yaml GET /v1/emails
openapi: 3.1.0
info:
  title: Well Document API
  version: 1.0.0
  description: API for uploading and managing financial documents in the Well platform
servers:
  - url: https://api.wellapp.ai
security: []
paths:
  /v1/emails:
    get:
      summary: Get emails
      description: >-
        Retrieve a list of email addresses with advanced filtering, sorting, and
        include capabilities. This endpoint supports:


        **Default behavior**: Returns email addresses with basic information
        (IDs only for relationships).


        **Trailing slashes**: Works with or without trailing slashes '/'.


        **Include functionality**: Use the `include` parameter to get detailed
        relationship data.


        **Date filtering**: Filter by creation, update, or deletion date ranges.


        **Relationship filtering**: Filter by related entities using various
        identifiers.


        **Contact filtering**: Filter by contact information and verification
        status.


        **Company filtering**: Filter by company registration details.


        **Email filtering**: Filter by primary status, verification, and label.


        **Sorting**: Sort results by date fields in ascending or descending
        order.
      parameters:
        - $ref: '#/components/parameters/AuthorizationHeader'
        - name: include
          in: query
          required: false
          schema:
            type: string
          description: >-
            Comma-separated list of related resources to include with detailed
            attributes. Available options: persons, companies, workspaces
          example: persons,companies,workspaces
        - name: created_at_from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter emails created on or after this datetime (ISO 8601 format)
          example: '2023-01-01T00:00:00Z'
        - name: created_at_to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter emails created on or before this datetime (ISO 8601 format)
          example: '2023-12-31T23:59:59Z'
        - name: updated_at_from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter emails updated on or after this datetime (ISO 8601 format)
        - name: updated_at_to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter emails updated on or before this datetime (ISO 8601 format)
        - name: workspace_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter emails by workspace UUID
        - name: external_workspace_id
          in: query
          required: false
          schema:
            type: string
          description: Filter emails by external workspace identifier
        - name: people_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter emails by person UUID
        - name: email
          in: query
          required: false
          schema:
            type: string
            format: email
          description: Filter by email address
          example: user@example.com
        - name: company_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter by company ID
          example: 550e8400-e29b-41d4-a716-446655440000
        - name: registration_tax_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by company registration tax ID
          example: '12345678901'
        - name: registration_registered_value
          in: query
          required: false
          schema:
            type: string
          description: Filter by company registration registered value
          example: '123456789'
        - name: is_primary
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Filter by primary email status
          example: true
        - name: is_verified
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Filter by verification status
          example: true
        - name: label
          in: query
          required: false
          schema:
            type: string
            enum:
              - work
              - personal
              - support
              - billing
              - other
            default: work
          description: Filter by email label
          example: work
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - created_at
              - updated_at
              - '-created_at'
            default: '-created_at'
          description: Sort emails by date fields. Prefix with '-' for descending order.
          example: '-created_at'
        - name: page[limit]
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of emails to return per page (1-100)
          example: 25
        - name: page[cursor]
          in: query
          required: false
          schema:
            type: string
          description: Cursor for pagination to get the next page of results
          example: >-
            eyJjcmVhdGVkX2F0IjoiMjAyMy0wNi0xNVQxMDozMDowMFoiLCJpZCI6InV1aWQtaGVyZSJ9
      responses:
        '200':
          description: Emails retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailGetResponse'
              example:
                data:
                  - type: email
                    id: email1-uuid
                    attributes:
                      value: sarah.wilson@techcorp.com
                      is_primary: true
                      is_verified: true
                      label: work
                      created_at: '2023-06-15T10:30:00Z'
                      updated_at: '2023-06-15T10:30:00Z'
                    relationships:
                      persons:
                        data:
                          - type: people
                            id: person1-uuid
                      companies:
                        data:
                          - type: company
                            id: company1-uuid
                      workspaces:
                        data:
                          - type: workspace
                            id: workspace1-uuid
                included:
                  - type: people
                    id: person1-uuid
                    attributes:
                      first_name: Sarah
                      last_name: Wilson
                      full_name: Sarah Wilson
                      created_at: '2023-06-15T09:00:00Z'
                      updated_at: '2023-06-15T09:00:00Z'
                  - type: company
                    id: company1-uuid
                    attributes:
                      name: TechCorp Solutions
                      description: Leading technology company
                      domain_name_primary_link_url: techcorp.com
                      locale: en
                      created_at: '2023-06-01T08:00:00Z'
                      updated_at: '2023-06-01T08:00:00Z'
                  - type: workspace
                    id: workspace1-uuid
                    attributes:
                      name: Sales Team
                      description: Sales team workspace
                      avatar_color: '#FF5733'
                      auto_extract_enabled: true
                      created_at: '2023-06-01T08:00:00Z'
                      updated_at: '2023-06-01T08:00:00Z'
                meta:
                  total: 150
                  page: 1
                  limit: 20
        '400':
          description: Bad request - invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: Unauthorized - invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
components:
  parameters:
    AuthorizationHeader:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
      description: Bearer token for authentication
  schemas:
    EmailGetResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Email'
        meta:
          type: object
          properties:
            pagination:
              type: object
              properties:
                total:
                  type: integer
                  description: Total number of emails
                count:
                  type: integer
                  description: Number of emails in current response
                has_more:
                  type: boolean
                  description: Whether there are more emails available
                next_cursor:
                  type: string
                  description: Cursor for the next page of results
    BadRequestError:
      type: object
      properties:
        code:
          type: string
          example: SCHEMA_VALIDATION_ERROR
          description: Error code identifier
        status:
          type: integer
          example: 400
          description: HTTP status code
        title:
          type: string
          example: Validation Error
          description: Error title
        message:
          type: string
          example: The request is invalid
          description: Detailed error message
        details:
          type: array
          items:
            type: object
            properties:
              instancePath:
                type: string
                description: Path to the invalid field in the request
              schemaPath:
                type: string
                description: Path to the validation rule in the schema
              keyword:
                type: string
                description: Validation keyword that failed
              params:
                type: object
                description: Parameters related to the validation failure
              message:
                type: string
                description: Human-readable validation error message
          description: Array of detailed validation errors
        meta:
          type: object
          properties:
            log_id:
              type: string
              format: uuid
              example: 65c669d4-679c-4a8b-b8c0-fbe37699bb5b
              description: Unique identifier for tracking this error in logs
          required:
            - log_id
      required:
        - code
        - status
        - title
        - message
        - meta
    UnauthorizedError:
      type: object
      properties:
        code:
          type: string
          example: UNAUTHORIZED
          description: Error code identifier
        status:
          type: integer
          example: 401
          description: HTTP status code
        title:
          type: string
          example: Unauthorized
          description: Error title
        message:
          type: string
          example: You are not authorized to access this resource
          description: Detailed error message
        meta:
          type: object
          properties:
            log_id:
              type: string
              format: uuid
              example: 65c669d4-679c-4a8b-b8c0-fbe37699bb5b
              description: Unique identifier for tracking this error in logs
          required:
            - log_id
      required:
        - code
        - status
        - title
        - message
        - meta
    Email:
      type: object
      properties:
        type:
          type: string
          const: email
        id:
          type: string
          format: uuid
        attributes:
          $ref: '#/components/schemas/EmailAttributes'
        relationships:
          $ref: '#/components/schemas/AtomicRelationshipsResponse'
        included:
          $ref: '#/components/schemas/SimpleIncludedResponse'
    EmailAttributes:
      type: object
      properties:
        value:
          type: string
          format: email
          description: Email address value
          example: sarah.wilson@techcorp.com
        is_primary:
          type: boolean
          default: true
          description: >-
            Whether this is the primary email address. Defaults to 'false',
            unless no other email is marked as primary (in which case it becomes
            'true'). Only one email can be marked as primary per person/company.
          example: true
        label:
          type: string
          enum:
            - work
            - personal
            - other
            - ...
          description: >-
            Email label type. See [all available labels](/enums/label) for
            complete list.
          default: work
          example: work
        created_at:
          type: string
          format: date-time
          description: Timestamp when the email was created
          example: '2023-06-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the email was last updated
          example: '2023-06-15T10:30:00Z'
    AtomicRelationshipsResponse:
      type: object
      properties:
        persons:
          $ref: '#/components/schemas/PeopleRelationResponse'
        companies:
          $ref: '#/components/schemas/CompanyRelationResponse'
        workspaces:
          $ref: '#/components/schemas/WorkspaceRelationResponse'
    SimpleIncludedResponse:
      type: object
      properties:
        persons:
          type: object
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    const: people
                  id:
                    type: string
                    format: uuid
                  attributes:
                    $ref: '#/components/schemas/PersonAttributes'
        companies:
          type: object
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    const: company
                  id:
                    type: string
                    format: uuid
                  attributes:
                    $ref: '#/components/schemas/CompanyAttributes'
        workspaces:
          type: object
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    const: workspace
                  id:
                    type: string
                    format: uuid
                  attributes:
                    $ref: '#/components/schemas/WorkspaceAttributes'
    PeopleRelationResponse:
      type: object
      properties:
        data:
          type: array
          items:
            properties:
              type:
                type: string
                enum:
                  - people
              id:
                type: string
                format: uuid
                description: UUID of the people
    CompanyRelationResponse:
      type: object
      properties:
        data:
          type: array
          items:
            properties:
              type:
                type: string
                enum:
                  - company
              id:
                type: string
                format: uuid
                description: UUID of the company
    WorkspaceRelationResponse:
      type: object
      properties:
        data:
          type: array
          items:
            oneOf:
              - properties:
                  type:
                    type: string
                    enum:
                      - workspace
                  external_workspace_id:
                    type: string
                    description: External workspace identifier
              - properties:
                  type:
                    type: string
                    enum:
                      - workspace
                  id:
                    type: string
                    format: uuid
                    description: UUID of the workspace
    PersonAttributes:
      type: object
      description: Person attribute data
      properties:
        first_name:
          type: string
          description: Person's first name
          example: Marie
          minLength: 1
          maxLength: 100
        last_name:
          type: string
          description: Person's last name
          example: Dubois
          minLength: 1
          maxLength: 100
        full_name:
          type: string
          description: Auto-computed full name (first + last)
          example: Marie Dubois
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: Person creation timestamp (UTC)
          example: '2024-01-15T10:30:00Z'
          readOnly: true
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Last modification timestamp (UTC)
          example: '2024-01-16T14:20:00Z'
          readOnly: true
      required:
        - first_name
        - last_name
        - created_at
    CompanyAttributes:
      type: object
      properties:
        description:
          type: string
        domain_name_primary_link_url:
          type: string
          format: url
          maxLength: 500
          description: >-
            The domain url from the website or email address of the company.
            Used as unique identifier in some cases.
          examples:
            - acme.com
        tax_id:
          type: object
          properties:
            value:
              description: Tax ID issued by local or national tax authority.
              type: string
              examples:
                - DE123456789
            type:
              description: >-
                Type of tax ID, useful for applying formatting and validation
                rules.
              type: string
              examples:
                - VAT
        registration:
          type: object
          properties:
            trade_name:
              description: Commercial or branding name (if different from registered name).
              type: string
              examples:
                - TechSol
            registered_name:
              description: Legal company name.
              type: string
              minLength: 1
              maxLength: 100
              examples:
                - Red Hat Inc.
        registration_number:
          type: object
          properties:
            business_type:
              description: Legal entity structure type.
              type: string
              examples:
                - GmbH
            value:
              description: Official company registration number.
              type: string
              examples:
                - HRB 123456
            registry_name:
              description: Name of the official registration body.
              type: string
              examples:
                - Handelsregister Berlin
            registry_country:
              description: Country of the registry authority. (string (ISO 3166-1 alpha-2))
              type: string
              examples:
                - DE
        workspace_id:
          type: string
          format: uuid
          description: UUID of the workspace associated with this company
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    WorkspaceAttributes:
      type: object
      properties:
        name:
          type: string
          description: Workspace name
        desription:
          type: string
          description: Workspace description
        external_workspace_id:
          type: string
          format: uuid
          description: external workspace id
        avatar_color:
          type: string
          format: colors
          description: Color of the avatar
        created_at:
          type: string
          format: date-time
          description: Timestamp when the workspace was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the workspace was last updated

````