The official Node.js SDK for [Nylas](https://developer.nylas.com/docs/v3/) โ the infrastructure that powers communications. Integrate with Gmail, Microsoft, IMAP, Zoom, and 250+ email, calendar, and meeting providers in 5 minutes. Covers [Email](https://developer.nylas.com/docs/v3/email/), [Calendar](https://developer.nylas.com/docs/v3/calendar/), [Contacts](https://developer.nylas.com/docs/v3/email/contacts/), [Scheduler](https://developer.nylas.com/docs/v3/scheduler/), [Notetaker](https://developer.nylas.com/docs/v3/notetaker/), and [Agent Accounts](https://developer.nylas.com/docs/v3/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**](https://developer.nylas.com/docs/v3/sdks/node/) on developer.nylas.com.
## Get started
1. [Sign up for a free Nylas account](https://dashboard-v3.nylas.com/register) and grab your API key from the [Nylas Dashboard](https://dashboard-v3.nylas.com/).
2. Read the [Getting started guide](https://developer.nylas.com/docs/v3/getting-started/) 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:
```bash
brew install nylas/nylas-cli/nylas
nylas init
```
More options in the [CLI getting-started guide](https://cli.nylas.com/guides/getting-started).
## โ๏ธ Install
> **Requirements:** Node.js v18 or later.
```bash
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:
```bash
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/`](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](https://developer.nylas.com/docs/dev-guide/platform/data-residency/).
```typescript
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](https://developer.nylas.com/docs/v3/auth/) (an authenticated end-user account):
```typescript
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.
```typescript
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](https://developer.nylas.com/docs/v3/sdks/node/send-email/)
- [Read messages and threads](https://developer.nylas.com/docs/v3/sdks/node/read-messages-threads/)
- [Manage events on a calendar](https://developer.nylas.com/docs/v3/sdks/node/manage-events/)
- [Manage contacts](https://developer.nylas.com/docs/v3/sdks/node/manage-contacts/)
- [Manage folders and labels](https://developer.nylas.com/docs/v3/sdks/node/manage-folders-labels/)
- [Test webhooks locally](https://developer.nylas.com/docs/v3/sdks/node/webhook-testing/)
## ๐ก Examples
Runnable examples live in [`examples/`](examples/) โ including [agent accounts](examples/agent-accounts/), [attachments](examples/attachments/) (incl. large attachments), [calendars](examples/calendars/), [folders](examples/folders/), [grants](examples/grants/), [messages](examples/messages/), [notetakers](examples/notetakers/), and edge runtimes ([AWS Lambda](examples/aws-lambda/), [Cloudflare + Vite](examples/cloudflare-vite-calendars/), [generic edge](examples/edge-environment/)).
For full sample apps and product quickstarts, browse [**nylas-samples** on GitHub](https://github.com/orgs/nylas-samples/repositories?q=node) โ every official SDK has Email, Calendar, Contacts, Scheduler, and Webhooks quickstarts.
## ๐ค AI agents
[nylas/skills](https://github.com/nylas/skills) drops Nylas into Claude Code, Cursor, Codex, and other agents that support the skills format:
```bash
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:
```bash
brew install nylas/nylas-cli/nylas
nylas mcp install
```
Walkthrough: [give AI agents email access via MCP](https://cli.nylas.com/guides/give-ai-agents-email-access-via-mcp).
## ๐ Reference
- **SDK guide:** [developer.nylas.com/docs/v3/sdks/node](https://developer.nylas.com/docs/v3/sdks/node/)
- **API reference:** [developer.nylas.com/docs/api/v3](https://developer.nylas.com/docs/api/v3/)
- **TypeDoc reference:** [nylas-nodejs-sdk-reference.pages.dev](https://nylas-nodejs-sdk-reference.pages.dev/) โ generated method/class docs for this SDK
- **Webhooks (notifications):** [developer.nylas.com/docs/v3/notifications](https://developer.nylas.com/docs/v3/notifications/)
- **Auth flows:** [developer.nylas.com/docs/v3/auth](https://developer.nylas.com/docs/v3/auth/)
- **Dev guide & best practices:** [developer.nylas.com/docs/dev-guide](https://developer.nylas.com/docs/dev-guide/)
- **Changelog:** [CHANGELOG.md](CHANGELOG.md)
## โจ Upgrading
See [`CHANGELOG.md`](CHANGELOG.md) for per-release notes. Older upgrade guidance lives in [`UPGRADE.md`](UPGRADE.md).
## ๐ Contributing
Issues, ideas, and pull requests welcome โ see [Contributing.md](Contributing.md). Before opening a large change, please open an issue or post in the [forum](https://forums.nylas.com) 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](https://www.nylas.com/security/vulnerability-disclosure-policy/).
## ๐ Other Nylas SDKs
- [nylas-python](https://github.com/nylas/nylas-python) ยท `pip install nylas`
- [nylas-ruby](https://github.com/nylas/nylas-ruby) ยท `gem install nylas`
- [nylas-java](https://github.com/nylas/nylas-java) ยท Maven / Gradle (Kotlin too)
## ๐ License
MIT โ see [LICENSE.txt](LICENSE.txt).
