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.
curl --request PUT \ --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>' \ --header 'Authorization: Bearer <NYLAS_API_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "unread": false, "starred": true }'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.
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”- Organize email with folders and labels to move messages between folders
- List Google email messages to fetch the messages you update
- Track email opens and replies to react to engagement automatically
- Get real-time updates with webhooks for message.updated notifications