◐ Shell
clean mode source ↗

GitHub - nylas/nylas-java: Nylas Java SDK

The official Kotlin & Java SDK for Nylas — the infrastructure that powers communications. Integrate with Gmail, Microsoft, IMAP, Zoom, and 250+ email, calendar, and meeting providers in 5 minutes. Covers Email, Calendar, Contacts, Scheduler, Notetaker, and Agent Accounts.

This repository is for contributors and anyone installing the SDK from source. If you just want to use the SDK in your app, head straight to the Kotlin & Java SDK guide on developer.nylas.com.

Get started

  1. Sign up for a free Nylas account.

  2. Follow the getting started guide to create an application and provision your first API key.

  3. Bootstrap a project with the Nylas CLI:

    brew install nylas/nylas-cli/nylas
nylas init

⚙️ Install

Requirements: Java 8 or later. Kotlin 1.8 or later.

Gradle

Kotlin DSL (build.gradle.kts):

implementation("com.nylas.sdk:nylas:2.17.0")

Groovy (build.gradle):

implementation 'com.nylas.sdk:nylas:2.17.0'

Maven

<dependency>
  <groupId>com.nylas.sdk</groupId>
  <artifactId>nylas</artifactId>
  <version>2.17.0</version>
</dependency>

Build from source

git clone https://github.com/nylas/nylas-java.git
cd nylas-java
./gradlew build uberJar

This produces build/libs/nylas-java-sdk-<version>-uber.jar.

⚡️ Usage

Initialize the client with your API key:

import com.nylas.NylasClient;
import com.nylas.models.Calendar;
import com.nylas.models.ListResponse;

NylasClient nylas = new NylasClient.Builder("NYLAS_API_KEY").build();

ListResponse<Calendar> calendars = nylas.calendars().list("GRANT_ID");

For step-by-step walkthroughs, see the developer guides:

Error handling

Nylas API errors extend AbstractNylasApiError (e.g. NylasApiError, NylasOAuthError). SDK-side errors extend AbstractNylasSdkError (e.g. NylasSdkTimeoutError, NylasSdkRemoteClosedError).

import com.nylas.models.AbstractNylasApiError;
import com.nylas.models.AbstractNylasSdkError;
import com.nylas.models.NylasApiError;

try {
  nylas.calendars().list("GRANT_ID");
} catch (NylasApiError e) {
  System.err.println("API error " + e.getStatusCode() + ": " + e.getMessage());
  System.err.println("Request ID: " + e.getRequestId());
} catch (AbstractNylasSdkError e) {
  System.err.println("SDK error: " + e.getMessage());
}

Logging

The SDK uses SLF4J. The HTTP client exposes three DEBUG-level loggers:

  • com.nylas.http.Summary — one line per request/response (method, URI, status, size, duration)
  • com.nylas.http.Headers — request/response headers (Authorization redacted by default)
  • com.nylas.http.Body — request/response bodies (first 10 kB by default)

Enable them with your logging framework, e.g. log4j2:

<Logger name="com.nylas" level="DEBUG"/>

Customize redaction and body-size limits by passing your own HttpLoggingInterceptor to NylasClient.Builder.

💡 Examples

Runnable Java and Kotlin examples live in examples/ (folders, events, messages, large attachments, Notetaker). For full apps, browse Java repos in nylas-samples.

🤖 AI agents

nylas/skills drops Nylas into Claude Code, Cursor, Codex, and other agents that support the skills format:

npx skills add nylas/skills
/plugin marketplace add nylas/skills   # Claude Code

The CLI also installs an MCP server for Claude Desktop, Claude Code, Cursor, Windsurf, or VS Code:

brew install nylas/nylas-cli/nylas
nylas mcp install

Walkthrough: give AI agents email access via MCP.

📚 Reference

✨ Upgrading

See CHANGELOG.md for release notes and UPGRADE.md for migration instructions between major versions.

💙 Contributing

We welcome questions, bug reports, and pull requests. See Contributing.md for how to get involved, or ask in the Nylas forum.

🔒 Security

Found a security issue? Please follow the Nylas vulnerability disclosure policy instead of opening a public issue.

🔗 Other Nylas SDKs

📝 License

This project is licensed under the terms of the MIT license.