Nylas Docs

The Nylas Developer Hub

Welcome to the Nylas developer hub. You'll find comprehensive guides and documentation to help you start working with Nylas as quickly as possible, as well as support if you get stuck. Let's jump right in!

Developer Guide

Calendar API

Explore the Nylas Calendar API

Nylas Calendar API Quickstart Guide

The Nylas Calendar API powers your application with a secure, reliable connection to your user’s calendars. Sync historic and live events into your application in real-time. Get bi-directional calendar sync and full CRUD (create, read, update, delete) capabilities with Google Calendar, Exchange Calendar, iCal, Outlook.com calendars and the rest with just a few lines of code.

The Nylas Calendar API provides a REST interface that includes functionality to

  • Access data for calendars and events, such as event titles, location, description, dates, and more.
  • Search for availability across any number of calendars.
  • Schedule events, send notifications, and RSVP to existing events.

Calendar API Endpoints

This section covers all of the endpoints the Nylas Calendar API provides to enable you to integrate full calendar functionality into your app.

Calendars

Each account connected to Nylas can have zero or more calendars, and each calendar contains a collection of individual events. Accounts can have many calendars including a primary calendar, shared team calendars, read access to colleagues' calendars, and other custom calendars. Calendars that are associated with email accounts typically have a primary calendar for the user's email, as well as an emailed events calendar that contains events that have been sent to a user's email inbox.

Events

Events are objects within a calendar that generally support all features and attributes of modern scheduling apps like event names, list of participants, descriptions, location, time, etc. Nylas supports all event functionality you would expect, including sending email invites, RSVP status checks and notifications, creating and modifying events, and recurring events (Google accounts only).

Other Features of the Nylas Calendar API

The Nylas Communications Platform provides other functionality that makes it easy for you to build your calendar integration.

Filtering allow you to narrow requests based on specific parameters like event titles, locations, and start and end time. Filters help you reduce the size of your API requests which results in faster performance.

Pagination makes it possible to control the number of results that are returned.

Webhooks allow your application to receive notifications when certain events occur such the creation or update of calendars and events.

Deltas enable you to process new data quickly without fetching an index of the user's calendar or performing a large number of API calls.

Quickstart Examples

This section contains examples that demonstrate 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://{access_token}:@api.nylas.com/calendars?limit=5
[
    {
        "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
    }
]
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));

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://{access_token}:@api.nylas.com/calendars/{calendar_id}
{
    "account_id": "joujhadwh59pz9rvfjfw",
    "description": "Emailed events",
    "id": "zd08j9stfph95u449vti",
    "name": "Emailed events",
    "object": "calendar",
    "read_only": true
}
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));
Ready to Build Your Calendar Integration?

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://{access_token}:@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": "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
        }
    }
]
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));

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://{access_token}:@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.

Ready to Build Your Calendar Integration?

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://{access_token}:@api.nylas.com/events \
  -d '{
    "title": "Party at the Ritz!",
    "when": {
        "start_time": 1577829600,
        "end_time": 1577844000
    },
    "calendar_id": "{calendar_id}"
}'
from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN,
)

event = nylas.events.create()
event.title = "New Years Party!"
event.when = {"start_time": 1577829600, "end_time": 1577844000}
event.calendar_id = '{calendar_id}'
event.save()
const Nylas = require('nylas');

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

const nylas = Nylas.with(ACCESS_TOKEN);

const event = nylas.events.build({
    title: 'New Years Party!',
    when: { start_time: 1577829600, end_time: 1577844000 },
    calendarId: CALENDAR_ID
  });
event.save().then(event => {
    console.log(event);
});

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.

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 participants 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, which you made note of above.
  • 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.

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')
Ready to Build Your Calendar Integration?

Build with the Nylas SDKs

The Nylas SDKs are the quickest way to get started integrating the Nylas Calendar API into your app. We offer SDKs for Python, Node.js, and Ruby to suit a variety of preferences.

Next Steps

How Nylas Works - Take a look at the Nylas architecture to see how we sync billions of events.

Quickstart Guides - Get up to speed quickly with our SDKs using our quickstart guides for Python and Node.js, or explore the Nylas Email or Contacts API.

Tutorials - Check out our plethora of tutorials to learn how to carry out common functionality, like creating new events, sending email invitations, RSVPing to events, and checking for calendar availability.

Integration Guides - Ready to start building your integration? Our integration guides cover what it takes to incorporate calendar functionality into your app. They cover best practices for using the Nylas Communications Platform and provider-specific advice for Google, Microsoft, and more.

Set up Postman - Postman makes it easy to explore the Nylas Calendar API.

API Reference - Our API reference provides all the detail you need to know to use the Nylas Communications Platform.

Calendar API


Explore the Nylas Calendar API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.