Only show these results:

Using the Calendar API

This guide goes over 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, go through our quickstart guide before proceeding.

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

  • Viewing the calendars and events of connected user accounts.
  • Creating new events.
  • Sending event invites.
  • RSVPing 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.

In this guide, we use a query parameter for a limit of five results. Check our documentation 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.

Example scripts are shown below:

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 our calendars API documentation to learn about the values the calendars endpoint returns.

While going through this guide, copy the id of a calendar that you are willing to make modifications to. You can always create a new calendar for this purpose if you don't want to test features out on any of your existing calendars.

The is_primary field is for Google and EWS calendars. If it has a value of true, it's the primary calendar. If it's false, it's either a secondary or a child calendar.

For other providers, the primary calendar either 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 aren't 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 can't be added, updated, or deleted. This calendar should be completely ignored for non-IMAP accounts since it contains the same events that are in the primary calendar.

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

Example scripts are shown below:

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.

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": "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.

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

Review the API documentation 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 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 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 sub-object. 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 true.

When notify_participants=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 our documentation on events reference 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.

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

In the following example, replace <ACCESS_TOKEN> with the appropriate account access token. Take a look at our API documentation for more information about room resources.

curl -X GET "https://api.nylas.com/resources" \
-H "Content-Type: application/json" \
-H "Authorization: Basic <ACCESS_TOKEN>"

Delete an Event

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