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 nameid
- The calendar IDread_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. Thenow
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
- Theid
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
- Time -
-
participants
- Participants are added as an array of participant subobjects(name
,email
,status
,comment
). Theemail
andstatus
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
- Theid
for the Emailed Events calendartitle
- 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, usenylas.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
, andmaybe
.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.