Manage events with Node.js

This page explains how to use the Nylas Node.js SDK and Calendar API to create and manage events, including how to RSVP to them.

Before you begin

Before you start, you must have done the following tasks:

List calendars and events

To access the calendars associated with an end user's account, use the nylas.calendars object. You can access their default calendar and any custom calendars (for example, those that the end user created).

The following code sample shows how to retrieve five calendars from an end user's account.

const calendars = await nylas.calendars.list({
  identifier: '<NYLAS_GRANT_ID>',
  queryParams: {
    limit: 5
  }
})

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

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

The following example shows how to query the Nylas APIs to retrieve the next 10 events from an end user's calendar, starting at the time that you make the request.

🔍 Nylas expects time values as Unix timestamps, in seconds. Date and time functions in JavaScript return time in milliseconds. To convert it to Unix timestamp format, divide the returned value by 1,000 (/ 1000).

const now = (new Date).getTime() / 1000; // Time in Unix timestamp format (in seconds)

cons const events = await nylas.events.list({
  identifier: '<NYLAS_GRANT_ID>',
  queryParams: {
    calendarId: '<CALENDAR_ID>',
    start: now
    limit: 10
  }
});

You can fine-tune the results by setting certain parameters, like starts, to specify a time range, a maximum number of results, and any pagination settings.

For more information, see the Events reference documentation.

The example below lists the calendars associated with an end user's account, and all events from a specified calendar.

import 'dotenv/config';
import Nylas from 'nylas';

const NylasConfig = {
  apiKey: '<NYLAS_API_KEY>',
  apiUri: '<NYLAS_API_URI>',
};

const nylas = new Nylas(NylasConfig);

async function fetchAllCalendars(): Promise<void> {
  try {
    const calendars = await nylas.calendars.list({
      identifier: '<NYLAS_GRANT_ID>',
    });

    console.log('Available Calendars:', calendars);
  } catch (error) {
    console.error('Error fetching calendars:', error);
  }
}

async function fetchAllEventsFromCalendar(): Promise<void> { 
  try {
    const events = await nylas.events.list({
      identifier: '<NYLAS_GRANT_ID>',
      queryParams: {
        calendarId: '<CALENDAR_ID>',
      }
    });
  
    console.log('Events:', events);
  } catch (error) {
    console.error('Error fetching calendars:', error);
  }
}

fetchAllCalendars();
fetchAllEventsFromCalendar();

Create an event and send email notifications

The following code sample creates an event and assigns its title and location parameters.

const now = Math.floor(Date.now() / 1000) // Time in Unix timestamp format (in seconds)

async function createAnEvent() {
  try {
    const event = await nylas.events.create({
      identifier: '<NYLAS_GRANT_ID>',
      requestBody: {
        title: 'Build With Nylas',
        when: {
          startTime: now,
          endTime: now + 3600,
          participants: [{ email: 'my.friend@example.com', name: 'My Friend' }],
        }
      },
      queryParams: {
        calendarId: '<CALENDAR_ID>',
      },
    })

    console.log('Event:', event)
  } catch (error) {
    console.error('Error creating event:', error)
  }
}

createAnEvent();

Keep the following things in mind when you create events:

The when object specifies the event time in Unix timestamp format, represented in UTC. The event time can be one of the following categories:

Category	Properties	Description
Time	`time`, `timezone`	A specific point in time (for example, the start time of an event).
Timespan	`startTime`, `endTime`, `startTimezone`, `endTimezone`	A period of time with a specified beginning and end (for example, an hour-long lunch meeting).
Date	`date`	The date on which the event occurs, without a clock-based start or end time (for example, a birthday or holiday).
Datespan	`startDate`, `endDate`	A span of days without specific clock-based start and end times (for example, a business quarter or semester). For more information, see All-day event handling.

You add participants in the participants array. Each requires an email and status value. You can also include a name and comment.
The calendarId must be the ID for a calendar that the end user has Write access to. For information on retrieving calendar IDs, see List calendars and events.

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 /v3/grants/{grant_id}/events reference documentation.

After you create the event, use updateAnEvent() to save it to the end user's calendar.

async function updateAnEvent(): Promise<void> {
  try {
    const event = await nylas.events.update({
      identifier: '<NYLAS_GRANT_ID>',
      eventId: '<EVENT_ID>',
      requestBody: {},
      queryParams: {
        calendarId: '<CALENDAR_ID>',
        notifyParticipants: true,
      },
    });

    console.log('Event:', event);
  } catch (error) {
    console.error('Error creating event:', error);
  }
}

updateAnEvent();

Now, you can send email notifications to the event's participants.

All together, the code to create an event and send email notifications resembles the following example.

const now = Math.floor(Date.now() / 1000) // Time in Unix timestamp format (in seconds)

async function createAnEvent() {
  try {
    const event = await nylas.events.create({
      identifier: '<NYLAS_GRANT_ID>',
      requestBody: {
        title: 'Build With Nylas',
        when: {
          startTime: now,
          endTime: now + 3600,
          participants: [{ email: 'my.friend@example.com', name: 'My Friend' }],
        }
      },
      queryParams: {
        calendarId: '<CALENDAR_ID>',
        notifyParticipants: true
      },
    })

    console.log('Event:', event)
  } catch (error) {
    console.error('Error creating event:', error)
  }
}

createAnEvent();

RSVP to an event

The following code sample replies "Yes" to an event.

async function sendEventRSVP() {
  try {
    const event = await nylas.events.update({
      identifier: '<NYLAS_GRANT_ID>',
      eventId: '<EVENT_ID>',
      requestBody: {
        participants: [{
          name: 'Nylas DevRel',
          email: 'devrelram@example.com',
          status: 'yes',
        }]
      },
      queryParams: {
        calendarId: '<CALENDAR_ID>',
      },
    })

    console.log('Event RSVP:', event)
  } catch (error) {
    console.error('Error to RSVP participant for event:', error)
  }
}

sendEventRSVP()

For more information, see the Send RSVP reference documentation.

Explore the Calendar API

If you've made it to this point, congratulations! You've learned how to manage events with the Nylas Node.js SDK and Calendar API! 🎉

There's plenty more that you can do with Nylas. Take a look at the following resources to learn more: