---
title: "List emails"
method: GET
path: "/v2/emails"
tags: ["Emails"]
---

# List emails

`GET /v2/emails`

Lists email metadata from your workspace's connected mailboxes. Email content is never returned.

At least one of `linked_object` with `linked_record_ids`, `participants`, or `domain` must be supplied; there is no way to list every email. When several are supplied they are combined with OR: emails matching any of the filters are returned.

> **Requesting access:** this endpoint is enabled per workspace and per app while it is in alpha. Contact [support@attio.com](mailto:support@attio.com) to request access.

**Things to know**

- Filters that identify your own workspace are ignored. This covers a member's or invited member's address, one of your mailboxes, and any of their domains. If every filter you supply is ignored, an empty page is returned.
- A filter that names a protected recipient in your workspace is rejected rather than ignored. This covers an address, a domain, and a record that resolves to either.
- Emails from a mailbox shared with your workspace as metadata only are returned without a subject line. An email is left out entirely when it has no participant you may see — that is, when every participant outside your workspace is a protected recipient.
- An email that reached more than one of your mailboxes is returned once, and `id.mailbox_id` identifies whichever copy was readable.
- `linked_records` is derived when you make the request rather than stored, so it reflects your records as they are now.
- Emails are returned newest first, ordered by when they were sent. Each request scans a bounded number of emails, so a page can hold fewer emails than `limit`, or none at all, while more are still available. Keep paginating for as long as a `next_cursor` is returned, rather than stopping on a short page.

This endpoint is in alpha and may be subject to breaking changes as we gather feedback.

Required scopes: `email:read`, `record_permission:read`, `object_configuration:read`.

## Query parameters

- `limit` integer — The maximum number of emails to return. Must be between 1 and 50. Defaults to 25.
- `cursor` string — A pagination cursor used to fetch the next page of emails. Responses with more emails will include a cursor for you to use here. If not provided, the first page will be returned.
- `linked_object` string — The object to filter emails by. Must be the slug or ID of either the people or companies object. If provided, linked_record_ids must also be provided.
- `linked_record_ids` string — A comma-separated list of up to 10 record IDs to filter emails by. All IDs must belong to the object given in `linked_object`, so filtering by both people and companies requires two requests. If provided, linked_object must also be provided.
- `participants` string — A comma-separated list of up to 10 email addresses. Emails that include at least one of them as a participant are returned.
- `domain` string — A domain to filter emails by. Emails with at least one participant at this domain are returned.
- `sent_after` string, nullable — Only return emails sent after this timestamp. `sent_after` is exclusive, so an email sent at exactly this timestamp is not returned.
- `sent_before` string, nullable — Only return emails sent before this timestamp. `sent_before` is exclusive, so an email sent at exactly this timestamp is not returned.

## Response `200`

Success

- object — Success
  - `data` Email[], required
    - `id` object, required
      - `workspace_id` string, uuid, required — The ID of the workspace the email belongs to.
      - `mailbox_id` string, uuid, required — The ID of the mailbox this copy of the email was read from. A single email sent to several people in your workspace is stored once per mailbox; this endpoint returns one entry per email, so the returned `mailbox_id` identifies whichever copy was readable.
      - `email_id` string, uuid, required — The ID of the Attio email.
    - `sent_at` string, required — Timestamp representing when the email was sent, taken from the email's own headers rather than from when Attio imported it.
    - `direction` 'inbound' | 'outbound', required — Whether the email was sent from your workspace or received by it.
    - `subject_line` string, nullable, required — The subject line of the email. This is `null` when the email has no subject or is from a mailbox shared as metadata only.
    - `participants` object[], required — The participants on the email. Note that `bcc` participants are realistically only present on outbound email: inbound messages do not disclose the other recipients' blind copies, so an absent `bcc` participant is not evidence that there was none.
      - `role` 'from' | 'reply-to' | 'to' | 'cc' | 'bcc', required — The role this participant had on the email.
      - `email_address` string, required — The normalized email address of the participant.
      - `email_domain` string, required — The domain of the participant's email address.
      - `name` string, nullable, required — The participant's name as it appeared on the email, when the email provided one.
    - `linked_records` object[], required — The person and company records whose email addresses or domains match this email's participants. Unlike meetings, this link is derived when you make the request rather than stored, so it reflects your records as they are now: creating a person record today will make older emails start reporting it.
      - `object_slug` string, required — The slug of the object the linked record belongs to.
      - `object_id` string, uuid, required — The ID of the object the linked record belongs to.
      - `record_id` string, uuid, required — The ID of the linked record.
  - `pagination` object, required
    - `next_cursor` string, nullable, required

---

[API](https://skmtc.net/attio/apis/attio-api.md) · [All operations](https://skmtc.net/attio/apis/attio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/attio/attio-api/revisions/6ad6c02e6af9/schema)