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

This guide will help you test out the Nylas Calendar API and explore some of the more common features the API provides. If you haven't already, please follow all of the steps in our guide on how to get your developer API keys. You will need the access token generated as part of that guide to follow the commands outlined here.

At the end of this guide, you should understand 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.

Hey there 👋

New here? Our Getting Started guide is a great place to begin.

How to use these examples

For all of the examples shown on this page, replace {access_token} with the access token you received when you completed the developer API keys guide before making the example call.

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

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}

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

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}

You can also query by attributes like location.

curl -X GET https://{access_token}:@api.nylas.com/events?location={my_location}

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

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!"
}'

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}"
}'

Delete an Event

Oh no! We weren't able to get a reservation at the Ritz for our party, so we need to delete the event, and notify all of the participants that it's been canceled.

curl -X DELETE https://{access_token}:@api.nylas.com/events/{id}?notify_participants=true

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.

Additional Resources

Here are some additional resources for when you're ready to move on.

  • Take a look at the quickstart guides for the Nylas Email and Contacts APIs to explore the features of the Nylas communication platform.
  • Set up Postman to make it easy to explore the Nylas API.
  • When you're ready to start integrating the Nylas communication platform into your app, take a look at our app integration guide.
  • Finally, you can always take a look at the API reference for more detail about how the Nylas APIs work.

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.