RErecruitwithatlas
Emails

List email activity

Changed on

Returns a keyset-paginated list of email activity within your agency. Each row represents a single email linked to a single person (an email matched to multiple people yields multiple rows), carrying metadata and a snippet — full message bodies are not returned. Private and hidden emails are always excluded.

Pagination (keyset): Responses carry pagination.hasMore and pagination.nextCursor rather than a page number or total count (both are prohibitively expensive on large mailboxes). Request the first page without a cursor, then send the returned nextCursor.cursorDate/cursorId on each subsequent request. This stays O(pageSize) at any depth, so it is safe for large historical backfills — unlike page/offset pagination, which degrades sharply on deep pages.

Backfill (1–2 yr): Loop the cursor until hasMore is false; optionally bound with createdAfter to cap the horizon.

Incremental sync: Poll with updatedAfter and page the cursor within each poll. Overlap each poll slightly (e.g. updatedAfter = lastPollStart - 60s) and dedupe by id so a row written exactly at the boundary is never missed. Add includeDeleted=true to receive soft-deleted emails as tombstones (deletedAt populated).

get/api/v1/emails

Request

Query parameters

personIdstring uuid

Filter to email activity linked to this person (one row is returned per person matched on an email, so this scopes to that person).

Example:550e8400-e29b-41d4-a716-446655440000
projectIdstring uuid

Filter to emails attributed to this project. Only Atlas-composed emails (sent from within a project) carry a project link, so inbound mailbox-synced emails are excluded by this filter.

Example:550e8400-e29b-41d4-a716-446655440000
direction'inbound' | 'outbound'

Filter by email direction: inbound (received) or outbound (sent).

Example:inbound
string
OR
string date-time
string
OR
string date-time
string
OR
string date-time
string
OR
string date-time
includeDeleted'true' | 'false'

Include soft-deleted emails as tombstones (with a populated deletedAt). Defaults to false. Pair with updatedAfter to incrementally sync deletions.

Example:false
pageSizeinteger

Items per page (max 100).

Example:25
cursorDatestring date-time

Keyset pagination cursor: the pagination.nextCursor.cursorDate returned by the previous request. Send together with cursorId to fetch the next page in stable order that stays O(pageSize) at any depth. Omit for the first page.

Example:2026-01-05T12:00:00.000Z
cursorIdstring uuid

Keyset pagination cursor: the pagination.nextCursor.cursorId returned by the previous request. Must be sent together with cursorDate.

Example:550e8400-e29b-41d4-a716-446655440000

Response

Paginated email activity

status'ok' required

Example response

{
  "pagination": {
    "pageSize": 25
  }
}

Changes