Nylas Docs

The Nylas Developer Hub

Welcome to the Nylas developer hub. You'll find comprehensive guides and documentation to help you start working with Nylas as quickly as possible, as well as support if you get stuck. Let's jump right in!

Developer Guide

Node SDK

The Node SDK Quickstart Guide

The Nylas Communications Platform allows developers to quickly build features that connect to every inbox, calendar, and contacts book in the world. The Nylas SDKs are the quickest way to integrate the Nylas Email, Calendar, and Contacts APIs into your app.

This guide will help you get started with the Nylas Node SDK.

Setup your developer account first!

Before following this guide, sign up for a Nylas developer account, and follow our guide to get your developer API keys.

Install

Before you install the SDK, sign up for a Nylas developer account, and follow our guide to get your developer API keys. You will need three values from this guide to run the code examples found here:

  • CLIENT_ID - The CLIENT ID found on the dashboard page for your Nylas App
  • CLIENT_SECRET - The CLIENT SECRET found on the dashboard page for your Nylas App
  • ACCESS_TOKEN - The Access token that is provided when you authenticate an account to your Nylas App

To run the Nylas Node SDK, you will first need to have Node and npm installed on your machine.

Then, head to the nearest command line and run the following:
npm install nylas

Alternatively, if you prefer to use Yarn, you can install the Nylas Node SDK with yarn add nylas

View Authorized Accounts

Once you have the Nylas Node SDK installed, run the following code to view the accounts that are connected to your Nylas app.

const Nylas = require('nylas');

Nylas.config({
    appId: APP_ID,
    appSecret: APP_SECRET,
  });

Nylas.accounts.list().then(accounts => {
  for (let account of accounts) {
    console.log(`ID: ${account.id}  | `, 
    `Billing State: ${account.billingState} | `,
    `Sync State: ${account.syncState}`
    );
  }
});

Read the API reference for the accounts endpoint to learn more about the information you can access for accounts. Now, you're ready to take a look at how to use the Nylas Node SDK to leverage the Nylas email, calendar, and contacts APIs.

Email API

The Nylas Email API makes it easy to integrate Gmail, Outlook, Microsoft Exchange, Office 365 and every other email service provider into your application, and it offers full Create, Read, Update, and Delete (CRUD) operations.

Messages and Threads

The Nylas Email API allows you to work with both messages and threads.

Messages are the fundamental object of the Nylas platform, and the core building block for most email applications. They contain several pieces of information, such as when a message was sent, the sender's address, to whom it was sent, and the message body. They can also contain files (attachments), calendar event invitations, and more.

Threads are first-class objects that represent a collection of messages. Messages are threaded together with a variety of heuristics to match the format of third-party accounts as close as possible.

View Email Messages and Threads

const Nylas = require('nylas');

Nylas.config({
    appId: APP_ID,
    appSecret: APP_SECRET,
  });
  
const nylas = Nylas.with(ACCESS_TOKEN);

// List the 5 most recent unread email threads
nylas.threads.list({unread: true, limit: 5}).then(threads =>{
    for (let thread of threads) {
        console.log(thread.subject);
    }
});


//Get the most recent message in expanded view, which includes header information
nylas.messages.first({in: 'inbox', view: 'expanded'}).then(message =>{
    console.log(message.subject);
    // Log the Nylas global ID for the message
    console.log(message.id);
    // Log the service provider ID of the message
    console.log(message.headers['Message-Id']);
});

View the API reference for messages and threads to learn more. You can also check out the email API quickstart guide to learn more about the functionality of the Nylas Email API.

Search Messages and Threads

The search sub-endpoint is used to run a full-text search, that is proxied to the account's provider. Results are matched with objects that have been synced, and then returned.

const Nylas = require('nylas');

Nylas.config({
    appId: CLIENT_ID,
    appSecret: CLIENT_SECRET,
  });
  
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.messages.search("from:my.friend@example.com").then(messages => {
    for (let message of messages) {
        console.log(message.subject);
    }  
});

nylas.threads.search("A really important thing").then(threads => {
    for (let thread of threads) {
        console.log(thread.subject);
    }
});

View the API reference for messages and threads to learn more. You can also check out the email API quickstart guide to learn more about the functionality of the Nylas Email API.

Send an Email

const Nylas = require('nylas');

Nylas.config({
    appId: CLIENT_ID,
    appSecret: CLIENT_SECRET,
  });
  
const nylas = Nylas.with(ACCESS_TOKEN);

const draft = nylas.drafts.build({
    subject: 'With Love, from Nylas',
    to: [{ name: 'My Nylas Friend', email: 'swag@nylas.com' }],
    body: 'This email was sent using the Nylas email API. Visit https://nylas.com for details.'
});

// Send the draft
draft.send().then(message => {
    console.log(`${message.id} was sent`);
});

View the API reference for sending to learn more. You can also check out the email API quickstart guide to learn more about the functionality of the Nylas Email API.

Calendar API

The Nylas Calendar API acts as a layer of abstraction on top of all calendar providers. The Nylas calendar API offers full Create, Read, Update, and Delete (CRUD) operations for all major calendar providers, with just a few lines of code you can add full-featured scheduling & calendar sync to your application.

Read Calendars and Events

const Nylas = require('nylas');

Nylas.config({
    appId: CLIENT_ID,
    appSecret: CLIENT_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

// Most user accounts have multiple calendars where events are stored
nylas.calendars.list().then(calendars => {
    for (let calendar of calendars) {
        // Print the name of each calendar, it's ID, and whether or not the calendar is read only
        console.log(`Name: ${calendar.name} | ID: ${calendar.id} | Read Only: ${calendar.readOnly}`);
    }
});

// Return the first 10 events after a specific point in time
nylas.events.list({starts_after: 1546290000, limit: 10 }).then(events => {
    for (let event of events) {
        // Print the event title, confirmation status, and ID.
        console.log(
            `Title: ${event.title} | `,
            `Status: ${event.status} | `,
            `ID: ${event.id}`,
        );
    }
});

Check out the API reference docs for calendars and events to learn more about the features of these endpoints. You can also take a look at the calendar API quickstart guide to learn more about the functionality of the Nylas calendar API.

Create an Event

const Nylas = require('nylas');

Nylas.config({
    appId: CLIENT_ID,
    appSecret: CLIENT_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

const event = nylas.events.build({
    title: 'New Years Party!',
    // calendarID must be the ID for a calendar the user has write access to.
    calendarId: CALENDAR_ID,
    // Event times are set via UTC timestamps
    // This example creates an event on December 31, 2018
    when: { start_time: 1546290000, end_time: 1546300800 },

    // Participants are stored as an array of participant subobjects
    participants: [{ email: 'my.friend@example.com', name: 'My Friend' }],
    location: 'My House!'
  });

// Event notification emails are not sent by default
// Enable notify_participants to send an email notification to participants
event.save({ notify_participants: true }).then(event => {
    console.log(event);
});

Check out the API reference docs for calendars and events to learn more about the features of these endpoints. You can also take a look at the calendar API quickstart guide to learn more about the functionality of the Nylas calendar API.

Contacts API

The Nylas contacts API connects address books and contact databases associated with user's email accounts directly into your application. It offers full Create, Read, Update, and Delete (CRUD) operations to perform bi-directional sync with contact data including addresses, email addresses, birthdays, job titles, and more.

Read Contact Information

const Nylas = require('nylas');

Nylas.config({
    appId: APP_ID,
    appSecret: APP_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

// Print the first and last name, email address, and the ID of the first 10 contacts returned for the user's account
nylas.contacts.list({limit: 10}).then(contacts => {
    for (const contact of contacts) {
        console.log(`Name: ${contact.givenName} ${contact.surname} | Email: ${contact.emailAddresses[0]['email']} | ID: ${contact.id}`);
    }
});

Check out the API reference docs for the contacts endpoint to learn more. You can also take a look at the contacts API quickstart guide to learn more about the functionality of the Nylas contacts API.

Create a New Contact

const Nylas = require('nylas');

Nylas.config({
    appId: APP_ID,
    appSecret: APP_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

const contact = nylas.contacts.build({
    // The contact's given name is typically their first name, 
    // you can specify a last name with 'surname'
    givenName: "My Nylas Friend",
    notes: "Make sure to keep in touch!",

    // Email address 'type' must be either 'work' or 'personal'
    emailAddresses: [{type: 'work', email: 'swag@nylas.com'}],

    // Phone number type must be one of 'business', 'organization_main', 
    // 'mobile', 'assistant', 'business_fax', 'home_fax', 'radio', 'car', 'home', or 'pager'
    // Google labels 'business' phone numbers as the contact's Work phone number
    phoneNumbers: [{type: 'random', number: '(555) 555-5555'}],

    // Web page type must be one of 'homepage', 'profile', 'work', or 'blog'
    webPages: [{type: 'homepage', url: 'nylas.com'}]
});

contact.save().then( contact => {
    console.log(contact);
});

Check out the API reference docs for the contacts endpoint to learn more. You can also take a look at the contacts API quickstart guide to learn more about the functionality of the Nylas contacts API.

Additional Resources

Here are some additional resources for when you're ready to move on.

  • Introduce yourself to the Nylas Communications Platform with our getting started guide
  • Take a look at the quickstart guides for the Nylas Email, Calendar and Contacts APIs to explore the features of the Nylas Communication Platform.
  • Setup Postman to make it easy to explore the Nylas APIs.
  • When you're ready to start integrating the Nylas Communication Platform into your app, take a look at our app integration guide.
  • Finally, you can always take a look at the API reference to learn about how the Nylas APIs work.

Node SDK


The Node SDK Quickstart Guide

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.