---
title: "List contacts"
method: GET
path: "/mailboxes/{address}/contacts"
tags: ["Mail"]
---

# List contacts

`GET /mailboxes/{address}/contacts`

## Request

- Base URL: `https://faivelo.com/api/v1`
- URL: `https://faivelo.com/api/v1/mailboxes/{address}/contacts`
- Auth: HTTP bearer

The people this mailbox corresponds with: everyone it has written to (recent Sent mail) or heard from (recent Inbox mail), most frequent first, up to 500. The same list the MCP `get_contacts` tool returns. Requires scope `mail:read`.

## Path parameters

- `address` string, required

## Response `200`

Contacts, most frequent first

- object
  - `success` boolean
  - `data` Contact[]
    - `name` string: Display name as seen in mail, empty when unknown
    - `email` string
    - `count` integer: Messages exchanged with this address in the scanned mail
    - `lastSeen` string, date-time: Most recent message to or from them

## Other responses

- `401`: Missing or invalid API key
- `402`: The account's plan does not include the API (`plan_required`)
- `403`: The key lacks the required scope
- `404`: Resource not found
- `429`: Rate limit exceeded

---

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