Manage events with the Nylas Node.js SDK

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

You'll use the Nylas Node.js SDK and Calendar API to manage your events.

What you'll learn

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

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

Prerequisites

Prerequisites include installing the Nylas Node.js SDK and setting up your environment. Before you start this tutorial, make sure that you do the following:

Complete the Getting started with the Nylas Node.js SDK tutorial.
Authenticate users with the Nylas Node.js SDK.

Step 1: Initialize the Nylas object

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

The Nylas object provides access to every resource in Nylas APIs. Before making any request, you must initialize the Nylas object with your client ID, client secret, and access token.

Call the config function and pass your client ID (<CLIENT_ID>) and client secret (<CLIENT_SECRET>).
Call the with function and pass your access token (<ACCESS_TOKEN>).

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

Step 2: Change the base API URL

You can optionally 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.

To change the base URL to the EU (Ireland) region, set apiServer: regionConfig[Region.Ireland].nylasAPIUrl. The base API URL defaults to the US region.

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

Step 3: Read calendars and events

Learn how to read calendars and events.

Read calendars

Use the nylas.calendar object to access calendars associated with an account. Available calendars include the account’s default calendar and other custom calendars, such as calendars that the user created or the user’s shared team calendars.

Call the .list() function to return all calendars.
Optionally, specify attributes for the calendar object.

The following example returns all calenders and logs name, id, and read_only attributes for each calendar:

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 name
id - The calendar ID
read_only - A true/false Boolean that specifies whether the user has write access to the calendar

Learn more about the Calendar endpoint.

Read events

Use the nylas.events object to access events that are found for a user’s account.

Call the .list() function to return all events.
Optionally, do the following:
- Filter the results. Learn more about filters.
- Specify attributes for the event object.

The following example returns the next ten events on the user’s calendar after the current time (now) and logs title, status and id attributes for each event:

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}`,
        );
    }
});

starts_after - Selects events that occur after the specified time. The now variable represents the current time in Unix epoch time format.
limit - Limits the number of events that are returned. For more information on using limits and offsets to paginate results, refer to Pagination.
calendar_id - The id for the user’s calendar

Learn more about the Events endpoint.

Example: Read calendars and events

The following example reads calendars and events from a user 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

Learn how to create events and send email notifications.

Create events

Create a new event and assign event attributes. For more information on available attributes, refer to POST /events.

The following example creates a new event object and assigns 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
  });

when - Event times are in UTC time format and can be one of the following event subobjects:
- Time - time, timezone
- Timespan - startTime, endTime, startTimezone, endTimezone
- Date - date
- Datespan - startDate, endDate
participants - Participants are added as an array of participant subobjects(name, email, status, comment). The email and status fields are required.
calendarId - CALENDAR_ID must be the ID for the calendar that the user has write access to. For information on how to retrieve calendar IDs, refer to Read calendars.

Send email notifications

Save the event to the calendar and send email notifications.

Call the save() function and set notify_participants: true.

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 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 events

Use the .first() function to retrieve events from the Emailed Events calendar, and use the event.rsvp() function to RSVP to the events. The Emailed Events calendar contains all events that the user has received notifications through email.

For more information on sending RSVPs, refer to POST /send-rsvp.

Call the .first() function to return the event and set filters.

For example, set the following filters:
- calendar_id - The id for the Emailed Events calendar
- title - The title of the event
```
nylas.events.first({calendar_id: EMAILED_CALENDAR_ID, title: "Birthday Party!"})   
```
If you know the id of the specific event that you want to respond to, use nylas.events.find({EVENT_ID}).

Learn more about filters.

Call the event.rsvp() function to set the response value and message.

Supported response values are yes, no, and maybe.

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 events

The following example 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 integrated your first calendar with the Nylas Calendar API. There's plenty more that you can do with Nylas. Take a look at the following resources:

Follow our Node.js SDK tutorials.
Learn more about the Nylas API.
Learn more about the Nylas Calendar API.
Learn more about how the Nylas Communications Platform works.
Read the blog post How to manage calendar events with the Nylas Node.js SDK.