examples

Nylas Java/Kotlin SDK Examples

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:

• Invite a Notetaker to a meeting
• List all Notetakers
• Get media from a Notetaker (if available)
• Leave a Notetaker session

Folders Example

The FoldersExample and KotlinFoldersExample demonstrate how to use the Nylas Java/Kotlin SDK to interact with the Folders API:

• List all folders with default multi-level hierarchy
• Use the new single_level parameter (Microsoft only) to retrieve folders from a single-level hierarchy
• Demonstrate the builder pattern with various query parameters
• Show folder details including parent relationships and unread counts

Large Attachments Example

The LargeAttachmentsExample demonstrates how to send emails with large file attachments using the Nylas Java SDK:

• Create and send emails with 3MB and 10MB test files
• Demonstrate the SDK's automatic handling of large attachments (switches to multipart form data for files ≥ 3MB)
• Send multiple large attachments in a single email
• Compare small vs large attachment handling mechanisms
• Use the FileUtils.attachFileRequestBuilder() helper method for easy file attachment
• Automatic cleanup of temporary test files

Custom Tracking Hostname Example

CustomTrackingDomainExample demonstrates the optional TrackingOptions.domainName field for:

• regular grant-based sends;
• draft creation;
• scheduled grant-based sends; and
• Transactional Send.

The hostname must be active and owned by the authenticated organization. Enable link tracking, open tracking, or both when setting it. Omit domainName to keep using the default Nylas tracking hostname.

For Transactional Send, the values are intentionally distinct: NYLAS_TRANSACTIONAL_SENDER_DOMAIN is the verified sender domain used in /v3/domains/{domain_name}/messages/send, while NYLAS_TRACKING_HOSTNAME becomes tracking_options.domain_name in the request body.

Setup

1. Environment Setup

Copy the .env.example file to .env and fill in your credentials:

cp .env.example .env

Edit the .env file with your details:

# Get your API key from the Nylas Dashboard
NYLAS_API_KEY=your_api_key_here

# Your grant ID (required for message examples)
NYLAS_GRANT_ID=your_grant_id_here

# Test email address (required for large attachments example)
NYLAS_TEST_EMAIL=test@example.com

# An active custom hostname owned by your organization (custom tracking example)
RECIPIENT_EMAIL=recipient@example.com
NYLAS_TRACKING_HOSTNAME=tracking.example.com

# 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 Messages example:

./gradlew :examples:run -PmainClass=com.nylas.examples.MessagesExample

Run Kotlin Messages example:

./gradlew :examples:run -PmainClass=com.nylas.examples.KotlinMessagesExampleKt

Run Java Events example:

./gradlew :examples:run -PmainClass=com.nylas.examples.EventsExample

Run Java Notetaker example:

./gradlew :examples:run -PmainClass=com.nylas.examples.NotetakerExample

Run Kotlin Notetaker example:

./gradlew :examples:run -PmainClass=com.nylas.examples.KotlinNotetakerExampleKt

Run Java Folders example:

./gradlew :examples:run -PmainClass=com.nylas.examples.FoldersExample

Run Kotlin Folders example:

./gradlew :examples:run -PmainClass=com.nylas.examples.KotlinFoldersExampleKt

Run Java Large Attachments example:

./gradlew :examples:run -PmainClass=com.nylas.examples.LargeAttachmentsExample

Run the custom tracking hostname example (defaults to a regular send):

NYLAS_CUSTOM_TRACKING_OPERATION=regular \
  ./gradlew :examples:run -PmainClass=com.nylas.examples.CustomTrackingDomainExample

Choose draft, scheduled, or transactional for the other operations. Scheduled sends also require NYLAS_SEND_AT as a Unix timestamp. Transactional Send requires NYLAS_TRANSACTIONAL_SENDER_DOMAIN and SENDER_EMAIL; the non-transactional operations require NYLAS_GRANT_ID.

Option 2: Using the Makefile

List available examples:

make list

Run the Java Notetaker example:

make java

Run the Kotlin Notetaker example:

make kotlin-way

Option 3: From an IDE

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 any of the example files:
   • MessagesExample.java (Java - demonstrates new message features)
   • KotlinMessagesExample.kt (Kotlin - demonstrates new message features)
   • EventsExample.java (Java - demonstrates events)
   • FoldersExample.java (Java - demonstrates folders and single_level parameter)
   • LargeAttachmentsExample.java (Java - demonstrates large file attachments)
   • CustomTrackingDomainExample.java (Java - demonstrates custom link and open tracking hostnames)
   • NotetakerExample.java (Java - demonstrates notetakers)
   • KotlinNotetakerExample.kt (Kotlin - demonstrates notetakers)
   • KotlinFoldersExample.kt (Kotlin - demonstrates folders and single_level parameter)

Project Structure

examples/
├── .env.example       # Template for environment variables
├── build.gradle.kts   # Gradle build file for examples
├── Makefile           # Helpful commands for running examples
├── README.md          # This file
└── src/
    └── main/
        ├── java/      # Java examples
        │   └── com/nylas/examples/
        │       ├── MessagesExample.java         # NEW: Message features demo
        │       ├── EventsExample.java           # Events API demo
        │       ├── FoldersExample.java          # NEW: Folders API demo with single_level parameter
        │       ├── LargeAttachmentsExample.java # NEW: Large file attachments demo
        │       └── NotetakerExample.java        # Notetaker API demo
        └── kotlin/    # Kotlin examples
            └── com/nylas/examples/
                ├── KotlinMessagesExample.kt     # NEW: Message features demo
                ├── KotlinFoldersExample.kt      # NEW: Folders API demo with single_level parameter
                └── 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.