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.
You can also bootstrap from the terminal:
brew install nylas/nylas-cli/nylas
nylas init
More options in the CLI getting-started guide.
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
Tested on Node.js 18+. Also runs on AWS Lambda, Cloudflare Workers, and Vite/edge environments โ see the examples/ directory for working setups.
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);
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:
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.
For Google and Microsoft calendars, events.batch() creates, updates, and deletes
events in one request. All operations share the query parameters. HTTP 207 returns
normally, even when every operation failed; each result corresponds to the operation
at the same index. The SDK does not split batches or retry failed operations.
import type { BatchEventOperation } from 'nylas';
const queryParams = { calendarId: 'primary' };
const operations: BatchEventOperation[] = [
{
method: 'create',
body: {
title: 'Standup',
when: { startTime: 1798794000, endTime: 1798795800 },
},
},
{ method: 'update', eventId: 'EVENT_ID_1', body: { title: 'Renamed' } },
{ method: 'delete', eventId: 'EVENT_ID_2' },
];
const result = await nylas.events.batch({
identifier: grantId,
queryParams,
requestBody: { operations },
});
const retryOperations: BatchEventOperation[] = [];
let retryDelay = 0;
for (const [index, item] of result.data.entries()) {
console.log(index, item.status, item.data?.id);
// A later step can fail after the provider created the event. Never retry it.
if (item.providerEventCreated) continue;
if (item.status === 429 || item.status === 503) {
retryOperations.push(operations[index]);
// Honor retryAfter, including zero. Choose an application backoff if absent.
retryDelay = Math.max(retryDelay, item.retryAfter ?? 1);
}
}
// Optional caller-controlled retry: one attempt, only for the selected failures.
if (retryOperations.length > 0) {
await new Promise((resolve) => setTimeout(resolve, retryDelay * 1000));
const retried = await nylas.events.batch({
identifier: grantId,
queryParams,
requestBody: { operations: retryOperations },
});
for (const [index, item] of retried.data.entries()) {
console.log('Retry result', index, item.status);
}
}
Participant notifications use the server default (true) when omitted. Microsoft
rejects notifyParticipants: false. Invalid requests raise the usual NylasApiError.
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.
See CHANGELOG.md for per-release notes. Older upgrade guidance lives in UPGRADE.md.
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.
Found a vulnerability? Please don't open a public issue. Report it through our Vulnerability Disclosure Policy.
pip install nylasgem install nylasMIT โ see LICENSE.txt.