---
title: "List contacts"
description: "The workspace address book, most recently seen first, with contacts that have never been mailed last. Every key on the workspace reads the same rows, so a contact saved by one member is a contact every member and every key sees. Paging is keyset: `limit` goes up to 200 and defaults to 50, and `nextCursor` goes back as `cursor` while `hasMore` is true."
url: "https://openemail.uk/docs/api/contacts/list"
area: "API"
category: "Mailbox"
---

# List contacts

The workspace address book, most recently seen first, with contacts that have never been mailed last. Every key on the workspace reads the same rows, so a contact saved by one member is a contact every member and every key sees. Paging is keyset: `limit` goes up to 200 and defaults to 50, and `nextCursor` goes back as `cursor` while `hasMore` is true.

`GET /contacts`

## GET /contacts

The workspace address book, most recently seen first, with contacts that have never been mailed last. Every key on the workspace reads the same rows, so a contact saved by one member is a contact every member and every key sees. Paging is keyset: `limit` goes up to 200 and defaults to 50, and `nextCursor` goes back as `cursor` while `hasMore` is true.

## Example

Needs `contacts:read`.

**curl**

```
curl "$OE/contacts?limit=50" -H "$AUTH"
```

**Response**

```
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "source": "auto",
      "notes": null,
      "lastSeenAt": "2026-08-29T08:19:08.000Z",
      "createdAt": "2026-08-01T10:00:00.000Z",
      "updatedAt": "2026-08-29T08:19:08.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

> `source` is `manual` when somebody saved the address, in the app or through `POST /contacts`, and `auto` when it was recorded because a member sent mail to it from the composer. They are materially different claims (`auto` is evidence of correspondence, `manual` is evidence of intent) and worth branching on.

> The order is `lastSeenAt` descending with nulls last, then newest first. A contact you just created has no `lastSeenAt` and sorts at the end rather than the top.

> The book belongs to the workspace rather than to whoever saved a row. Mail arriving from an address creates nothing.