v8
latestOpenAPI 3.1.02026-08-087720756.5 KBList 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 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
The maximum number of emails to return. Must be between 1 and 50. Defaults to 25.
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.
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.
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.
A comma-separated list of up to 10 email addresses. Emails that include at least one of them as a participant are returned.
A domain to filter emails by. Emails with at least one participant at this domain are returned.
Only return emails sent after this timestamp. sent_after is exclusive, so an email sent at exactly this timestamp is not returned.
Only return emails sent before this timestamp. sent_before is exclusive, so an email sent at exactly this timestamp is not returned.
Response
Success
Example response
{
"data": [
{
"id": {
"workspace_id": "14beef7a-99f7-4534-a87e-70b564330a4c",
"mailbox_id": "7f3a1c88-2e4b-4d59-9a0c-6b8d5e7f1a23",
"email_id": "d2c4f0a1-5b6e-4a7c-8d9e-1f2a3b4c5d6e"
},
"sent_at": "2023-01-01T15:00:00.000000000Z",
"direction": "outbound",
"subject_line": "Re: Q3 renewal",
"participants": [
{
"role": "from",
"email_address": "person@company.com",
"email_domain": "fundstack.com",
"name": "Simon Mitchell"
}
],
"linked_records": [
{
"object_slug": "people",
"object_id": "97052eb9-e65e-443f-a297-f2d9a4a7f795",
"record_id": "891dcbfc-9141-415d-9b2a-2238a6cc012d"
}
]
}
]
}