Get Emails

get/v1/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. ## Filtering & sorting Filter via `POST /v1/records/query` (root `emails`) or the `filters` model; operators are gated by each field's data type. See [Filtering & sorting](../filtering-and-sorting). **Filterable fields** | Field | Type | Allowed operators | |---|---|---| | `composite_companies_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_email_summary` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_people_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `created_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `deleted_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `email` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `email_id` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `pk` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `updated_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | **Sortable fields:** `composite_companies_list`, `composite_email_summary`, `composite_people_list`, `created_at`, `deleted_at`, `email`, `email_id`, `pk`, `updated_at` (via `orderBy` / `sort`, `asc`|`desc`).

Requires a bearer token: Authorization: Bearer <token>.

Query parameters

Name	Type	Required	Description
include	string	No	Comma-separated list of related resources to include with detailed attributes. Available options: persons, companies, workspacese.g. persons,companies,workspaces
created_at_from	string <date-time>	No	Filter emails created on or after this datetime (ISO 8601 format)e.g. 2023-01-01T00:00:00Z
created_at_to	string <date-time>	No	Filter emails created on or before this datetime (ISO 8601 format)e.g. 2023-12-31T23:59:59Z
updated_at_from	string <date-time>	No	Filter emails updated on or after this datetime (ISO 8601 format)e.g. 2026-06-07T10:00:00.000Z
updated_at_to	string <date-time>	No	Filter emails updated on or before this datetime (ISO 8601 format)e.g. 2026-06-07T10:00:00.000Z
workspace_id	string <uuid>	No	Filter emails by workspace UUIDe.g. 00000000-0000-4000-8000-000000000000
external_workspace_id	string	No	Filter emails by external workspace identifiere.g. External workspace ID
people_id	string <uuid>	No	Filter emails by person UUIDe.g. 00000000-0000-4000-8000-000000000000
email	string <email>	No	Filter by email addresse.g. user@example.com
company_id	string <uuid>	No	Filter by company IDe.g. 550e8400-e29b-41d4-a716-446655440000
registration_tax_id	string	No	Filter by company registration tax IDe.g. 12345678901
registration_registered_value	string	No	Filter by company registration registered valuee.g. 123456789
is_primary	boolean	No	Filter by primary email statuse.g. true
is_verified	boolean	No	Filter by verification statuse.g. true
label	string	No	Filter by email labele.g. work
sort	string	No	Sort emails by date fields. Prefix with '-' for descending order.e.g. -created_at
page[limit]	integer	No	Number of emails to return per page (1-100)e.g. 25
page[cursor]	string	No	Cursor for pagination to get the next page of resultse.g. eyJjcmVhdGVkX2F0IjoiMjAyMy0wNi0xNVQxMDozMDowMFoiLCJpZCI6InV1aWQtaGVyZSJ9

Request

cURL

curl -X GET https://api.wellapp.ai/v1/emails \
  -H "Authorization: Bearer $WELL_API_TOKEN"

Responses

200 — Emails retrieved successfully

{
  "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"
      },
      "relationships": {
        "company_emails": {
          "data": [
            {
              "type": "company_email",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        },
        "person_emails": {
          "data": [
            {
              "type": "person_email",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        }
      }
    },
    {
      "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"
      },
      "relationships": {
        "company_emails": {
          "data": [
            {
              "type": "company_email",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        },
        "person_emails": {
          "data": [
            {
              "type": "person_email",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        }
      }
    },
    {
      "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"
      },
      "relationships": {
        "company_emails": {
          "data": [
            {
              "type": "company_email",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        },
        "person_emails": {
          "data": [
            {
              "type": "person_email",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20
  }
}

400 — Bad request - invalid query parameters

{
  "code": "BAD_REQUEST",
  "status": 400,
  "title": "Bad Request",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

401 — Unauthorized - invalid API key

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "title": "Unauthorized",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

Complex Usage Example

Advanced Email Filtering with Full Context

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

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"

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):

{
  "root": "emails",
  "whereClause": { "workspace": { "name": { "_ilike": "%acme%" } } },
  "orderBy": { "field": "workspace.name", "direction": "asc" }
}

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

{
  "root": "emails",
  "whereClause": { "company_emails": { "_some": { "field_name": { "_gt": 0 } } } }
}

Query parameters

Request

Responses

Complex Usage Example

Advanced Email Filtering with Full Context

Filtering & sorting on related objects