Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Reply to a thread message

POST
/v1/email/threads/{thread_id}/messages/{message_id}/reply
const reply = await bird.email.threads.messages.reply("thr_01abc", "rem_01xyz", {
  text: "Thanks for reaching out!",
});
console.log(reply.id);
Response202
{
  "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"
  }
}

Sends a reply to a specific message in a conversation, from the mailbox's own address. Recipients are derived from the message being replied to: for a received message, its Reply-To address when present, otherwise its From address; for a message the mailbox sent, its original To recipients. Set reply_all to copy the original To and Cc recipients in as Cc, leaving out the mailbox's own address. The subject and the threading headers that keep the reply in this conversation are set automatically, and the reply is recorded in the conversation. To reply to a conversation as a whole, target its newest received message.

Parameters

thread_idstring

Thread identifier. Starts with thr_.

message_idstring

Message ID (rem_ for a received message, em_ for a sent one).

Request Payload

html
string

HTML body of the reply. At least one of html or text must be provided.

text
string

Plain-text body of the reply. At least one of html or text must be provided.

reply_all
boolean

Also send the reply to the original To and Cc recipients, minus the mailbox's own address.

tags
array of object

Structured {name, value} labels for filtering and analytics on the sent-message log. Cap: 20 tags per send.

Show child parameters
tags.name
string
required

Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.

tags.value
string
required

Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.

metadata
object

Arbitrary JSON object stored on the send and echoed in webhook payloads. Cap: 2 KB serialized.

category
string

Content classification, which controls suppression policy:

  • marketing: Blocks on all suppression reasons.
  • transactional: Allows delivery through complaint and unsubscribe suppressions, for receipts, password resets, and similar operational mail.

Possible values: marketing, transactional

attachments
array of object

File attachments to include with the reply. The send is rejected when the estimated generated message size exceeds 20 MB (bodies plus all attachments after base64 encoding). Keep total raw attachment content at or below 15 MB for reliable headroom. Attachment metadata stays on the message's attachment_manifest, and the bytes are downloadable for the mailbox's retention tier.

Show child parameters
attachments.filename
string
required

The name the recipient sees on the attachment.

attachments.content
string
required

Base64-encoded file bytes. The encoded value and MIME wrapping count toward the 20 MB message limit.

attachments.content_type
string

The file's MIME type. If omitted, the API infers it from the extension in filename. The API rejects executable and script types based on this value.

attachments.content_id
string

An RFC 2392 Content-ID for an inline file. Reference it from the HTML body with <img src="cid:{content_id}"/>. Omit it to send a downloadable attachment.

Response Payload

id
string
required

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.

direction
string
required

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

Possible values: inbound, outbound

channel
string
required

Channel this message lives on. Always email.

thread_id
string
required

Conversation this message belongs to.

from
string
required

Sender address.

to
array of string
required

Recipient addresses on the To line.

cc
array of string
required

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

delivered_to
nullable string
required

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.

subject
nullable string
required

Message subject. Null when the message had no subject.

preview
nullable string
required

Short plain-text preview of the message body.

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.

labels
array of string
required

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.

status
nullable string
required

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.

recipients
nullable array
required

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.

authentication
nullable string
required

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

spf_pass
nullable boolean
required

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.

dkim_pass
nullable boolean
required

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.

dmarc_pass
nullable boolean
required

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.

purge_at
string
required

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"]}}.

attachment_count
integer
required

Number of attachments on the message.

attachment_manifest
array of object
required

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

Show child attributes
attachment_manifest.id
string
required

Attachment ID, used to download the attachment bytes.

attachment_manifest.filename
nullable string
required

Original filename, or null when the attachment had none.

attachment_manifest.content_type
nullable string
required

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

attachment_manifest.size
integer
required

Attachment size in bytes.

reference_ids
array of string
required

RFC 5322 References header entries used to thread the conversation.

contact_id
nullable string
required

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

source
object
required

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.

Show child attributes
source.resource
string
required

API path of the log entry for this message.

source.available_until
string
required

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

occurred_at
string
required

When the message was received or accepted for sending.

Related resources

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

Try the practice and get an implementation brief