List messages in a thread

GET

/v1/email/threads/{thread_id}/messages

for await (const msg of bird.email.threads.messages.list("thr_01abc")) {
  console.log(msg.id, msg.direction);
}

for message in client.email.threads.messages.list("thr_01krdgeqcxet5s7t44vh8rt9mg"):
    print(message.id, message.subject)

for msg, err := range client.Email.Threads.Messages.List(context.Background(), "thr_123", bird.EmailThreadsMessagesListParams{}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, msg.Direction)
}

foreach ($bird->email->threads->messages->list('thr_01krdgeqcxet5s7t44vh8rt9mg') as $message) {
    echo $message->getId(), ' ', $message->getDirection(), "\n";
}

bird email threads messages list <thread-id>

curl -X GET "https://us1.platform.bird.com/v1/email/threads/{thread_id}/messages" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "label=unread" \
  --url-query "limit=25"

Resposta200

{
  "data": [
    {
      "id": "rem_01krdgeqcxet5s7t44vh8rt9mg",
      "direction": "inbound",
      "channel": "email",
      "thread_id": "thr_01krdgeqcxet5s7t44vh8rt9mg",
      "subject": "Re: Your order",
      "labels": [
        "inbox",
        "unread"
      ],
      "recipients": [
        {
          "status": "delivered"
        }
      ],
      "authentication": "pass",
      "attachment_manifest": [
        {
          "id": "rea_01krdgeqcxet5s7t44vh8rt9mg",
          "filename": "invoice.pdf",
          "content_type": "application/pdf"
        }
      ],
      "contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
      "source": {
        "resource": "/v1/email/inbound-messages/rem_01krdgeqcxet5s7t44vh8rt9mg"
      }
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Returns the messages in a conversation, newest first, both received and sent. To page through older messages, use starting_after. The sort order is fixed, so to render the messages in conversation order, reverse the page yourself.

By default, every message that is not in the trash is returned, whichever folder the conversation is in. Pass label to narrow the view instead: use trash for trashed messages, or any custom label.

Pass include=extracted_text to inline each message's extracted plain text. A thread whose retention tier has ended returns 410 Gone.

Parâmetros

thread_id

string

Thread identifier. Starts with thr_.

Parâmetros de consulta

direction

string

Filter to received (inbound) or sent (outbound) messages.

Possible values: outbound, inbound

label

string

Filter to messages that have this label. trash lists trashed messages. Any other label, whether that is archive, spam, blocked, unread or one of your own, lists the messages that have it and are not in the trash. When omitted, every message that is not trashed is returned, whichever folder the conversation is in.

include

string

Set to extracted_text to inline each message's extracted plain text.

Possible values: extracted_text

limit

integer

Maximum number of items to return per page.

starting_after

string

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

ending_before

string

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.

Payload de resposta

data

array of object

obrigatório

Mostrar atributos secundários

data.id

string

obrigatório

Message ID. Received messages have a rem_ ID, sent messages an em_ ID: the same IDs used by the received-message and sent-message logs.

data.direction

string

obrigatório

Which way the message went. inbound means you received it, outbound means you sent it.

Possible values: inbound, outbound

data.channel

string

obrigatório

Channel this message lives on. Always email.

data.thread_id

string

obrigatório

Conversation this message belongs to.

data.from

string

obrigatório

Sender address.

data.to

array of string

obrigatório

Recipient addresses on the To line.

data.cc

array of string

obrigatório

Recipient addresses on the Cc line. Empty when the message had none.

data.delivered_to

nullable string

obrigatório

Address the message was actually delivered to, when it differs from the mailbox address (for example mail routed in from another address). Null for sent messages and for mail addressed directly to the mailbox.

data.subject

nullable string

obrigatório

Message subject. Null when the message had no subject.

data.preview

nullable string

obrigatório

Short plain-text preview of the message body.

data.extracted_text

nullable string

Plain-text content of the message with quoted history stripped. Readable for the mailbox's full retention tier, in both directions. Always present when fetching a single message. On list endpoints it is included only when the request sets include=extracted_text. Null when no text could be extracted.

data.labels

array of string

obrigatório

Labels on this message. A received message always has exactly one placement label:

inbox: Accepted mail.
archive: The message's conversation was filed away.
spam: The message is filed in Spam.
blocked: The message was rejected by the mailbox's receive policy or rules.

A received message also has unread until it is read. trash marks a message in the trash, in either direction. Custom labels share the same list, and a message has at most 20 labels in total.

data.status

nullable string

obrigatório

Aggregate delivery status of a sent message:

accepted: Accepted for sending.
sent: Handed off to the provider.
delivered: All attempted recipients delivered.
failed: Terminal failure.

Null for received messages.

data.recipients

nullable array

obrigatório

Terminal per-recipient delivery outcomes of a sent message, filled in as each one becomes known and kept for the mailbox's full retention tier. Null for received messages and before any recipient reaches a terminal state. Per-recipient event detail lives on the sent-message log (source) for 30 days.

data.authentication

nullable string

obrigatório

DMARC result for the domain in the received message's From header.

pass: SPF or DKIM passed and aligned with that domain.
fail: DMARC was evaluated and did not pass.
unknown: no trustworthy verdict is available.

This follows dmarc_pass and does not verify a particular person. The receiving provider currently supplies no DMARC result, so received messages report unknown.

Null for sent messages. This field is readable for the mailbox's full retention tier, so the verdict is still available after the 30-day received-message log has expired.

Possible values: pass, fail, unknown, null

data.spf_pass

nullable boolean

obrigatório

Whether the receiving provider reports that SPF authorized the envelope sender for the sending server. A soft failure is false. Missing, neutral and inconclusive results are null. Sent messages have null results. Kept for the mailbox retention tier.

data.dkim_pass

nullable boolean

obrigatório

Whether the receiving provider verified a DKIM signature. A passing signature makes this true even when another signature fails. Missing signatures and inconclusive verification results are null. Sent messages have null results. Kept for the mailbox retention tier.

data.dmarc_pass

nullable boolean

obrigatório

Whether SPF or DKIM passed and aligned with the domain in the message's From header. The receiving provider currently supplies no DMARC result, so this is null. Sent messages have null results. Kept for the mailbox retention tier.

data.purge_at

string

obrigatório

Scheduled permanent-deletion time. This is the end of the mailbox's retention tier, moved to no more than 30 days in the future while the message is in the trash. Restore a trashed message before then with PATCH {"labels": {"remove": ["trash"]}}.

data.attachment_count

integer

obrigatório

Number of attachments on the message.

data.attachment_manifest

array of object

obrigatório

Attachment metadata (filename, content type, size). Both the metadata and the attachment bytes stay available for the mailbox's retention tier.

Mostrar atributos secundários

data.attachment_manifest.id

string

obrigatório

Attachment ID, used to download the attachment bytes.

data.attachment_manifest.filename

nullable string

obrigatório

Original filename, or null when the attachment had none.

data.attachment_manifest.content_type

nullable string

obrigatório

MIME content type, or null when it could not be determined.

data.attachment_manifest.size

integer

obrigatório

Attachment size in bytes.

data.reference_ids

array of string

obrigatório

RFC 5322 References header entries used to thread the conversation.

data.contact_id

nullable string

obrigatório

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

data.source

object

obrigatório

Link to the message's entry in the received-message or sent-message log, which has delivery analytics such as per-recipient events. Log entries expire 30 days after the message occurred.

Mostrar atributos secundários

data.source.resource

string

obrigatório

API path of the log entry for this message.

data.source.available_until

string

obrigatório

When the log entry (and the message's body and raw MIME) expires.

data.occurred_at

string

obrigatório

When the message was received or accepted for sending.

next_cursor

nullable string

obrigatório

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

prev_cursor

nullable string

obrigatório

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

refresh_cursor

nullable string

obrigatório

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.

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaGetting started with email Explore a funcionalidadeEmail Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first email

Experimente na prática e obtenha um resumo de implementação

for await (const msg of bird.email.threads.messages.list("thr_01abc")) {
  console.log(msg.id, msg.direction);
}

for message in client.email.threads.messages.list("thr_01krdgeqcxet5s7t44vh8rt9mg"):
    print(message.id, message.subject)

for msg, err := range client.Email.Threads.Messages.List(context.Background(), "thr_123", bird.EmailThreadsMessagesListParams{}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, msg.Direction)
}

foreach ($bird->email->threads->messages->list('thr_01krdgeqcxet5s7t44vh8rt9mg') as $message) {
    echo $message->getId(), ' ', $message->getDirection(), "\n";
}

bird email threads messages list <thread-id>

curl -X GET "https://us1.platform.bird.com/v1/email/threads/{thread_id}/messages" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "label=unread" \
  --url-query "limit=25"

Resposta200

{
  "data": [
    {
      "id": "rem_01krdgeqcxet5s7t44vh8rt9mg",
      "direction": "inbound",
      "channel": "email",
      "thread_id": "thr_01krdgeqcxet5s7t44vh8rt9mg",
      "subject": "Re: Your order",
      "labels": [
        "inbox",
        "unread"
      ],
      "recipients": [
        {
          "status": "delivered"
        }
      ],
      "authentication": "pass",
      "attachment_manifest": [
        {
          "id": "rea_01krdgeqcxet5s7t44vh8rt9mg",
          "filename": "invoice.pdf",
          "content_type": "application/pdf"
        }
      ],
      "contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
      "source": {
        "resource": "/v1/email/inbound-messages/rem_01krdgeqcxet5s7t44vh8rt9mg"
      }
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}