Only show these results:

Using the Nylas Events API

Nylas gives you secure, reliable access to calendar and event data using a unified API. A Calendar object serves as a container for Event objects, and Events function as containers for information about scheduled events that are going to happen. This includes a list of the people involved, details about the time, meeting location, and a description. It can also include attachments and information about who has confirmed their attendance.

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 in this document, 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 all of a user's calendars, make a request to the events endpoint.

Example scripts are shown below:

curl -X GET https://api.nylas.com/events   
from nylas import APIClient

nylas = APIClient(
    APP_ID,
    APP_SECRET,
    ACCESS_TOKEN
)

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

nylas.events.list().then(events => console.log(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 <[email protected]>",
        "participants": [
            {
                "comment": null,
                "email": "[email protected]",
                "name": null,
                "status": "yes"
            },
            {
                "comment": null,
                "email": "[email protected]",
                "name": null,
                "status": "maybe"
            }
        ],
        "read_only": true,
        "status": "confirmed",
        "title": "Meet with Nylas",
        "when": {
            "end_time": 1478568600,
            "object": "timespan",
            "start_time": 1478565000
        }
    }
]

By default, Nylas returns 100 objects. Results are sorted by the start date and time, beginning with the oldest.

If you know the event ID of a specific event you're interested in, you can use the /events/<id> endpoint instead.

Filtering a list of events

You can use queries to filter the events. For example, you can filter to return only events from a single calendar.

Example scripts are shown below:

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

nylas = APIClient(
    APP_ID,
    APP_SECRET,
    ACCESS_TOKEN
)

print(nylas.events.where(calendar_id='{id}'))   
const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

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

For more information about the parameters you can use in queries to the /events endpoint, see the Events API documentation.

Creating events

In this section and the following two, we'll create, then modify an event.

It's time to create your first event using the Nylas calendar API!

The following example demonstrates a basic event for a New Year's Eve party at the Ritz Carlton. Replace <CALENDAR_ID> with the value for the calendar you want to add this event to:

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": "[email protected]"
        }
    ]
}'

This command creates an event for a New Year's Eve party on December 31, 2019 at 10 PM UTC. The values for when can be one of four subobjects. Review our documentation on event subobjects for more information.

This example also adds a room resource with the participants attribute. To add room resources, include the email address associated with that room. Take a look at our API documentation on resources for more information.

Check the response from the Nylas API when you create this event and copy the value for id to reference in the next step.

Modify an event and send an email invite

Let's also invite friends to this event!

The following command adds a participant to the event and sends them an email invite. It also contains additional details for the 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": "[email protected]",
            "name": "My Friend",
            "status": "noreply"
        }
    ],
    "description": "We will ring in 2020 at the Ritz!"
}'   
from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

event = nylas.events.get('<EVENT_ID>')
event.location = "The Ritz Carlton"
event.participants = [{"name": "My Friend", 'email': '[email protected]'}]
event.save(notify_participants='true')   
const Nylas = require('nylas');

Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

nylas.events.find('<EVENT_ID>').then(event => {
    event.participants = [{"name": "Jane Doe Events", 'email':'[email protected]'}]
    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 subobject. 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 subobjects.

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

Deleting events

If an event is cancelled, you can delete it and send a notification to all participants to let them know that it's been cancelled:

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

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

event = nylas.events.get('{id}')
nylas.events.delete(event.id, notify_participants='true')   
const Nylas = require('nylas');
Nylas.config({
    clientId: CLIENT_ID,
    clientSecret: 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.

RSVP to Events

✨ The Send RSVP endpoint has been updated for the Nylas API v3 Beta. For more information, see the Changes to RSVPs section. To learn more about the API v3 Beta, see the v3 Beta documentation.

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

The POST /send-rsvp endpoint (migrated to POST /v3/grants/<grant_id>/events/<event_id>/send-rsvp in v3 Beta) lets you send a response to the 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.

When you want to RSVP to an Event, simply pass your intended RSVP status in a POST request, as in the following examples.

curl --request POST \
  --url https://api.nylas.com/send-rsvp \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_id": "string",
    "status": "yes",
    "account_id": "string"
}'   
curl --request POST \
  --url https://api.us.nylas.com/v3/grants/<GRANT_ID>/events/<EVENT_ID>/send-rsvp?calendar_id=<CALENDAR_ID> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <API_KEY_OR_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "yes"
  }'

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 sometime 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 (v3 conferencing) that you can add.

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

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

curl --request GET \
  --url https://api.nylas.com/resources \
  --header 'Accept: application/json' \
  --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(
    CLIENT_ID,
    CLIENT_SECRET,
    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: CLIENT_ID,
  app_secret: CLIENT_SECRET,
  access_token: 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();