Update a message in a thread

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, blocked, 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 has at most 20 labels, system labels included.

Contact to link this message to, or null to unlink the current contact.

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.

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

Possible values: inbound, outbound

Channel this message lives on. Always email.

Conversation this message belongs to.

Sender address.

Recipient addresses on the To line.

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

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.

Message subject. Null when the message had no subject.

Short plain-text preview of the message body.

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 on this message. A received message always has exactly one placement label:

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.

Folded delivery status of a sent message:

Null for received messages.

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.

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. 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

Whether SPF passed for the sender of a received message. Null for sent messages and when no verdict is available. This field is kept for the mailbox's retention tier.

Whether DKIM passed for the sender of a received message. Null for sent messages and when no verdict is available. This field is kept for the mailbox's retention tier.

Whether DMARC passed for the sender of a received message. Null for sent messages and when no verdict is available. This field is kept for the mailbox's retention tier.

When the message will be permanently deleted: the end of the mailbox's retention tier, 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"]}}.

Number of attachments on the message.

Attachment metadata (filename, content type, size). Stays readable for the mailbox's retention tier even after the attachment bytes themselves have expired.

RFC 5322 References header entries used to thread the conversation.

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

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.

When the message was received or accepted for sending.