Only show these results:

Recurring Events

Nylas uses the RRULE calendar standard to schedule and format recurring events. This page explains how to use RRULE and the events endpoint to create and update recurring events.

ℹ️ Recurring Events Edit is available for Entry, Core, and Plus plans.

RRULE formatting syntax

RRULE uses a specific syntax for recurring events in calendars. The formatting described in this table is for the request body of an Events endpoint API request or for the recurrence object in the SDKs:

Parameter Type Description
rrule Array An array of RRULE and EXDATE strings. See RFC-5545 for more information.

Note that EXRULE and RDATE strings are not currently supported for POST or PUT requests.
timezone String An IANA timezone database-formatted string (for example, America/New_York).

The rrule parameter is an array of two strings. The first string value in the array represents the recurring event patterns; it begins with RRULE and separates option-value pairs with semicolons (;). The second string in the array is the optional EXDATE value, which excludes dates from the pattern. For example, this array represents a sample recurring event:

rrule: ["RRULE: OPTIONS=VALUE;OPTIONS=VALUE", "EXDATE: ISO_8601_TIME"], timezone: "STRING"

Exclude dates from a recurrence schedule

You can omit specific dates from a recurring event by using the optional EXDATE property in an event's rrule array. Note that only ISO 8601 values are valid.

RRULE configuration options

This table shows common options for RRULE configurations:

Option Value Description
FREQ YEARLY, MONTHLY, WEEKLY, DAILY, HOURLY The event's recurrence frequency.
BYDAY MO, TU, WE, TH, FR, SA, SU The day of the week on which the recurring event occurs. If not specified, Nylas uses the date and time values from the original event.
BYMONTH [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] The month, specified by its corresponding number (for example, October is 10).
COUNT Integer The number of times the event recurs.
INTERVAL Integer The interval between each recurrence (for example, a FREQ of MONTHLY with an INTERVAL of 2 means the event recurs every two months).

Learn More

For more information on RRULE standards, see the links in the What's next? section.

Examples: Recurrence RRULE

The SDK examples in this section demonstrate each of the RRULE configuration options with the recurrence object.

Each option in the rrule array corresponds to a pattern. Options are separated in the RRULE string by semicolons (;). These examples show the relationship between patterns and RRULE formatting:

  • Occurs every two years: FREQ=YEARLY, INTERVAL=2
  • Occurs on Monday, Wednesday, and Friday: BYDAY=MO,WE,FR
  • Occurs in February, April, June, and September: BYMONTH=2,4,6,9
  • Occurs 75 times total: COUNT=75
  • Does not occur on November 20, 2021 at 5:20:47 GMT: "EXDATE:20211120T0420470000"

These examples show how you can use the rrule array to create a recurring event with each of the Nylas SDKs:

   "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 following sections cover various RRULE behaviors that you may experience with Nylas and other providers. This information is helpful to keep in mind when creating and changing recurring events.

Event changes or updates

Updating or deleting the main event in a recurrence schedule impacts all instances of the event. You can omit individual events using the EXDATE property.

expand_recurring parameter

When you retrieve events through the Nylas API, setting the expand_recurring parameter to true returns all instances of a recurring event. If you request events without the expand_recurring parameter, the Events endpoint returns only the master event if it falls within the requested time range.

Recurring events that have overrides (for example, changes to individual events) are returned separately. Setting expand_recurring to true doesn't impact how these events are returned. If expand_recurring isn't set, any cancellations are returned along with the master event. Cancelled events have their cancelled parameter set to true.

Recurring event defaults

Because RRULE formatting doesn't allow for changes to the event time, each instance of a recurring event occurs at the same time of day as the original. If you want to change the time that an individual event occurs, you can make a PUT request to the Events endpoint.

If BYDAY isn't included in the RRULE string for weekly events (those with FREQ=WEEKLY set), Nylas defaults to information from the master event's date and time values to set the recurrence schedule.

Provider support

This table compares how various providers support 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.
Changing the 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. They do update for overrides created through Microsoft's native calendar interface, however.
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

Microsoft accounts have a few additional limitations for recurring events.

If a recurring event has an associated EXDATE, you cannot recover or undo the removed occurrence. You must either create a new, separate event to represent a recovered EXDATE, or use other event properties like status to recover the occurrence. These options allow you to change the event information at another time.

Currently, Microsoft accounts don't support creating an event that occurs monthly on multiple days (for example, RRULE:FREQ=MONTHLY;BYDAY=1TH,3TH). The index property is on a monthly recurrence object, not the day-of-week object. Microsoft accounts don't support different indices.

Microsoft Exchange also 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 the previous instance. You cannot overlap recurring events. For more information, see Microsoft's official documentation.

Unsupported properties

Currently, Nylas doesn't support EXRULE and RDATE strings for API requests.

If you edit the EXDATE value after creating a recurring event, Nylas returns a 200 successful job, but doesn't remove or delete events. You must use the Delete An Event endpoint to remove individual events from a recurrence schedule.

What's next?

Video walkthrough

Prefer video? You can watch our Coding with Nylas livestream.

Resources

Here are some more resources covering RRULE and recurring events: