Recurring Events
For scheduling events with a repeating pattern, use a calendar standard called RRULE. This property describes how to format recurring events for calendars. Use the recurrence RRULE standards for Nylas API requests to the Events endpoint. Create or update recurring events through POST or PUT requests. This guide provides explanations of the formatting and recurrence use.
RRULE Formatting
Recurring events use a specific syntax for repeated patterns in calendars. The code below is the basic formatting structure. This formatting is for the request body of an Events endpoint API request or for the recurrence
object in the SDKs.
Attribute | Type | Description |
---|---|---|
rrule |
array | An array of RRULE and EXDATE strings. See RFC-5545 for more details. EXRULE and RDATE strings are not supported for POST or PUT requests at this time. |
timezone |
string | IANA time zone database formatted string (e.g. America/New_York). |
The RRULE formatting is an array of two strings. The first string value in the array is for the recurring event patterns. This string begins with RRULE
and separates option value pairs with semicolons. The second string value in the array is the optional EXDATE
to exclude dates from the pattern.
See the Excluding Dates and Timezone sections for more info.
rrule: ["RRULE: OPTIONS=VALUE;OPTIONS=VALUE", "EXDATE: ISO_8601_TIME"], timezone: "STRING"
The table below shows common options for RRULE configurations. View the What's Next section for more resources on RRULE standards.
Options | Values | Description |
---|---|---|
FREQ |
YEARLY , MONTHLY , WEEKLY , DAILY , HOURLY |
Frequency in time. |
BYDAY |
MO , TU , WE , TH , FR , SA , SU |
Day of the week specified, Nylas defaults to date and time values from original event if not included. |
BYMONTH |
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] |
Month specified by corresponding number, e.g. January is 1 , February is 2 , etc. |
COUNT |
integer | Number of instances for recurring event. |
INTERVAL |
integer | Interval between each frequency iteration, e.g. monthly frequency with 2 means every two months. |
Excluding Dates
Omit specific dates with the EXDATE
property in the rrule
array. Only ISO 8601 values are valid. EXDATE
is an optional string. View the Recurrence RRULE Example section for a sample request.
Timezone
The timezone option uses IANA time zone database formatted string values.
Recurrence RRULE Example
The following examples use each of the options. These SDK samples show configurations with the recurrence object.
Each option in the RRULE corresponds to a pattern. These are separated with semicolons in the RRULE string. The list below shows the relationship between the RRULE formatting and the patterns.
- Every two years -
FREQ=YEARLY
,INTERVAL=2
- On Monday, Wednesday, and Friday -
BYDAY=MO,WE,FR
- In February, April, June, September, and November -
BYMONTH=2,4,6,9,11
- 75 times total -
COUNT=75
- Doesn't occur on November 20th, 2021 at 5:20:47 GMT -
"EXDATE:20211120T0420470000"
"recurrence": {
"rrule": [
"RRULE:FREQ=YEARLY;BYDAY=MO,WE,FR;BYMONTH=2,4,6,9,11;COUNT=75;INTERVAL=2",
"EXDATE:20211120T0520470000"
],
"timezone": "America/Los_Angeles"
event.recurrence = {"rrule": ["RRULE:FREQ=YEARLY;BYDAY=MO,WE,FR;BYMONTH=2,4,6,9,11;COUNT=75;INTERVAL=2", "EXDATE:20211120T052047000"], "timezone": "America_Los_Angeles"}
recurrence: {rrule: ["RRULE:FREQ=YEARLY;BYDAY=MO,WE,FR;BYMONTH=2,4,6,9,11;COUNT=75;INTERVAL=2", "EXDATE:20211120T052047000"], timezone: "America/Los_Angeles"}
event.recurrence = {rrule: ["RRULE:FREQ=YEARLY;BYDAY=MO,WE,FR;BYMONTH=2,4,6,9,11;COUNT=75;INTERVAL=2", "EXDATE:20211120T052047000"], timezone: "America/Los_Angeles"}
Best Practices
The sections below cover various RRULE behaviors in Nylas and from other providers. This info is helpful for creating and changing recurring events.
Event Changes or Updates
Updating or deleting a recurring event's main event impacts all instances of the event. Omit individual events using the EXDATE
property. Individual event overrides are supported in recurring events.
Expand Recurring Parameter
When retrieving events through the API, the expand_recurring
parameter set to true
provides all instances of a recurring event. When requesting events without the expand_recurring
parameter, the events endpoint only returns the master
recurring event. This applies only if the master
event falls within the requested time range.
Recurring events with overrides, such as changes or deletions to individual events, return separately. The expand_recurring
value as true
doesn't impact how the events get returned. If expand_recurring
isn't configured, any cancellations are returned in addition to the base event. This applies for apps with recurrence expanded on the client. Cancellations have the field cancelled
set to true
.
Recurring Event Defaults
The event time for recurring events is the same as the original event. RRULE formatting doesn’t allow for changes to the event time. To change the time of an individual event, make a PUT API request to the Events endpoint.
If BYDAY
isn't included in the RRULE string for weekly events, for example FREQ=WEEKLY
, Nylas defaults to information from the event's date or time values.
Provider Support
The table below compares the differences for providers and recurring events.
Description | Google Behavior | Microsoft Behavior |
---|---|---|
Modifying the recurrence of a series, such as changing an event from weekly to daily. | Overrides remain unchanged if they are still part of the recurrence. | Overrides are removed. |
Changes to busy status on the main event for a series. | Busy status updates for all events in the series, including overrides. | Busy status doesn't update for overrides that were created through Nylas. However, they update for overrides created through Microsoft's native calendar interface. |
Deleting a single occurrence from a series within the provider's native calendar UI. | This delete appears as an override event. The status changes to cancelled using the Nylas API. |
This delete appears as an EXDATE using the Nylas API. |
Creating a recurring event in the provider's UI with an end date for the recurrence. | The end date shows up as 23:59:59 after the last occurrence in the account's local timezone using the Nylas API. |
The end date shows up as the start time of the last occurrence in the series using the Nylas API. |
Additional Microsoft Limitations
If a recurring event has an EXDATE
, you can't recover or undo the removed occurrence. Either create a new, separate event to represent a recovered EXDATE
or use other event properties like status
. These options allow you to change the event information at another time.
The following RRULEs aren't supported for Microsoft accounts at this time.
RRULE:FREQ=MONTHLY;BYDAY=1TH,3TH
- A Monthly recurrence with multiple days. Microsoft accounts don't support different indices. The index property is on the monthly recurrence object and not on each day-of-week object.
Exchange doesn't allow you to reschedule an instance of a recurring event that is going to fall on the day of or the day before of the previous instance. You are not able to overlap recurring events. Learn more about this error in the Microsoft documentation.
Unsupported Properties
Nylas doesn’t support EXRULE
and RDATE
strings for API requests at this time.
Editing the EXDATE
value after creating a recurring event returns a 200
successful job, but doesn't remove or delete events. Use the Delete An Event endpoint to remove an individual child event from a created recurring parent event.
What's Next
Recurring events and RRULE's robust configurations help make scheduling even easier. Use these formatting standards to add convenient repeating patterns for your users' events. View the links below for the Nylas blog post on RRULEs, Events endpoint API documentation, as well as SDK tutorials for events.
- Nylas RRULE Blog Post
- Events API Documentation
- Events with Node.js Tutorial
- Events with Python Tutorial
Resources
See the links below for resources about RRULE and recurrence.
The following is a demo Javascript library. This is a comprehensive reference for RRULE options as well as input and output descriptions.
Video Walkthrough
Prefer video? You can watch our LiveStream Coding with Nylas.
What's Next?
- Read the blog post How to Create Recurring Events Using RRule.