Skip to content
Docs
or

Using the Events API

The Nylas Events API gives your application a secure, reliable connection to the events on your end users’ calendars. It provides a REST interface that lets you create, update, and delete events.

How the Events API works

Every end user who authenticates with your Nylas application can have zero, one, or multiple calendars, all of which serve as containers for Event objects.

Event objects are containers for information about scheduled events. This includes a list of the people involved, details about the time, meeting location (in-person address or virtual conferencing details), and a description. They can also include .ics files and other attachments, and information about who has confirmed their attendance.

In most cases, you make requests to the Availability endpoints (Get Availability or Get Free/Busy Schedule) before you make requests to the Event endpoints, to ensure the time for an event you want to book is available.

Conferencing details

The Nylas Events API includes both the ability to read conferencing details from an event, and create conferences as you create events. See Manually add conferencing to an event for more information.

Before you begin

To follow along with the samples on this page, you first need to sign up for a Nylas developer account, which gets you a free Nylas application and API key.

For a guided introduction, you can follow the Getting started guide to set up a Nylas account and Sandbox application. When you have those, you can connect an account from a calendar provider (such as Google, Microsoft, or iCloud) and use your API key with the sample API calls on this page to access that account’s data.

Get a list of events

To return a list of events from an end user’s calendar, make a Get all Events request that includes the specific calendar ID.

By default, Nylas returns a list of 100 Event objects. The results are sorted by the start date and time, beginning with the oldest event.

If you know the ID for a specific event, you can make a Get Event request to fetch it instead.

You can also get a list of events using the Nylas SDKs, as in the following examples.

Filter a list of events

You can add query parameters to a GET request to filter the events that Nylas returns. For example, you can filter to return only events from a single calendar. The following code snippet uses several query parameters to filter events.

For information about the parameters you can use in queries to the Get Events endpoint, see the Events reference.

You can also filter results using the Nylas SDKs, as in the example below.

All-day event handling

When Nylas returns an all-day event (datespan) from Google and Microsoft calendars, the end date is set to the day after the event ends. This is due to how Google and Microsoft handle all-day events. To display the correct number of days for all-day events, make sure that you subtract a day.

For example, an event scheduled for December 1st will have an end date of December 2nd.

Create an event

The code samples below show how to create an event — in this case, a New Year’s Eve party in a specific room at the Ritz Carlton.

Nylas’ response includes an id for the new event.

Modify an event and send an email invitation

You can now modify the event from the previous step to add a participant for the New Year’s Eve party and send an invitation.

For more information about the parameters you can modify, see the Events references.

Notify participants

The query string parameter notify_participants=true sends an email invitation to all email addresses listed in the participants sub-object. The query string parameter defaults to true.

Delete an event

If an event is cancelled, you can delete it and send an email notification to all participants.

RSVP to an event

To make event planning even easier, the Nylas Event API lets you send an RSVP response to an event’s organizer.

The Send RSVP endpoint lets you send a response to a specified event’s organizer with an RSVP status (yes, no, or maybe). This lets the organizer know whether you plan to come, and updates the event with your RSVP status.

Nylas sends event RSVPs as email updates. If your application does not include the email send API scopes, Nylas updates the RSVP for the event and returns a 200 error message. If this happens, event participants on the same provider will see the RSVP update, but participants on other providers will not.

Get available room resources

You can use the GET /v3/grants/<GRANT_ID>/resources endpoint to get a list of resources such as conference rooms or other equipment that the end user can book.

Nylas returns only items that the end user’s grant has access to. You cannot book a resource on behalf of an end user if they don’t have access to that resource.

At minimum, each resource has an email address and a calendar. You can add a resource to an event by including its email address in an event invitation, and you can use the calendar ID to get the resource’s availability.

Limited attendance events

Limited attendance events allow an organizer to set specific times when they’re available to meet with a group, and limit the number of people who can attend. This is useful for events such as online classes or seminars.

The event owner creates and schedules the event, and sets a maximum number of attendees. They then make the event available to book, provide a way for attendees to select it, and send potential attendees an invitation to choose a time. Attendees can choose to sign up if one of the set times works for them.

When an attendee books an event, Nylas checks that the event hasn’t met its capacity limit yet, creates an event on the attendee’s calendar, and increments the capacity counter for the event.

Enable attendance limits

To limit the number of attendees for an event, pass the capacity value in your Create Event request. The capacity field defaults to -1, meaning the event is open to an unlimited number of attendees. Set it to the desired number of attendees (not counting the event owner) to create a limited attendance event.

{
  "title": "Philosophy Club Lecture series",
  "busy": true,
  "capacity": 5,
  "organizer": {
      "name": "Aristotle",
      "email": "[email protected]"
    },
  "participants": [{
    "name": "Jane Stephens",
    "email": "[email protected]"
  }],
  "hide_participants": true,
  "description": "Come ready to talk philosophy!",
  "when": {
      "start_time": 1674604800,
      "end_time": 1722382420,
      "start_timezone": "America/New_York",
      "end_timezone": "America/New_York"
  },
  "location": "New York Public Library, Cave room",
}'

If the participant count for a limited attendance event exceeds the capacity when an attendee tries to book the event, Nylas returns a 400 error response with the updated message.