---
title: "List contacts"
method: GET
path: "/api/contacts"
tags: ["Email"]
---

# List contacts

`GET /api/contacts`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/contacts`
- Auth: HTTP bearer

The account's address book, auto-fed by mail traffic: correspondents, message counts, last activity, and notes. Most recently active first by default (order=recent), for display: a contact that gets new mail during a paged scan moves ahead of the cursor, so that scan can skip it. To sync the whole book, pass order=created: oldest first by creation time then id, a key that never changes, so every contact that exists for the whole scan comes back exactly once and contacts created meanwhile come at the end. A cursor only continues the order it came from (400 INVALID_CURSOR otherwise). Aggregates data from every mailbox, so mailbox-confined tokens are denied (400 MAILBOX_CONFINED).

## Query parameters

- `q` string
- `limit` integer
- `cursor` string
- `order` 'recent' | 'created'

## Response `200`

Contacts

- object
  - `contacts` object[]
    - `address` string
    - `name` string, nullable
    - `notes` string, nullable
    - `source` 'auto' | 'manual'
    - `message_count` integer
    - `first_seen_at` string
    - `last_seen_at` string
    - `last_direction` string, nullable
  - `next_cursor` string, nullable

---

[API](https://skmtc.dev/domani/apis/domani-run-api.md) · [All operations](https://skmtc.dev/domani/apis/domani-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domani/apis/domani-run-api/revisions/7679f8159533?raw)