nylas/nylas-nodejs

Nylas Node.js SDK

The official Node.js SDK for Nylas — the infrastructure that powers communications

📖 SDK Guide · 📚 API Reference · 🚀 Sign up · 💡 Samples · 💬 Forum

The official Node.js 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 Node.js SDK guide on developer.nylas.com.

Get started

1. Sign up for a free Nylas account and grab your API key from the Nylas Dashboard.
2. Read the Getting started guide for the core concepts (applications, grants, API keys).
3. Install the SDK and make your first request — see below.

You can also bootstrap from the terminal:

brew install nylas/nylas-cli/nylas
nylas init

More options in the CLI getting-started guide.

⚙️ Install

Requirements: Node.js v18 or later.

npm install nylas
# or
yarn add nylas

The package ships its own TypeScript types — no @types/nylas needed. It's a hybrid ESM + CommonJS package, so both import and require work.

To install from source:

git clone https://github.com/nylas/nylas-nodejs.git
cd nylas-nodejs
npm install

Runtime support

Tested on Node.js 18+. Also runs on AWS Lambda, Cloudflare Workers, and Vite/edge environments — see the examples/ directory for working setups.

⚡️ Usage

You access Nylas resources (messages, calendars, events, contacts, …) through an instance of Nylas. Initialize it with your API key — and optionally an apiUri matching your data residency.

import Nylas from "nylas";
// or: const Nylas = require("nylas").default;

const nylas = new Nylas({
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI, // e.g. https://api.us.nylas.com
  timeout: 30, // optional, in seconds
});

Once initialized, use it to make requests against a grant (an authenticated end-user account):

const calendars = await nylas.calendars.list({
  identifier: process.env.NYLAS_GRANT_ID,
});
console.log(calendars);

Error handling

The SDK throws typed errors you can catch and inspect. Every API error carries a requestId and flowId — include both when filing a support ticket so we can trace the request end-to-end.

import { NylasApiError, NylasOAuthError, NylasSdkTimeoutError } from "nylas";

try {
  await nylas.calendars.list({ identifier: grantId });
} catch (err) {
  if (err instanceof NylasApiError) {
    console.error(err.statusCode, err.type, err.message, err.requestId, err.flowId);
  } else if (err instanceof NylasSdkTimeoutError) {
    console.error("Timed out:", err.url, err.timeout);
  } else {
    throw err;
  }
}

Step-by-step walkthroughs in the SDK guide:

• Send and receive email
• Read messages and threads
• Manage events on a calendar
• Manage contacts
• Manage folders and labels
• Test webhooks locally

💡 Examples

Runnable examples live in examples/ — including agent accounts, attachments (incl. large attachments), calendars, folders, grants, messages, notetakers, and edge runtimes (AWS Lambda, Cloudflare + Vite, generic edge).

For full sample apps and product quickstarts, browse nylas-samples on GitHub — every official SDK has Email, Calendar, Contacts, Scheduler, and Webhooks quickstarts.

🤖 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

• SDK guide: developer.nylas.com/docs/v3/sdks/node
• API reference: developer.nylas.com/docs/api/v3
• TypeDoc reference: nylas-nodejs-sdk-reference.pages.dev — generated method/class docs for this SDK
• Webhooks (notifications): developer.nylas.com/docs/v3/notifications
• Auth flows: developer.nylas.com/docs/v3/auth
• Dev guide & best practices: developer.nylas.com/docs/dev-guide
• Changelog: CHANGELOG.md

✨ Upgrading

See CHANGELOG.md for per-release notes. Older upgrade guidance lives in UPGRADE.md.

💙 Contributing

Issues, ideas, and pull requests welcome — see Contributing.md. Before opening a large change, please open an issue or post in the forum so we can sanity-check the direction.

🔒 Security

Found a vulnerability? Please don't open a public issue. Report it through our Vulnerability Disclosure Policy.

🔗 Other Nylas SDKs

• nylas-python · pip install nylas
• nylas-ruby · gem install nylas
• nylas-java · Maven / Gradle (Kotlin too)

📝 License

MIT — see LICENSE.txt.