Version:
Only show these results:

Using the v2 Events API

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

In many cases, you make requests to the Availability endpoints before you make requests to the Event endpoints, to make sure the time for an event you want to book is available.

This page discusses how to create, update, and delete Event objects. See Using the Calendar API for information about creating and modifying the calendar that contains an event.

Before you begin

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

Get a list of events

To return a list of events from all of a user's calendars, make a GET /events request or use the Nylas SDKs to get a list of events on an end user's calendars. By default, Nylas returns a list of 100 Event objects. The results are sorted by the start date and time, beginning with the oldest.

If you know the ID for a specific event that you're interested in, you can make a Get Event request to get a single event instead.

curl -X GET https://api.nylas.com/events   
[{
  "account_id": "iy7wkz66wrbeccc6nisy",
  "busy": true,
  "calendar_id": "412pwfsq3k7uklj1zkq5",
  "description": "This is a super important meeting",
  "id": "c7n5vl6dhbdeqwjaxk29",
  "location": null,
  "message_id": null,
  "object": "event",
  "owner": "Jane Doe <jane.doe@example.com>",
  "participants": [
    {
      "comment": null,
      "email": "you@example.com",
      "name": null,
      "status": "yes"
    },
    {
      "comment": null,
      "email": "someone@example.com",
      "name": null,
      "status": "maybe"
    }
  ],
  "read_only": true,
  "status": "confirmed",
  "title": "Meet with Nylas",
  "when": {
    "end_time": 1478568600,
    "object": "timespan",
    "start_time": 1478565000
  }
}]   
from nylas import APIClient

nylas = APIClient(
  APP_ID,
  APP_SECRET,
  ACCESS_TOKEN
)

print(nylas.events.all())   
const Nylas = require('nylas');

Nylas.config({
  clientId: NYLAS_CLIENT_ID,
  clientSecret: NYLAS_CLIENT_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

nylas.events.list().then(events => console.log(events));   
import java.io.IOException;
import com.nylas.RequestFailedException;
import com.nylas.NylasAccount;
import com.nylas.NylasClient;
import com.nylas.Event;
import com.nylas.Events;

public class NylasExamples {
  public static void getEventsExample() throws IOException, RequestFailedException {
    NylasClient nylas = new NylasClient();
    NylasAccount account = nylas.account("{ACCESS_TOKEN}");
    Events events = account.events();

    events.list();

    for (Event event : events_list) {
      System.out.println(event);
    }
  }
}

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. For information about the parameters you can use in queries to the Get Events endpoint, see the Events API documentation.

To filter the events that Nylas returns for a GET /events request, include a query parameter in the request. The following example uses the ?calendar_id query parameter to filter for events that are on a specific calendar.

curl -X GET https://api.nylas.com/events?calendar_id=<CALENDAR_ID>

You can also filter the list of events using the Nylas SDKs.

const Nylas = require('nylas');

Nylas.config({
  clientId: NYLAS_CLIENT_ID,
  clientSecret: NYLAS_CLIENT_SECRET
});

const nylas = Nylas.with(ACCESS_TOKEN);

nylas.events.list({calendar_id: '{id}'}).then(events => console.log(events));   
from nylas import APIClient

nylas = APIClient(
    APP_ID,
    APP_SECRET,
    ACCESS_TOKEN
)

print(nylas.events.where(calendar_id='{id}'))

Create an event

This section describes how to create an event — in this case, a New Year's Eve party at the Ritz Carlton. The following examples use the Nylas API to create an event on December 31, 2019 at 10:00p.m. UTC and include a room resource.

curl -X POST \
  https://api.nylas.com/events \
  -d '{
    "title": "Party at the Ritz!",
    "when": {
      "start_time": 1577829600,
      "end_time": 1577844000
    },
    "calendar_id": "<CALENDAR_ID>",
    "location": "Ritz Ballroom",
    "participants": [{
      "email": "ballroom@example.com"
    }]
}'

Nylas' response includes an id for the new event.

Modify an event and send an email invite

Next, you can modify the event from the previous step to add a participant for the New Year's Eve party. The following examples use the Nylas API to add a participant to the event and send an email invite.

⛔️ You're about to send a real event invite! The following commands send an email from the account you connected to the Nylas API to any email addresses you put in the participants sub-object. Make sure you actually want to send this invite to those addresses before running this command!

curl -X PUT \
  https://<ACCESS_TOKEN>:@api.nylas.com/events/<EVENT_ID>?notify_participants=true \
  -d '{
    "where": "The Ritz Carlton",
    "participants": [{
      "comment": "null",
      "email": "my.friend@example.com",
      "name": "My Friend",
      "status": "noreply"
    }],
    "description": "We will ring in 2020 at the Ritz!"
}'

You can do the same using the Nylas SDKs, as in the following examples.

from nylas import APIClient

nylas = APIClient(
    NYLAS_CLIENT_ID,
    NYLAS_CLIENT_SECRET,
    ACCESS_TOKEN
)

event = nylas.events.get('<EVENT_ID>')
event.location = "The Ritz Carlton"
event.participants = [{"name": "My Friend", 'email': 'my.friend@example.com'}]

event.save(notify_participants='true')   
const Nylas = require('nylas');

Nylas.config({
  clientId: NYLAS_CLIENT_ID,
  clientSecret: NYLAS_CLIENT_SECRET
});

const nylas = Nylas.with(ACCESS_TOKEN);

nylas.events.find('<EVENT_ID>').then(event => {
  event.participants = [{"name": "Jane Doe Events", 'email':'janedoeevents@example.com'}]
  event.location = 'The Ritz Carlton'
  event.description = 'We will ring in 2025 at the Ritz!'

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

Notify participants

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

When notify_participants=false, the request doesn't create an event for the participant. Participants do not receive an email or an ICS file. Use the Generate ICS File endpoint to generate a separate file to configure for participants.

Keep in mind

The overview below covers the main points of the request:

  • <EVENT_ID> takes the value of the id for the event that you want to update.
  • The participants attribute is an array of participant sub-objects.

Check out the Events reference documentation to learn about the parameters that can be modified for an event object.

Delete an event

If an event is cancelled, you can delete it and send a notification to all participants. The following examples show how to delete an event using the Nylas APIs.

curl -X DELETE https://<ACCESS_TOKEN>:@api.nylas.com/events/{id}?notify_participants=true

You can also delete an event using the Nylas SDKs.

from nylas import APIClient

nylas = APIClient(
    NYLAS_CLIENT_ID,
    NYLAS_CLIENT_SECRET,
    ACCESS_TOKEN
)

event = nylas.events.get('{id}')

nylas.events.delete(event.id, notify_participants='true')   
const Nylas = require('nylas');

Nylas.config({
  clientId: NYLAS_CLIENT_ID,
  clientSecret: NYLAS_CLIENT_SECRET
});

const nylas = Nylas.with(ACCESS_TOKEN);

nylas.events.delete('{id}', notify_participants='true')

Adding conferencing details

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

Get available room resources

In some provider configurations, you can use the Nylas API to get a list of room resources that you can add to events. These usually represent physical spaces like conference rooms, physical equipment like projectors or AV systems, or sometimes virtual equipment like videoconference bridges or phone conference lines. Room resources require that the administrator of your provider system configures bookable resources, and are separate from the conferencing details that you can add.

ℹ️ Room Resources is available for v2 Core and Plus plans.

In the following examples, replace <ACCESS_TOKEN> with your account access token. See the Room resources reference documentation for more information.

curl --request GET \
  --url https://api.nylas.com/resources \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json'   
const Nylas = require('nylas');
Nylas.config({clientId: 'clientId', clientSecret: 'clientSecret'});
const nylas = Nylas.with('access_token');

// Return all resources associated with the account
nylas.resources.list().then(resource => console.log(resource));   
from nylas import APIClient

nylas = APIClient(
    <NYLAS_CLIENT_ID>,
    <NYLAS_CLIENT_SECRET>,
    <NYLAS_ACCESS_TOKEN>
)

# Return all resources associated with the account
nylas.room_resources.all()   
# !/usr/bin/env ruby
require 'nylas'

# Initialize and connect to the Nylas client
nylas = Nylas::API.new(
    app_id: <NYLAS_CLIENT_ID>,
    app_secret: <NYLAS_CLIENT_SECRET>,
    access_token: <NYLAS_ACCESS_TOKEN>
)

resources = nylas.room_resources   
// Initialize and connect to the Nylas client
NylasClient nylas = new NylasClient();
NylasAccount account = nylas.account("ACCESS_TOKEN");

RoomResources roomResource = account.roomResources();
List<RoomResource> roomResourceList = roomResource.list();

Group meetings

Group meetings allow an organizer to set specific times when they are 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. The attendee can choose to sign up if one of the set times works for them. When the attendee books the 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 that event.

Enabling attendance limits

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

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

The examples below show an event request body that creates an event that allows up to five attendees.

{
  "title": "Fireside Forum",
  "when": {
    "start_time": 1649991600,
    "end_time": 1649995200,
    "start_timezone": "America/Toronto",
    "end_timezone": "America/Toronto"
  },
  "round_robin_order": [],
  "capacity": 5,
  "calendar_id":"<calendar_id>",
  "participants": [{
    "email": "<participant email>"
  }]
}