Get emails

curl --request GET \
  --url https://api.wellapp.ai/v1/emails \
  --header 'Authorization: <authorization>'

{
  "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
  }
}

Emails

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.

GET

emails

Get emails

curl --request GET \
  --url https://api.wellapp.ai/v1/emails \
  --header 'Authorization: <authorization>'

{
  "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
  }
}

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"

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

Headers

Authorization

string

required

Bearer token for authentication

Query Parameters

include

string

Comma-separated list of related resources to include with detailed attributes. Available options: persons, companies, workspaces

created_at_from

string<date-time>

Filter emails created on or after this datetime (ISO 8601 format)

created_at_to

string<date-time>

Filter emails created on or before this datetime (ISO 8601 format)

updated_at_from

string<date-time>

Filter emails updated on or after this datetime (ISO 8601 format)

updated_at_to

string<date-time>

Filter emails updated on or before this datetime (ISO 8601 format)

workspace_id

string<uuid>

Filter emails by workspace UUID

external_workspace_id

string

Filter emails by external workspace identifier

people_id

string<uuid>

Filter emails by person UUID

string<email>

Filter by email address

company_id

string<uuid>

Filter by company ID

registration_tax_id

string

Filter by company registration tax ID

registration_registered_value

string

Filter by company registration registered value

is_primary

boolean

default:true

Filter by primary email status

is_verified

boolean

default:true

Filter by verification status

label

enum<string>

default:work

Filter by email label

Available options:

work,

personal,

support,

billing,

other

sort

enum<string>

default:-created_at

Sort emails by date fields. Prefix with '-' for descending order.

Available options:

created_at,

updated_at,

-created_at

page[limit]

integer

default:20

Number of emails to return per page (1-100)

Required range: 1 <= x <= 100

page[cursor]

string

Cursor for pagination to get the next page of results

Response

Emails retrieved successfully

data

object[]

Show child attributes

​Complex Usage Example

​Advanced Email Filtering with Full Context

​Filtering & sorting on related objects

Headers

Query Parameters

Response

Complex Usage Example

Advanced Email Filtering with Full Context

Filtering & sorting on related objects