Only show these results:

Using the Calendar API

This article contains examples that demonstrate the basic functionality of the Nylas Calendar API using curl. Many of these examples include examples of a JSON response so you can see what they return, but if you would like to try these examples yourself, complete the developer API keys guide before proceeding.

The examples in this section will cover how to use the Nylas Calendar API to:

  • View the calendars and events of connected user accounts,
  • Create new events and send event invites, and
  • RSVP to events.

Get Available Calendars

Most user accounts will be subscribed to multiple calendars. To view a list of all calendars the user has access to, make a request to the calendars endpoint. For the purpose of this guide, we will use a query parameter to limit it to 5 results. Review the docs on pagination to learn more about controlling the number of objects that are returned. The calendars endpoint also supports views to further customize the response.

curl -X GET https://api.nylas.com/calendars?limit=5   
from nylas import APIClient

nylas = APIClient(
APP_ID,
APP_SECRET,
ACCESS_TOKEN
)

print(nylas.calendars.where(limit=5))
const Nylas = require('nylas');
Nylas.config({
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.calendars.list({limit: 5}).then(calendars => console.log(calendars));
[
{
"account_id": "joujhadwh59pz9rvfjfw",
"description": "Emailed events",
"id": "zd08j9stfph95u449vti",
"name": "Emailed events",
"object": "calendar",
"read_only": true
},
{
"account_id": "joujhadwh59pz9rvfjfw",
"description": null,
"id": "a6jx8278v11s53itpdcn",
"name": "swag@nylas.com",
"object": "calendar",
"read_only": false
}
]

Review the calendars API reference to learn about the values the calendars endpoint returns. In particular, you should copy the id of a calendar that you are willing to make modifications to while following the rest of this guide. You can always create a new calendar for this purpose if you don't want to test things out on any of your existing calendars.

The primary calendar for an account usually has the same name as the email address, or is sometimes simply called "Calendar." Users may also have other custom calendars, or access to shared team calendars.

All accounts also include a special calendar called "Emailed events" which contains event invitations that have been sent to the user's mailbox. This calendar is read-only, meaning events cannot be added, updated, or deleted.

You can return information for a single calendar by providing the appropriate calendar id.

curl -X GET https://api.nylas.com/calendars/{calendar_id}   
from nylas import APIClient

nylas = APIClient(
APP_ID,
APP_SECRET,
ACCESS_TOKEN
)

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

nylas.calendars.find('{id}').then(calendar => console.log(calendar));
{
"account_id": "joujhadwh59pz9rvfjfw",
"description": "Emailed events",
"id": "zd08j9stfph95u449vti",
"name": "Emailed events",
"object": "calendar",
"read_only": true
}

Read Content from Events

To return a list of events from all of a user's calendars, make a request to the events endpoint.

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": "My Nylas Friend <swag@nylas.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
}
}
]

The default behavior returns 100 objects, sorted by the start date and time from oldest to the furthest into the future.

You can use queries to filter the events that are returned, such as returning only events from a single calendar.

curl -X GET https://api.nylas.com/calendars/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));

Review the API reference for the events endpoint to see other parameters that can be used in queries.

Create, Modify, and Delete Events

It's time to create your first event using the Nylas calendar API! The following example demonstrates a very basic event for a new years 2020 party we're planning at the Ritz Carlton. Make sure you replace {calendar_id} with the value for the calendar you want to add this event to.

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

This command will create an event for a New Years party on December 31 2019 at 10 PM UTC. The values for when can be one of four subobjects. review the reference docs on event subobjects to learn more.

This example also adds a room resource via the participants attribute. To add room resources, you need to include the email address associated with that room. Take a look at the API docs for resources to learn more.

Take a look at the response the Nylas API provides when you create this event and copy the value for id; we will need it in the next step.

Modify an Event and Send an Email Invite

We can't forget to invite our friends! The following command will add a participant to the event and send them an email invite. It will also add some additional details to the invite.

You're about to send a real event invite!

The following command will send an email from the account you've connected to the Nylas API to any email addresses that are specified in the participant's subobject. Make sure you actually want to send this invite before you run 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!"
}'
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': 'my.friend@example.com'}]
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": "My Nylase Friend", 'email':'swag@nylas.com'}]
event.location = 'The Ritz Carlton'
event.description = 'We will ring in 2020 at the Ritz!'
event.save({ notify_participants: true }).then(event => {
console.log(event);
});
});

There is a lot to unpack here, so let's break it down.

  • {event_id} should be replaced with the id for the event that you want to update.
  • The query parameter notify_participants=true is responsible for sending an email invite to all email addresses listed in the participants subobject. This is false by default.
  • The participants attribute is an array of participant subobjects. Review the reference docs on event subobjects to learn more.

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

Get Available Room Resources

Nylas supports getting a list of room resources for some accounts that can be added to events. In the following example, replace {access_token} with the appropriate account access token. Take a look at the API docs for more info about room resources.

curl -X GET "https://api.nylas.com/resources" \
-H "Content-Type: application/json" \
-H "Authorization: Basic {access_token}"

RSVP to Events

No calendar is complete without the ability to send RSVP statuses to event participants. The send-rsvp endpoint makes this possible; it sends an email notification to all email addresses found in the participants subobject. In the following example, replace the {event_id} and {account_id} with the appropriate values; you can find these by inspecting the response the Nylas Calendar API provided when you first created the event.

curl -X POST \
https://{access_token}:@api.nylas.com/send-rsvp?notify_participants=true \
-d '{
"event_id": "{event_id}",
"status": "yes",
"account_id": "{account_id}"
}'
const Nylas = require('nylas');
Nylas.config({
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET,
});
const nylas = Nylas.with(ACCESS_TOKEN);

nylas.events.first({calendar_id: '{calendar_id}', title: "New Years Party!"}).then(event => {
event.rsvp('yes', 'I can\'t wait to ring in the new year!')
})

Delete an Event

Sometimes plans change and events are cancelled, so they need to be deleted with a notification sent to all participants that it's been canceled.

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')