feat(messages): add support for tracking_options, raw_mime fields and new MessageFields enum values (#645)

* Added support for new message `fields` query parameter values: `include_tracking_options` and `raw_mime`

* Added support for `rawMime` property in Message responses when using `fields=raw_mime`

* feat: add message cleaning and scheduled messages examples

* Ran prettier

* Clean up

Author: AaronDDM

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Support for new message `fields` query parameter values: `include_tracking_options` and `raw_mime`
+- Support for `trackingOptions` property in Message responses when using `fields=include_tracking_options`
+- Support for `rawMime` property in Message responses when using `fields=raw_mime`
+- `MessageTrackingOptions` interface for tracking message opens, thread replies, link clicks, and custom labels
+
 ## [7.10.0] - 2025-05-27
 
 ### Added

examples/.env.example

@@ -11,4 +11,7 @@ MEETING_LINK=your_meeting_link_here
 NYLAS_GRANT_ID=your_grant_id_here
 
 # Calendar ID (required for event creation/updates)
-NYLAS_CALENDAR_ID=your_calendar_id_here
+NYLAS_CALENDAR_ID=your_calendar_id_here
+
+# For testing message sending (optional)
+TEST_EMAIL=your-test-email@example.com

examples/README.md

@@ -5,6 +5,7 @@ This directory contains examples of how to use the Nylas Node.js SDK to interact
 ## Examples
 
 - [Notetakers](./notetakers/README.md) - Examples of how to use the Nylas Notetakers API to invite a Notetaker bot to meetings, get recordings and transcripts, and more.
+- [Messages](./messages/README.md) - Examples of how to use the Nylas Messages API to list, find, send, update messages, and work with new features like tracking options and raw MIME data.
 
 ## Running the Examples
 
@@ -31,10 +32,19 @@ To run these examples, you'll need to:
    ```bash
    # Using ts-node
    npx ts-node notetakers/notetaker.ts
+   npx ts-node calendars/event_with_notetaker.ts
+   npx ts-node messages/messages.ts
+   
+   # Or using npm scripts
+   npm run notetakers
+   npm run calendars
+   npm run messages
 
    # Or if you compiled the examples
    npm run build
    node dist/notetakers/notetaker.js
+   node dist/calendars/event_with_notetaker.js
+   node dist/messages/messages.js
    ```
 
 ## Documentation

examples/messages/ENVIRONMENT.md

@@ -0,0 +1,45 @@
+# Environment Setup for Messages Example
+
+## Required Environment Variables
+
+Create a `.env` file in the `examples` directory with the following variables:
+
+```bash
+# Required
+NYLAS_API_KEY=your_api_key_here
+NYLAS_GRANT_ID=your_grant_id_here
+
+# Optional
+NYLAS_API_URI=https://api.us.nylas.com
+
+# For testing message sending (optional)
+TEST_EMAIL=your-test-email@example.com
+```
+
+## Getting Your API Key and Grant ID
+
+1. **API Key**: Get your API key from the [Nylas Dashboard](https://dashboard.nylas.com)
+2. **Grant ID**: After connecting an email account, you'll get a grant ID that represents that connection
+
+## Testing Message Sending
+
+If you want to test the message sending functionality, set the `TEST_EMAIL` environment variable to an email address you control. The example will skip message sending if this variable is not set.
+
+## Running the Example
+
+Once your environment variables are set:
+
+```bash
+cd examples
+npm install
+npm run messages
+```
+
+## What the Example Demonstrates
+
+- **Message Fields**: Different ways to query messages with various field options
+- **Tracking Options**: How tracking data appears in message responses
+- **Raw MIME**: Getting raw MIME data for messages
+- **Message Operations**: Listing, finding, updating, and sending messages
+- **Scheduled Messages**: Working with scheduled message functionality
+- **Message Cleaning**: Using the clean messages API 

examples/messages/README.md

@@ -0,0 +1,59 @@
+# Messages Examples
+
+This directory contains examples of how to use the Nylas Messages API to list, find, send, and work with messages.
+
+## Features Demonstrated
+
+This example demonstrates:
+
+- **Message Operations**: List, find, send, update, and delete messages
+- **Message Fields**: Using different `fields` query parameters to get different data:
+  - `standard` - Standard message payload
+  - `include_headers` - Message with custom headers
+  - `include_tracking_options` - Message with tracking settings
+  - `raw_mime` - Raw MIME data (Base64url-encoded)
+- **Message Tracking**: Working with tracking options for opens, thread replies, and link clicks
+- **Scheduled Messages**: Creating, listing, and managing scheduled messages
+- **Message Cleaning**: Using the clean messages API to process message content
+- **Error Handling**: Proper error handling with NylasApiError
+
+## Prerequisites
+
+Before running this example, make sure you have:
+
+1. A Nylas application with an API key
+2. A connected email account (grant)
+3. The required environment variables set up
+
+## Environment Variables
+
+Create a `.env` file in the parent `examples` directory with:
+
+```bash
+# Required
+NYLAS_API_KEY=your_api_key_here
+NYLAS_GRANT_ID=your_grant_id_here
+
+# Optional
+NYLAS_API_URI=https://api.us.nylas.com
+```
+
+## Running the Example
+
+```bash
+cd examples
+npm install
+npx ts-node messages/messages.ts
+```
+
+## Example Output
+
+The example will demonstrate:
+1. Listing messages with different field options
+2. Finding specific messages with tracking data
+3. Sending messages with tracking enabled
+4. Working with raw MIME data
+5. Managing scheduled messages
+6. Cleaning message content
+
+Each operation includes detailed console output showing the API responses and data structures.