> ## Documentation Index > Fetch the complete documentation index at: https://docs.attio.com/llms.txt > Use this file to discover all available pages before exploring further. # List 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`. ## OpenAPI ````yaml https://api.attio.com/openapi/api get /v2/emails openapi: 3.1.0 info: title: Attio API version: 2.0.0 contact: name: Attio Support email: support@attio.com url: https://attio.com/help servers: - url: https://api.attio.com description: Production security: - oauth2: [] tags: - name: Objects description: >- Objects are the core data models inside of Attio. They contain standard objects, such as [people](/rest-api/endpoint-reference/standard-objects/people/list-person-records), [companies](/rest-api/endpoint-reference/standard-objects/companies/list-company-records) or [deals](/docs/standard-objects-deals), and custom objects that are specific to your use-case. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Object views description: Object views are saved table or board layouts for an object. - name: List views description: List views are saved table or board layouts for a list. - name: Attributes description: >- Attributes model properties of objects and lists. Some attributes, such as the `name` attribute on a person, are system-defined, while others are user-defined. Attributes are one of [many types](/docs/attribute-types) such as text, location or select. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Records description: >- Records are individual instances of objects e.g. a specific [person](/rest-api/endpoint-reference/standard-objects/people/list-person-records) or [company](/rest-api/endpoint-reference/standard-objects/companies/list-company-records). See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: SCIM groups description: >- SCIM groups represent Attio teams managed through the SCIM provisioning protocol. - name: SCIM schemas description: >- SCIM schemas describe the resource types supported by the SCIM service provider. - name: SCIM users description: >- SCIM users represent workspace members managed through the SCIM provisioning protocol. - name: Lists description: >- Lists are used to model a particular process. A list contains many records of a single object type, where each record is represented by an entry. Entries contain their own data from attributes defined on the list and also data from their parent record. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Meta description: Meta endpoints are used to get information about the API token. - name: Entries description: >- Entries are elements in a list that reference a single parent record. Entries contain their own data from attributes defined on the list and also data from their parent record. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Files description: >- Files are documents and folders linked to records, stored either in Attio or connected via external storage providers. - name: Workspace members description: >- Workspace members represent a user with access to a workspace. Workspace members are assigned roles that determine what they can do within the workspace. - name: Notes description: Notes are rich text documents that reference a single parent record. - name: Meetings description: >- Meetings are events synced from your calendar, added manually or added from third-party integrations. - name: Emails description: >- Emails are messages synced from connected mailboxes. This API exposes their metadata — participants, subject line and timestamps — and never their content. - name: Call recordings description: >- Call recordings store video, audio, transcript and speaker information for calls. They are linked to meetings. - name: Transcripts description: >- Transcripts contain the speech segments and speaker information for a call recording. They are linked to call recordings. - name: Tasks description: >- A task is a defined, actionable item with references to linked records and assigned workspace members. - name: Webhooks description: >- Webhooks allow you to listen for changes to data in Attio, for example when a record is updated. - name: Threads description: >- Threads are groups of [comments](/rest-api/endpoint-reference/comments/get-a-comment) on either a record or entry. - name: Comments description: >- Comments are messages on a [thread](/rest-api/endpoint-reference/threads/list-threads). - name: People description: >- People are one of the core objects inside of Attio. Person records can be added to lists and can be created automatically when syncing your mailbox. - name: Companies description: >- Companies are one of the core objects inside of Attio. Company records can be added to lists and can be created automatically when syncing your mailbox. - name: Users description: >- Users are an optional standard object that represents a user of your system. Users can belong to many workspaces. - name: Deals description: >- Deals are an optional standard object that represent a deal or opportunity. - name: Workspaces description: >- Workspaces are an optional standard object that represent a workspace or account in your system. Workspaces have many users and can be used to model a multi-tenant system. A company record can optionally have multiple workspaces. - name: SQL description: >- Query records and list entries across your workspace using SQL. A single query can reference any object or list in the workspace. paths: /v2/emails: get: tags: - Emails summary: List emails description: >- 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`. parameters: - schema: type: integer minimum: 1 maximum: 50 default: 25 description: >- The maximum number of emails to return. Must be between 1 and 50. Defaults to 25. example: 25 required: false name: limit in: query - schema: type: string description: >- 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. required: false name: cursor in: query - schema: type: string minLength: 1 description: >- 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. required: false name: linked_object in: query - schema: type: string description: >- 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. required: false name: linked_record_ids in: query - schema: type: string default: '' description: >- A comma-separated list of up to 10 email addresses. Emails that include at least one of them as a participant are returned. required: false name: participants in: query - schema: type: string minLength: 1 description: >- A domain to filter emails by. Emails with at least one participant at this domain are returned. example: fundstack.com required: false name: domain in: query - schema: type: - string - 'null' description: >- Only return emails sent after this timestamp. `sent_after` is exclusive, so an email sent at exactly this timestamp is not returned. required: false name: sent_after in: query - schema: type: - string - 'null' description: >- Only return emails sent before this timestamp. `sent_before` is exclusive, so an email sent at exactly this timestamp is not returned. required: false name: sent_before in: query responses: '200': description: Success content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/email' pagination: type: object properties: next_cursor: type: - string - 'null' required: - next_cursor required: - data - pagination description: Success security: - oauth2: - email:read - record_permission:read - object_configuration:read components: schemas: email: type: object properties: id: type: object properties: workspace_id: type: string format: uuid description: The ID of the workspace the email belongs to. example: 14beef7a-99f7-4534-a87e-70b564330a4c mailbox_id: type: string format: uuid description: >- 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. example: 7f3a1c88-2e4b-4d59-9a0c-6b8d5e7f1a23 email_id: type: string format: uuid description: The ID of the Attio email. example: d2c4f0a1-5b6e-4a7c-8d9e-1f2a3b4c5d6e required: - workspace_id - mailbox_id - email_id sent_at: type: string description: >- Timestamp representing when the email was sent, taken from the email's own headers rather than from when Attio imported it. example: '2023-01-01T15:00:00.000000000Z' direction: type: string enum: - inbound - outbound description: Whether the email was sent from your workspace or received by it. example: outbound subject_line: type: - string - 'null' description: >- The subject line of the email. This is `null` when the email has no subject or is from a mailbox shared as metadata only. example: 'Re: Q3 renewal' participants: type: array items: type: object properties: role: type: string enum: - from - reply-to - to - cc - bcc description: The role this participant had on the email. example: from email_address: type: string description: The normalized email address of the participant. example: person@company.com email_domain: type: string description: The domain of the participant's email address. example: fundstack.com name: type: - string - 'null' description: >- The participant's name as it appeared on the email, when the email provided one. example: Simon Mitchell required: - role - email_address - email_domain - name description: >- 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. linked_records: type: array items: type: object properties: object_slug: type: string description: The slug of the object the linked record belongs to. example: people object_id: type: string format: uuid description: The ID of the object the linked record belongs to. example: 97052eb9-e65e-443f-a297-f2d9a4a7f795 record_id: type: string format: uuid description: The ID of the linked record. example: 891dcbfc-9141-415d-9b2a-2238a6cc012d required: - object_slug - object_id - record_id description: >- 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. required: - id - sent_at - direction - subject_line - participants - linked_records securitySchemes: oauth2: type: oauth2 description: This API uses OAuth 2.0 with the authorization code grant flow. flows: authorizationCode: authorizationUrl: https://app.attio.com/authorize tokenUrl: https://app.attio.com/oauth/token scopes: user_management:read: View workspace members. user_management:read-write: View workspace members. record_permission:read: View, and optionally write, records. record_permission:read-write: View, and optionally write, records. object_configuration:read: >- View, and optionally write, the configuration and attributes of objects. object_configuration:read-write: >- View, and optionally write, the configuration and attributes of objects. list_entry:read: View, and optionally write, the entries in a list. list_entry:read-write: View, and optionally write, the entries in a list. list_configuration:read: >- View, and optionally write, the configuration and attributes of lists. list_configuration:read-write: >- View, and optionally write, the configuration and attributes of lists. public_collection:read: >- View, and optionally write, both the settings and information within public collections. public_collection:read-write: >- View, and optionally write, both the settings and information within public collections. private_collection:read: >- View, and optionally modify, both the settings and information of all collections within the workspace, regardless of their access settings. private_collection:read-write: >- View, and optionally modify, both the settings and information of all collections within the workspace, regardless of their access settings. comment:read: View comments (and threads), and optionally write comments. comment:read-write: View comments (and threads), and optionally write comments. task:read: View, and optionally write, tasks. task:read-write: View, and optionally write, tasks. note:read: View, and optionally write, notes. note:read-write: View, and optionally write, notes. meeting:read: View, and optionally write, meetings. meeting:read-write: View, and optionally write, meetings. call_recording:read: >- View, and optionally write, call recordings, transcripts and speakers for meetings. call_recording:read-write: >- View, and optionally write, call recordings, transcripts and speakers for meetings. webhook:read: View, and optionally manage, webhooks. webhook:read-write: View, and optionally manage, webhooks. file:read: View, and upload files. file:read-write: View, and upload files. email:read: View email metadata. Email content is never exposed. email:read-write: View email metadata. Email content is never exposed. ````