Only show these results:

Using the Calendar API

This guide demonstrates the basic functionality of the Nylas Calendar API using curl. Many of these examples include JSON responses for detailing returns.

To try these examples yourself, complete the developer API keys guide before proceeding.

The examples in this section cover how to use the Nylas Calendar API for the following actions.

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

Get Available Calendars

Most user accounts subscribe to multiple calendars. To view a list of all calendars the user has access to, make a request to the calendars endpoint.

For this guide, we use a query parameter for a limit of 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": "[email protected]",
        "object": "calendar",
        "read_only": false
    }
]

Review the calendars API reference to learn about the values the calendars endpoint returns.

In particular, 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 is_primary field is for Google and EWS calendars. If true, then it's the primary calendar, if false it's a secondary or a child calendar.

For other providers the primary calendar usually has the same name as the email address or is called Calendar. Users may also have other custom calendars or access to shared team calendars.

Microsoft Shared Calendars

Microsoft Shared Calendars are not supported through the Nylas Calendar API.

All accounts also include a special calendar called Emailed events. This calendar contains event invitations that have been sent to the user's mailbox. The Emailed events calendar is read-only, and events cannot be added, updated, or deleted.
The Emailed events calendar should be completely ignored for non-IMAP accounts since it contains the same events in the primary calendar.

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 <[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
        }
    }
]

The default behavior returns 100 objects. Results are sorted by the start date and time beginning with the oldest first.

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

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

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 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 the reference docs on event subobjects to learn more.

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 the API docs for resources to learn more.

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 command sends 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 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": "My Nylase Friend", 'email':'[email protected]'}]
    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);
    });
  });

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 false. When false, the request doesn't create an event for the participant. Participants will not receive an email or an ICS file. Use the Generate ICS File endpoint to have 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 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

Complete your calendar's functionality with sending RSVP statuses to event participants. The send-rsvp endpoint 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 Year's Eve Party!"}).then(event => {
    event.rsvp('yes', 'I can\'t wait to ring in the new year!')
})

Delete an Event

Sometimes plans change. If events are cancelled, they can be deleted with a notification sent to all participants 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')