Update a message in a thread
PATCH
/v1/email/threads/{thread_id}/messages/{message_id}
curl -X PATCH "https://us1.platform.bird.com/v1/email/threads/{thread_id}/messages/{message_id}" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Applies read-state, label, and contact changes to a message in a conversation. Omitted fields are left unchanged. The read flag is only valid on received messages.
Request Payload
labels
object
Label changes to apply. Labels in add are applied and labels in remove are taken off; other labels are left untouched. Adding a label that is already present, or removing one that is not, has no effect. System labels express state changes: on a conversation, adding spam files it as spam, adding archive files it away without deleting it, adding inbox (or removing spam or archive) returns it to the inbox, and removing unread marks all retained received messages as read in one call; on a message, adding or removing unread flips read state, and adding or removing trash moves it to or out of the trash. Changes that contradict this model are rejected: adding more than one placement label in one request, adding blocked (blocking a sender is a receive-rule decision), removing inbox without adding a destination, adding trash or unread to a conversation (removing unread is the mark-all-read shortcut; trash uses the DELETE verb), placement labels on a message (move its conversation instead), and unread on a sent message. Custom labels are 1-64 characters with no commas, control characters, or leading or trailing whitespace. System label names and a small reserved set (all, archived, deleted, draft, drafts, flagged, important, junk, muted, none, outbox, pinned, read, scheduled, snoozed, starred) cannot be used as custom labels, in any casing. A conversation or message carries at most 20 labels, system labels included.
Show child parameters
labels.add
array of string
Labels to apply.
labels.remove
array of string
Labels to take off.
contact_id
nullable string
Contact to link this message to, or null to unlink the current contact.
Response Payload
id
string
required
Message ID. Received messages carry a rem_ ID, sent messages an em_ ID — the same IDs used by the received-message and sent-message logs.
direction
string
required
Direction of the message — inbound for a received message, outbound for a sent one.
Possible values: inbound, outbound
channel
string
required
Channel this message was carried 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 period, 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. System labels carry its state: a received message holds exactly one placement label — inbox for accepted mail, archive when its conversation was filed away, spam (failed sender authentication), or blocked (rejected by the mailbox's receive policy or rules) — plus unread until it is read. trash marks a message in the trash, either direction. Custom labels share the same list; a message carries at most 20.
status
nullable string
required
Folded delivery status of a sent message: accepted, sent (provider handoff), delivered (all attempted recipients delivered), or failed (terminal failure). Null for received messages.
recipients
nullable array
required
Terminal per-recipient delivery outcomes of a sent message, folded in as they become known — part of the message's durable memory. 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
Whether the sender of a received message was authenticated. pass means the sender's identity was verified; fail means it was checked and did not verify; unknown means no verdict could be determined and the sender should not be treated as verified. Null for sent messages. Part of the message's durable memory — readable for the mailbox's full retention period, so the verdict survives after the 30-day inbound log has expired.
Possible values: pass, fail, unknown, null
spf_pass
nullable boolean
required
Whether SPF passed for the sender of a received message. Null for sent messages and when no verdict is available. Durable for the mailbox's retention period.
dkim_pass
nullable boolean
required
Whether DKIM passed for the sender of a received message. Null for sent messages and when no verdict is available. Durable for the mailbox's retention period.
dmarc_pass
nullable boolean
required
Whether DMARC passed for the sender of a received message. Null for sent messages and when no verdict is available. Durable for the mailbox's retention period.
purge_at
string
required
When the message will be permanently deleted: the end of the mailbox's retention period, pulled nearer (at most 30 days out) 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). Remains readable for the mailbox's retention period even after the attachment bytes themselves have expired.
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 carries 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 original rendered source) expires.
occurred_at
string
required
When the message was received or accepted for sending.