Get emails

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

import requests

url = "https://api.wellapp.ai/v1/emails"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.wellapp.ai/v1/emails', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wellapp.ai/v1/emails",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.wellapp.ai/v1/emails"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.wellapp.ai/v1/emails")
  .header("Authorization", "<authorization>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.wellapp.ai/v1/emails")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

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

{
  "code": "SCHEMA_VALIDATION_ERROR",
  "status": 400,
  "title": "Validation Error",
  "message": "The request is invalid",
  "meta": {
    "log_id": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b"
  },
  "details": [
    {
      "instancePath": "<string>",
      "schemaPath": "<string>",
      "keyword": "<string>",
      "params": {},
      "message": "<string>"
    }
  ]
}

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "title": "Unauthorized",
  "message": "You are not authorized to access this resource",
  "meta": {
    "log_id": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b"
  }
}

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

import requests

url = "https://api.wellapp.ai/v1/emails"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.wellapp.ai/v1/emails', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wellapp.ai/v1/emails",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.wellapp.ai/v1/emails"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.wellapp.ai/v1/emails")
  .header("Authorization", "<authorization>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.wellapp.ai/v1/emails")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

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

{
  "code": "SCHEMA_VALIDATION_ERROR",
  "status": 400,
  "title": "Validation Error",
  "message": "The request is invalid",
  "meta": {
    "log_id": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b"
  },
  "details": [
    {
      "instancePath": "<string>",
      "schemaPath": "<string>",
      "keyword": "<string>",
      "params": {},
      "message": "<string>"
    }
  ]
}

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "title": "Unauthorized",
  "message": "You are not authorized to access this resource",
  "meta": {
    "log_id": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b"
  }
}

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

Main Resources

Atomic Resources

System

Records — read endpoints

Get Emails

Complex Usage Example

Advanced Email Filtering with Full Context

Headers

Query Parameters

Response

​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