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

# What did you do?
Add support for three new Nylas API message features:

1. New MessageFields enum values:
   - INCLUDE_TRACKING_OPTIONS: Returns message tracking options data
   - RAW_MIME: Returns Base64url-encoded raw message content

2. New Message model properties:
- trackingOptions: TrackingOptions object with opens, thread_replies,
links, and label fields
   - rawMime: String field containing Base64url-encoded message data

3. Enhanced Messages API methods:
- Messages.find() now accepts FindMessageQueryParams to specify fields
- Added FindMessageQueryParams class with Builder pattern for
consistency

Changes include:
- Comprehensive test coverage for all new functionality
- Java and Kotlin examples demonstrating the new features
- Updated documentation and changelog
- Backwards compatibility maintained

Resolves support for include_tracking_options and raw_mime fields in
Messages API.

# License
<!-- Your PR comment must contain the following line for us to merge the
PR. -->
I confirm that this contribution is made under the terms of the MIT
license and that I have the authority necessary to make this
contribution on behalf of its copyright owner.

Author: AaronDDM

CHANGELOG.md

@@ -1,6 +1,15 @@
 # Nylas Java SDK Changelog
 
 
+## [Unreleased]
+
+### Added
+* Support for `include_tracking_options` and `raw_mime` values in `MessageFields` enum
+* Support for `tracking_options` field in `Message` model to access message tracking settings
+* Support for `raw_mime` field in `Message` model to access Base64url-encoded message data
+* Support for query parameters in `Messages.find()` method to specify fields like `include_tracking_options` and `raw_mime`
+* Added `Builder` pattern to `FindMessageQueryParams` for consistency with other query parameter classes
+
 ## [2.9.0] - Release 2025-05-27
 
 ### Added

examples/.env.example

@@ -8,4 +8,8 @@ MEETING_LINK=your_meeting_link_here
 
 # Nylas API URI - Optional (defaults to https://api.us.nylas.com)
 # Only change this if instructed by Nylas support
-NYLAS_API_URI=https://api.us.nylas.com
+NYLAS_API_URI=https://api.us.nylas.com
+
+# Grant ID - Required for message and event examples
+# You can get this from your Nylas Dashboard after connecting an account
+NYLAS_GRANT_ID=your_grant_id_here

examples/README.md

@@ -4,6 +4,24 @@ Simple examples demonstrating how to use the Nylas Java/Kotlin SDK.
 
 ## Available Examples
 
+### Messages Example
+
+The `MessagesExample` and `KotlinMessagesExample` demonstrate how to use the new message features in the Nylas Java/Kotlin SDK:
+
+- Use the new `MessageFields.INCLUDE_TRACKING_OPTIONS` and `MessageFields.RAW_MIME` enum values
+- Access tracking options (opens, thread_replies, links, label) from messages  
+- Retrieve raw MIME content for messages
+- Use the new `FindMessageQueryParams` to specify fields when finding specific messages
+- Compare different field options and their effects on returned data
+
+### Events Example
+
+The `EventsExample` demonstrates how to use the Nylas Java/Kotlin SDK to interact with the Events API:
+
+- List events from a calendar
+- Filter events by date range
+- Show event details
+
 ### Notetaker Example
 
 The `NotetakerExample` demonstrates how to use the Nylas Java/Kotlin SDK to interact with the Notetakers API:
@@ -28,20 +46,38 @@ Edit the `.env` file with your details:
 # Get your API key from the Nylas Dashboard
 NYLAS_API_KEY=your_api_key_here
 
-# Add your meeting link (Zoom, Google Meet, or Microsoft Teams)
+# Your grant ID (required for message examples)
+NYLAS_GRANT_ID=your_grant_id_here
+
+# Add your meeting link (Zoom, Google Meet, or Microsoft Teams) - for Notetaker example
 MEETING_LINK=your_meeting_link_here
 ```
 
 ### 2. Running the Examples
 
 #### Option 1: Using Gradle
 
-Run Java example:
+Run Java Messages example:
+```bash
+./gradlew :examples:run -PmainClass=com.nylas.examples.MessagesExample
+```
+
+Run Kotlin Messages example:
+```bash
+./gradlew :examples:run -PmainClass=com.nylas.examples.KotlinMessagesExampleKt
+```
+
+Run Java Events example:
+```bash
+./gradlew :examples:run -PmainClass=com.nylas.examples.EventsExample
+```
+
+Run Java Notetaker example:
 ```bash
 ./gradlew :examples:run -PmainClass=com.nylas.examples.NotetakerExample
 ```
 
-Run Kotlin example:
+Run Kotlin Notetaker example:
 ```bash
 ./gradlew :examples:run -PmainClass=com.nylas.examples.KotlinNotetakerExampleKt
 ```
@@ -53,12 +89,12 @@ List available examples:
 make list
 ```
 
-Run the Java example:
+Run the Java Notetaker example:
 ```bash
 make java
 ```
 
-Run the Kotlin example:
+Run the Kotlin Notetaker example:
 ```bash
 make kotlin-way
 ```
@@ -67,9 +103,12 @@ make kotlin-way
 
 1. Open the project in your IDE (IntelliJ IDEA, Eclipse, etc.)
 2. Set the required environment variables in your run configuration
-3. Run the main method in either:
-   - `NotetakerExample.java` (Java)
-   - `KotlinNotetakerExample.kt` (Kotlin)
+3. Run the main method in any of the example files:
+   - `MessagesExample.java` (Java - demonstrates new message features)
+   - `KotlinMessagesExample.kt` (Kotlin - demonstrates new message features)  
+   - `EventsExample.java` (Java - demonstrates events)
+   - `NotetakerExample.java` (Java - demonstrates notetakers)
+   - `KotlinNotetakerExample.kt` (Kotlin - demonstrates notetakers)
 
 ## Project Structure
 
@@ -83,12 +122,31 @@ examples/
     └── main/
         ├── java/      # Java examples
         │   └── com/nylas/examples/
-        │       └── NotetakerExample.java
+        │       ├── MessagesExample.java     # NEW: Message features demo
+        │       ├── EventsExample.java       # Events API demo
+        │       └── NotetakerExample.java    # Notetaker API demo
         └── kotlin/    # Kotlin examples
             └── com/nylas/examples/
-                └── KotlinNotetakerExample.kt
+                ├── KotlinMessagesExample.kt     # NEW: Message features demo
+                └── KotlinNotetakerExample.kt    # Notetaker API demo
 ```
 
+## Message Features Demonstrated
+
+The Messages examples showcase the following new features added to the Nylas SDK:
+
+1. **New MessageFields enum values:**
+   - `MessageFields.INCLUDE_TRACKING_OPTIONS` - Returns tracking options data
+   - `MessageFields.RAW_MIME` - Returns raw MIME message content
+
+2. **New Message model properties:**
+   - `trackingOptions` - Contains opens, thread_replies, links, and label tracking data
+   - `rawMime` - Contains Base64url-encoded raw message data
+
+3. **Enhanced Messages API methods:**
+   - `Messages.find()` now accepts `FindMessageQueryParams` to specify which fields to include
+   - Both list and find operations support the new field options
+
 ## Additional Information
 
 For more information about the Nylas API, refer to the [Nylas API documentation](https://developer.nylas.com/). 

examples/build.gradle.kts

@@ -53,7 +53,9 @@ tasks.register("listExamples") {
         println("Available examples:")
         println("- Java-Notetaker: com.nylas.examples.NotetakerExample")
         println("- Java-Events: com.nylas.examples.EventsExample")
+        println("- Java-Messages: com.nylas.examples.MessagesExample")
         println("- Kotlin-Notetaker: com.nylas.examples.KotlinNotetakerExampleKt")
+        println("- Kotlin-Messages: com.nylas.examples.KotlinMessagesExampleKt")
         println("\nRun an example with: ./gradlew :examples:run -PmainClass=<example class name>")
     }
 }