List threads

GET

/v1/email/threads

for await (const thread of bird.email.threads.list({ mailbox_id: "mbx_01abc" })) {
  console.log(thread.id, thread.subject);
}

for thread in client.email.threads.list(mailbox_id="mbx_01krdgeqcxet5s7t44vh8rt9mg"):
    print(thread.id, thread.subject)

for thread, err := range client.Email.Threads.List(context.Background(), bird.EmailThreadsListParams{}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(thread.Id)
}

foreach ($bird->email->threads->list(['mailbox_id' => 'mbx_01krdgeqcxet5s7t44vh8rt9mg']) as $thread) {
    echo $thread->getId(), ' ', $thread->getSubject(), "\n";
}

bird email threads list

curl -X GET "https://us1.platform.bird.com/v1/email/threads" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "label=urgent" \
  --url-query "participant=billing@acme.com" \
  --url-query "subject=quarterly invoice" \
  --url-query "limit=25"

Response200

{
  "data": [
    {
      "id": "thr_01krdgeqcxet5s7t44vh8rt9mg",
      "mailbox_id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
      "channel": "email",
      "contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
      "subject": "Re: Your order",
      "last_direction": "inbound",
      "labels": [
        "inbox",
        "urgent"
      ],
      "highlights": {
        "subject": [
          "Re: your **order** **4821**"
        ],
        "text": [
          "confirming your **order** **4821** shipped"
        ]
      }
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Returns a paginated list of conversations across the workspace's mailboxes, most recently active first. label selects the view: the inbox (the default when omitted), archive, spam, blocked, or any custom label. You can also filter by mailbox, by linked contact, by participant address, or by a subject substring.

This listing filters; it does not search message content. Conversations whose every message is trashed are excluded; restoring a message returns the conversation to the list.

before and after filter by time. To page through the results, pass the response cursors back as starting_after or ending_before.

Query Parameters

mailbox_idstring

Filter to conversations in a specific mailbox.

contact_idstring

Filter to conversations linked to a specific contact.

labelarray

Filter to conversations that have this label. Repeat the parameter to ask for more than one: only conversations that have every label you list are returned.

A placement label picks a folder: inbox, archive, spam, or blocked. A custom label matches a conversation in any folder. Leave this out and you get the inbox.

has_unreadboolean

When true, only conversations with unread messages are returned. This filters on the conversation's unread state, so you can combine it with label, for example to get unread conversations in the archive. The unread label itself lives on individual messages; this filter uses the conversation's aggregate unread state.

participantstring

Conversations involving this address, matching the sender or any recipient. The match is case-insensitive and matches on any part of the address, so a fragment works as well as the whole address.

subjectstring

Conversations whose subject contains this text (case-insensitive).

afterstring

Filter to conversations whose most recent message is at or after this time. Use the response cursors for pagination.

beforestring

Filter to conversations whose most recent message is at or before this time. Use the response cursors for pagination.

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

Response Payload

data

array of object

required

Show child attributes

data.id

string

required

Thread ID.

data.mailbox_id

string

required

Mailbox this conversation belongs to.

data.channel

string

required

Channel this conversation lives on. Always email.

data.contact_id

nullable string

required

Contact linked to this conversation, or null when none is linked.

data.subject

nullable string

required

Subject of the conversation, taken from its first message. Null when that message had no subject.

data.participants

array of string

required

Addresses that appear on the retained messages in this conversation, including the mailbox's own address.

data.message_count

integer

required

Number of retained messages in this conversation, both directions.

data.unread_count

integer

required

Number of retained received messages that are still unread. Spam and blocked mail is not counted.

data.last_message_at

string

required

When the most recent retained message in this conversation was received or sent.

data.last_direction

string

required

Direction of the most recent message: inbound for a received message, outbound for a sent one.

Possible values: inbound, outbound

data.labels

array of string

required

Labels on this conversation. Exactly one system placement label is always present, set by the message that started the conversation:

inbox: The conversation is in the inbox.
archive: The conversation was filed away and is done for now.
spam: The conversation's opening message is filed in Spam.
blocked: The conversation's opening message was rejected by the mailbox's receive policy or rules.

Move a conversation by updating its labels. Add spam to file it as spam, add archive to clean it out of the inbox, and add inbox, or remove spam, blocked, or archive, to bring it back. An archived conversation returns to the inbox by itself when a new message arrives. Custom labels share the same list, and a conversation has at most 20 labels in total.

data.created_at

string

required

When the thread was created.

data.updated_at

string

required

When the thread last changed.

data.highlights

object

Matched search fragments, keyed by the field that matched. Returned only by thread search. Omitted when listing threads.

Show child attributes

data.highlights.subject

array of string

Matched fragments from the conversation's subject.

data.highlights.text

array of string

Matched fragments from a message's body text.

next_cursor

nullable string

required

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursor

nullable string

required

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursor

nullable string

required

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Continue with the documentation, guides and examples for this topic.

Try the practice and get an implementation brief

for await (const thread of bird.email.threads.list({ mailbox_id: "mbx_01abc" })) {
  console.log(thread.id, thread.subject);
}

for thread in client.email.threads.list(mailbox_id="mbx_01krdgeqcxet5s7t44vh8rt9mg"):
    print(thread.id, thread.subject)

for thread, err := range client.Email.Threads.List(context.Background(), bird.EmailThreadsListParams{}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(thread.Id)
}

foreach ($bird->email->threads->list(['mailbox_id' => 'mbx_01krdgeqcxet5s7t44vh8rt9mg']) as $thread) {
    echo $thread->getId(), ' ', $thread->getSubject(), "\n";
}

bird email threads list

curl -X GET "https://us1.platform.bird.com/v1/email/threads" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "label=urgent" \
  --url-query "participant=billing@acme.com" \
  --url-query "subject=quarterly invoice" \
  --url-query "limit=25"

Response200

{
  "data": [
    {
      "id": "thr_01krdgeqcxet5s7t44vh8rt9mg",
      "mailbox_id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
      "channel": "email",
      "contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
      "subject": "Re: Your order",
      "last_direction": "inbound",
      "labels": [
        "inbox",
        "urgent"
      ],
      "highlights": {
        "subject": [
          "Re: your **order** **4821**"
        ],
        "text": [
          "confirming your **order** **4821** shipped"
        ]
      }
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

List threads

Query Parameters

Response Payload

Related resources