Update a thread - Threads - API Reference

PUT

https://api.us.nylas.com/v3/grants/{grant_id}/threads/{thread_id}

Updates the specified thread.

When you make a PUT request, Nylas replaces all data in the nested object with the information included in your request. For more information, see Updating objects.

NYLAS API KEYACCESS TOKEN

Parameters

Path parameters

grant_id*string

ID of the grant to access. Use /me/ to refer to the grant associated with an access token.

thread_id*string

ID of the thread to access. Nylas recommends you URL-encode this field, or you might receive a 404 error if the ID contains special characters (for example, #).

Query parameters

selectstring

Specify fields that you want Nylas to return, as a comma-separated list (for example, select=id,updated_at). This allows you to receive only the portion of object data that you're interested in. You can use select to optimize response size and reduce latency by limiting queries to only the information that you need.

shared_folder_idstring

(Microsoft only) When provided, Nylas returns items from the specified shared folder ID. Required when using shared_from. This parameter only accepts a single folder ID. Check out the Shared folders guide for more information.

shared_fromstring

(Microsoft only) When provided, Nylas returns items that were shared from the specified email address. It also accepts grant ID. This parameter only accepts single email address or grant ID. Check out the Shared folders guide for more information.

Request body

starredboolean

When true, indicates that the thread is starred.

Example: true

unreadboolean

When false, indicates that all messages in the thread have been read.

Example: true

foldersarray<string>

The IDs of the folders to apply to the thread. This overwrites all previously assigned folders for all messages in the thread.

Example: ["folder-1","folder-2"]

Responses

request_idstring

The request ID.

dataobject

grant_idstringread-only

The ID of grant for the connected user.

Example: "41009df5-bf11-4c97-aa18-b285b5f2e386"

idstring

A globally unique object identifier for Microsoft accounts. An email address for Google accounts.

Example: "5d3qmne77v32r8l4phyuksl2x, [email protected]"

minLength: 1

objectstring

The type of object (in this case, thread).

latest_draft_or_messageobject

The latest message or draft in the thread.

attachmentsarray<object>

An array of Attachment objects. For Google, linked Google Drive files are not included. For Microsoft, linked OneDrive files are not included.

Example:

[{"content_disposition":"attachment","content_type":"text/calendar","id":"4kj2jrcoj9ve5j9yxqz5cuv98","size":1708},{"content_disposition":"attachment","content_type":"application/ics","filename":"invite.ics","id":"70jcsv367jaiavt4njeu4xswg","size":1708}]

minItems: 0

bccarray<object>

An array of name/email address pairs that the message was BCC'd to. For received messages, this is nearly always empty.

bodystring

The body of the message as either plain-text or HTML content. If the message has both plain-text and HTML, Nylas returns the HTML version.

Example: "Hello, I just sent a message using Nylas!"

ccarray<object>

An array of name/email address pairs that the message was CC'd to.

dateinteger

Unix timestamp in seconds that represents when the mail server received the message. This might be different from the unified Date header in a raw Message object.

Example: 1635355739

foldersarray<string>

The IDs of the folders that the message appears in. Microsoft messages can be in a single folder only. Google allows a single message to appear in multiple folders.

Example: ["8l6c4d11y1p4dm4fxj52whyr9","d9zkcr2tljpu3m4qpj7l2hbr0"]

fromarray<object>

A list of name/email address pairs that the message was sent from. This is usually one pair only, but can be many.

grant_idstringread-only

The ID of grant for the connected user.

Example: "41009df5-bf11-4c97-aa18-b285b5f2e386"

headersarray<object>

An array of key-value pairs that contain the message headers. Nylas returns this field when you set the fields query parameter to either include_headers or include_basic_headers.

fields=include_headers: Returns the full set of headers on the message.
fields=include_basic_headers: Returns only the three RFC threading headers (Message-ID, In-Reply-To, References). Use this option when you only need to track message identity and thread relationships — payload size is significantly smaller than include_headers.

A single message can sometimes have multiple headers with the same key name. Nylas adds all of the headers to the headers array without merging or de-duplicating the data. When the headers contain encoded data, Nylas adds it to the headers array without decoding it. If you need the decoded data, you need to build decoding logic into your project.

Some headers might contain raw MIME information (for example, =?Windows-1252?Q?Re:_Candidature_de_Mme_Leyah_Miller?=).

idstring

A globally unique object identifier for Microsoft accounts. An email address for Google accounts.

Example: "5d3qmne77v32r8l4phyuksl2x, [email protected]"

minLength: 1

in_reply_tostring

(EWS only) The ID of the message that this message replies to. This ID is the same as the In-Reply-To header.

Example: "<[email protected]>"

metadataobject

The metadata associated with the object. For more information, see Metadata.

objectstring

The object type of the response (in this case, message).

Example: "message"

raw_mimestring

A Base64url-encoded string containing the message data (including the body content).

To get the raw MIME content for a message, set the fields query parameter to raw_mime in your request. When you request raw MIME data, Nylas returns the grant_id, object, id, and raw_mime fields only.

reply_toarray<object>

An array of name/email address pairs that should receive replies to the message.

snippetstring

A short snippet (the first 100 characters, with HTML tags removed) of the message body. This is useful for displaying a preview of the message.

Example:

"You have been invited to the following event. Welcome! WhenThu Oct 28, 2021\n7am - 8am Eastern Time - Toronto Joining info"

minLength: 1

starredboolean

If true, shows that the message has been starred by the user. For EWS, this is only supported on Microsoft Exchange 2010 or later.

Example: false

subjectstring

The subject of the message.

Example: "Nylas Send v3 Email"

thread_idstring

A reference to the parent Thread object. Every message is associated with a thread, whether that thread contains one message or many. If the message is new, Nylas assigns a thread_id to it.

Example: "1t8tv3890q4vgmwq6pmdwm8qgsaer"

minLength: 1

toarray<object>

An array of name/email address pairs that the message was sent to.

tracking_optionsobject

Tracking options for the message.

unreadboolean

If true, shows that the message has not been read by the user.

Example: true

has_attachmentsboolean

When true, indicates that the message has attachments.

Example: false

has_draftsboolean

When true, indicates that the message is a draft.

Example: false

earliest_message_dateinteger

The date when the earliest or first message in the thread was sent or received, in seconds using the Unix timestamp format.

latest_message_received_dateinteger

The date when the most recent incoming message in the thread was received, in seconds using the Unix timestamp format.

latest_message_sent_dateinteger

The date when the most recent outgoing message in the thread was sent, in seconds using the Unix timestamp format.

participantsarray<object>

A sub-object that contains the names and email addresses of all participants in the thread.

snippetstring

A short snippet (the first 100 characters, with HTML tags removed) of the body of the last received message. This is useful for displaying a preview of a message.

Example: "jnlnnn --Sent with Nylas"

minLength: 1

starredboolean

When true, indicates that the thread is starred. For EWS, this is only supported for Microsoft Exchange 2010 or later.

Example: false

subjectstring

The subject line of the thread.

Example: "Nylas Send v3 Thread"

unreadboolean

When false, indicates that all messages in the thread have been read.

message_idsarray<string>

An array of IDs for all messages in the thread.

draft_idsarray<string>

An array of IDs for all drafts in the thread.

foldersarray<string>

An array of folder IDs for all folders that the messages in the thread appear in.

Microsoft messages can only be in one folder at a time. Google messages can be in multiple folders.

Example: ["8l6c4d11y1p4dm4fxj52whyr9","d9zkcr2tljpu3m4qpj7l2hbr0"]

Code examples

curl --compressed --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads/<THREAD_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "unread": true,
    "starred": false,
    "folders": ["<FOLDER_ID>"]
  }'
Sign in and select an app and grant, then add any required auth token, to auto-fill these placeholders with your real values.

Copy

View as Markdown

Install

Open in

Open in Claude Open in ChatGPT Open in Cursor