Nylas Calendar API Supports Recurring Events CRUD for Office 365/Outlook and Exchange Calendars

Nylas Calendar API Supports Recurring Events for Office 365, Outlook, and Exchange Calendars

Use the Nylas Calendar API to easily create, update and delete recurring events for your Microsoft calendars.

Jieun Kim | December 18, 2019

We know recurring events are integral to your day-to-day— whether it’s quarterly business analysis meetings or  1:1s with your teammates, it’s important to be able to easily create recurring events and to edit them as things come up… and they always do! For example, say a new hire to your team needs to be added to the department’s quarterly meeting, or maybe there’s been a big office move and the meeting location now needs to be updated. 

Previously, the Nylas API —which makes it easy to integrate full calendar data from 100% of providers—supported recurring events CRUD  for Google Calendars only. We are excited to share that, as of today, developers can now create, read, update and delete recurring events within our API for Microsoft calendars as well, adding to our robust set of calendar features.

Creating a Recurring Event with the Nylas Calendar API

Now that you can easily schedule recurring meetings for your Microsoft accounts via the Nylas API, let’s take a look at how one would set this up. To create the event, make a POST call to the /events endpoint and include the recurrence object in the payload:

curl -X POST \

  https://api.nylas.com/events \

  -H 'Content-Type: application/json' \

  -H 'cache-control: no-cache' \

  -d '{

    "title":"coffee",

    "location": "cafe grumpy",

    "calendar_id": "b464omkvjd1831vyzk70nowtze",

    "participants": [

        {

            "email": "[email protected]"
        },

       {

            “email”: “[email protected]”,

            “status”: “yes”

       }

    ], 

"recurrence": { "rrule": [ "RRULE:FREQ=WEEKLY;BYDAY=MO" ], 

"timezone": "America/Los_Angeles" }, 

"when": { "start_time": 1574100000, "end_time": 1574103600 }

}'

This will create a weekly recurring event for Kofi and Edna to get coffee on Mondays.  You’ll notice the recurrence object also supports a timezone parameter. 

Updating An Occurrence of a Recurring Event with the Nylas Calendar API

But what if Edna wants to update one occurrence of the recurring event she just created? Maybe she’d like to change the location one week to check out a new coffee shop that just opened up. We call this modification an override.  To do so, Edna makes a GET / request to the /events endpoint to retrieve the occurrences of the event so she can select the ID of the specific occurrence she’d like to update:

curl -X GET \

  'https://api.nylas.com/events?expand_recurring=true&title=coffee' \

  -H 'Authorization: Basic bXXXXXXXXXXWWM2SHgxOUh6NHBTcXBQOg==' \

  -H 'Host: api.nylas.com' \

It may interest you to know that in the Nylas database, we store a single “Master event” in our database that represents a series of events as defined by the RRULE. Developers can request that our API returns all of the events even though they don’t technically exist in our database and these events are “inflated” each time the request is made on the fly. This is the significance of the  ‘expand_recurring’ parameter, as setting it to ‘true’ will return all occurrences of the event, not just the master recurring event. Meanwhile, the phrase ‘coffee’ was passed into the parameter ‘title’ to help winnow down results.

When Edna gets back the response, the occurrence hasn’t been updated before, so the first thing she’ll see is that the format of the ID is a little different than the more commonly seen Nylas IDs that do not contain the underscore character. Edna’s occurrence ID will look something like this: 4l9hosbl407h7ts99v7abvt5y_20191118T190000Z

This format here is {master_event_id}_{start_time}.  On the other hand, if the occurrence has been overridden before, then a new ID without an underscore will be returned in your response and that ID is the one that should be used for any future modifications you’d like to make. 

To update the occurrence,  make a PUT / call to the events/{id} endpoint with the occurrence ID passed in, and the payload with the relevant updated information (in this case, the location ‘Cafe Grumpy’ has been updated to ‘Cafe Cheerful’) like so:

curl -X PUT \

  'https://api.nylas.com/events/4l9hosbl407h7ts99v7abvt5y_20191118T190000Z' \

  -H 'Authorization: Basic bHh6U3JqYzXXXXXhDMXhXWWM2SHgxOUh6NHBTcXBQOg==' \

  -H 'Host: api.nylas.com' \

  -H 'cache-control: no-cache' \

  -d '{

    "title":"coffee",

    "location": "Cafe Cheerful",

    "calendar_id": "ad3x2u7pf63wvjbp64bmzq1o7",

    "participants": [

        {

            "email": "[email protected]"

        },

        {

            "email": "[email protected]"

         }

    ]

}

'

Great – Cafe Cheerful, here they come!

In addition to overrides, Nylas supports exdates as a way to modify occurrences. An exdate is simply a list of timestamps that indicate which dates have been excluded or deleted from a series. These are represented within the RRULE array.  For example, if we were to include an exdate in our first code snippet above (where we created a recurring event), we would just need to add the EXDATE component to the rrule list in the recurrence object, like so: 

curl -X POST \

  https://api.nylas.com/events \

  -H 'Content-Type: application/json' \

  -H 'cache-control: no-cache' \

  -d '{

    "title":"coffee",

    "location": "cafe grumpy",

    "calendar_id": "b464omkvjd1831vyzk70nowtze",

    "participants": [

        {

            "email": "[email protected]"

        },

        {
 
            “email”: “[email protected]”,
            “status”: “yes” 

        }

    ], 

    "recurrence": { "rrule": [ "RRULE:FREQ=WEEKLY;BYDAY=MO", 
 
    "EXDATE:20191216T180000Z" ], 

    "timezone": "America/Los_Angeles" }, 

    "when": { "start_time": 1574100000, "end_time": 1574103600 }

}'

Deleting Recurring Events with the Nylas Calendar API

Say Edna’s had her fill of coffee dates, and she’d like to delete this recurring event. To do so, she’ll need the master event ID; recall from the example above that this is the first part of the occurrence ID preceding the underscore – it can also be found as an attribute on the event object. For our purposes, the ID is 4l9hosbl407h7ts99v7abvt5y.

Simply make a DELETE call to the /events/4l9hosbl407h7ts99v7abvt5y

and hey presto! That will disappear the recurring events from your calendar. 

Check out a few important notes about recurring events to keep in mind (as well as key differences between providers) and get started building full calendar sync and CRUD with the Nylas APIs. Check out the docs here.

And now that you can create, update and delete recurring events in your account—be it a Google or Microsoft account—  your users can get back to scheduling all the important recurring events in their lives with ease! 

Ready to Start Building?

Get Started – Build your first integration with Nylas in 15 minutes.

Quickstart Guides – Get up to speed quickly with our SDKs for Python, Node.js, and Ruby or explore the Nylas Email, Calendar, and Contacts APIs.

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

Nylas Recurring Events API reference – Take a look at the Nylas recurring events under the hood.

Nylas free-busy API reference – Take a look at the Nylas free-busy endpoint under the hood.

Tutorials – Check out our tutorials to learn how to carry out common functionality like creating, reading and RSVP-ing to calendar events.

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

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

 

 

About the Author

jieun kim is a technical writer based in nyc. in her spare time, she enjoys contemplating unusual shapes and accumulating large stacks of books.

Ready to Start Building?

Connect up to 10 accounts for free today. No credit card required.