Skip to content
Skip to main content

Mark messages read, unread, or starred

Last updated:

You want a read receipt to flip when a user opens a message in your app, or a star toggle that syncs back to their real mailbox. Each provider models this differently: Gmail has stars, Outlook has flags, and IMAP has the \Flagged and \Seen keywords.

The Nylas Email API exposes one message update call. You PUT the fields you want to change, and it maps read state and stars to whatever the provider uses, so the change shows up in the user’s mail client too.

How do I mark a message read or unread?

Section titled “How do I mark a message read or unread?”

Send a PUT /v3/grants/{grant_id}/messages/{message_id} request with the unread field: false marks the message read, true marks it unread. Nylas applies the change on the user’s provider, so it syncs to their mail client across all 6 providers. You only send the fields you’re changing, so a read-state update is a 1-field body.

The request below marks a message as read and stars it in the same call.

How do I star a message?

Section titled “How do I star a message?”

Set the starred field on the same PUT /v3/grants/{grant_id}/messages/{message_id} request: true stars the message, false removes the star. Nylas maps starred to each provider’s own concept, so it becomes a Gmail star or an Outlook flag from a single field. One caveat: starring on Exchange (EWS) requires Exchange 2010 or later.

Because both unread and starred live on the same endpoint, you can change read state and star state together in 1 request rather than making two calls.

Update message state from the terminal

Section titled “Update message state from the terminal”

The Nylas CLI flips message flags by ID: nylas email mark read, unread, and starred toggle state, and nylas email move files a message into a folder or archives it. Each takes a message ID and writes straight to the provider.

# Mark a message read, then star it
nylas email mark read <message-id>
nylas email mark starred <message-id>


# Move a message into a folder
nylas email move <message-id> --folder <folder-id>

State changes sync back to the provider, so the message shows as read or starred in the user’s mail client too. The same commands work across all 6 providers. See the email mark read and email mark starred command reference.

Things to know about updating message state

Section titled “Things to know about updating message state”

A couple of details help here. The update is a partial PUT: include only the fields you want to change, and Nylas leaves everything else untouched. The same endpoint also accepts a folders array (to move or label the message, covered in its own recipe) and a metadata object, so read state, stars, folders, and metadata all go through this one call. Read state and folder changes apply across all 6 providers.

Provider mapping is the main thing to keep in mind: a “star” is Gmail-native, but on Outlook it surfaces as a flag. The behavior is equivalent, though a power user may see slightly different wording in their client.

What’s next

Section titled “What’s next”