Only show these results:

Manage events with the Nylas Node.js SDK

The Nylas Node.js SDK is the quickest way to integrate calendars into your app using JavaScript and the Nylas Calendar API. The Calendar API connects to all major providers including Google, Exchange, iCal, and Outlook.

This page discusses how to use the Nylas Node.js SDK and Calendar API to create and manage events.

What you'll learn

In this tutorial, you'll learn how to do the following tasks:

  • Read calendars and events.
  • Create Events and send email notifications to participants.
  • RSVP to events.

Prerequisites

Before you start, install the Nylas Node.js SDK and set up your environment:

Step 1: Initialize the Nylas object

At its core, the Nylas platform is an API client that interfaces with all major calendar and event service providers.

The Nylas object provides access to every resource in the Nylas API. Before you make any API requests, you must initialize the Nylas object with your client ID, client secret, and access token:

  1. Call the .config() function and pass your <CLIENT_ID> and <CLIENT_SECRET>.
  2. Call the .with() function and pass your <ACCESS_TOKEN>.

All together, your code should look like the example below.

const Nylas = require('nylas');
 
Nylas.config({
 clientId: <CLIENT_ID>,
 clientSecret: <CLIENT_SECRET>
});
 
const nylas = Nylas.with(<ACCESS_TOKEN>);

Step 2: (Optional) Change the base API URL

You can choose to change the base API URL depending on your location:

Location API URL Scheduler API URL
United States (Oregon) https://api.nylas.com https://api.schedule.nylas.com
Europe (Ireland) https://ireland.api.nylas.com https://ireland.api.schedule.nylas.com

For more information, see Data residency and Migration guide for data centers.

If you're using the Node.js SDK v6.x and the Nylas API v3 Beta: The EU region is currently not available.

To change the API URL, pass the API_URL parameter to Nylas.config():

const Nylas = require('nylas');
 
Nylas.config({
 clientId: <CLIENT_ID>,
 clientSecret: <CLIENT_SECRET>,
 apiServer: regionConfig[Region.Ireland].nylasAPIUrl
});
 
const nylas = Nylas.with(<ACCESS_TOKEN>);

If you're using the Nylas EU region: The base API URL defaults to the US region, but you can specify apiServer: regionConfig[Region.Ireland].nylasAPIUrl to use the EU region. See Data Residency for more information.

Step 3: Read calendars and events

You can use the Nylas object to read calendars and events from a user's account.

Read calendars

To access the calendars associated with an end user's account, use the nylas.calendars object. You can access the account's default calendar and its custom calendars, such as those that the user created and their shared team calendars:

  1. Call the .list() function to return all calendars associated with the user's account.

  2. (Optional) Specify attributes for the Calendar object. For example, this code logs each calendar's name, id, and read_only attributes:

    nylas.calendars.list().then(calendars => {
        for (const calendar of calendars) {
            console.log(`Name: ${calendar.name} | ID: ${calendar.id} | Read Only: ${calendar.readOnly}`);
        }
    });
    • name: The calendar's name.
    • id: The calendar's ID.
    • read_only: A Boolean that specifies whether the user has Write access to the calendar.

For more information about calendars and their parameters, see the Calendar endpoint documentation.

Read events

To access the events associated with a user's account, use the nylas.events object.

These steps read the next ten events that occur on the user's calendar after the current time (now). Each Event that's returned will include its title, status, and id attributes:

  1. Call the .list() function to return all events associated with the user's account.

  2. (Optional) Filter the results (for example, include only events that occur after a certain time by setting the starts_after parameter).

    • starts_after: Select events that occur after the specified time only. The now variable represents the current time in Unix epoch format.
    • limit: Limit the number of events that are returned. For more information on using limits and offsets to paginate results, see the Pagination documentation.
    • calendar_id: The id of the user’s calendar.

  3. (Optional) Set attributes for the Event object.

When put together, the code looks like the example below.

const now = (new Date).getTime()/1000;
nylas.events.list({starts_after: now, limit: 10 , calendar_id: CALENDAR_ID}).then(events => {
    for (const event of events) {
        console.log(
            `Title: ${event.title} | `,
            `Status: ${event.status} | `,
            `ID: ${event.id}`,
        );
    }
});

For more information about events, see the Events endpoint documentation.

Example: Read calendars and events

The following example reads calendars and events from an end user's account.

const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

// Most user accounts have multiple calendars where events are stored.
nylas.calendars.list().then(calendars => {
    for (const 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}`);
    }
});
// The Nylas API keeps track of time with Unix Epoch seconds timestamps.
const now = (new Date().getTime())/1000;
// Return the the next 10 events after the current time.
// CALENDAR_ID should be replaced with the ID for a specific calendar.
nylas.events.list({starts_after: now, limit: 10 , calendar_id: CALENDAR_ID}).then(events => {
    for (const event of events) {
        // Print the event title, confirmation status, and ID.
        console.log(
            `Title: ${event.title} | `,
            `Status: ${event.status} | `,
            `ID: ${event.id}`,
        );
    }
});

Step 4: Create events and send email notifications

When you create an event, you can set variables that change its attributes, such as its title and location. For more information on available attributes, see the POST /events documentation.

The example below creates a new Event object and assigns its title and location.

const { default: Event } = require('nylas/lib/models/event');

const event = new Event(nylas, {
    title: 'New Years Party!',
    location: 'My House!',
    when: { startTime: 1546290000, endTime: 1546300800 },
    participants: [{ email: '[email protected]', name: 'My Friend' }],
    calendarId: CALENDAR_ID
  });

  • Event times are represented by the when parameter. They're listed in UTC time format and can be one of these event subobjects:

    • Time: time, timezone
    • Timespan: startTime, endTime, startTimezone, endTimezone
    • Date: date
    • Datespan: startDate, endDate

  • Participants are added as an array of participant subobjects. Each participant object requires an email and status value. The other values (name and comment) are optional.

  • The calendarId must be the ID for a calendar that the user has Write access to. For information on how to retrieve calendar IDs, see Read calendars.

After you create an event, use the .save() function to save it to the user's calendar as in the following code snippet. You can then set email notifications to be sent to participants.

event.save({ notify_participants: true }).then(event => {
    console.log(event);
});

Example: Create events and send email notifications

The following example creates an Event and sends email notifications to its participants.

const Nylas = require('nylas');
const { default: Event } = require('nylas/lib/models/event');

Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

const event = new Event(nylas, {
    title: 'New Years Party!',
    // Event times are set via UTC timestamps.
    // This example creates an event on December 31, 2018.
    when: { startTime: 1546290000, endTime: 1546300800 },
    // Participants are stored as an array of participant subobjects
    participants: [{ email: '[email protected]', name: 'My Friend' }],
    location: 'My House!',
    // calendarID must be the ID for a calendar the user has Write access to.
    calendarId: CALENDAR_ID
  });

// 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);
});

Step 5: RSVP to an event

To RSVP to events, first retrieve a list of events from the Emailed Events calendar. This calendar contains all events that the user has received invitations to via email messages. Note that the RSVP feature works for events listed in the Emailed Events calendar only.

The steps below retrieve and RSVP to an Event from the Emailed Events calendar. For more information about sending RSVPs, see the POST /send-rsvp documentation.

  1. Use the .first() function to retrieve events from the Emailed Events calendar, and to set filters for the returned events:

    nylas.events.first({calendar_id: EMAILED_CALENDAR_ID, title: "Birthday Party!"})
    • calendar_id: The ID for the Emailed Events calendar.
    • title: The title of the Event.

  2. Use the event.rsvp() function to set the RSVP response value (yes, no, or maybe) and message.

    nylas.events.first({calendar_id: EMAILED_CALENDAR_ID, title: "Birthday Party!"}).then(event => {
        event.rsvp('yes', 'I can\'t wait to see the birthday girl!')
    })

Example: RSVP to an event

The example below retrieves the Birthday Party event from the Emailed Events calendar and responds "Yes" to the event.

const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

// CALENDAR_ID should be the ID for the Emailed Events calendar.
nylas.events.first({calendar_id: EMAILED_CALENDAR_ID, title: "Birthday Party!"}).then(event => {
    event.rsvp('yes', 'I can\'t wait to see the birthday girl!')
})

More resources

If you’ve made it this far, congrats! You’ve learned how to manage events with the Nylas Calendar API. 🎉

There's plenty more that you can do with Nylas. Take a look at these resources: