Version:
Only show these results:

Schedule recurring events

You can use the RRULE format to schedule recurring events. This page explains how to create recurring events, what to expect when using them, and how to use RRULE with the Nylas Events API.

ℹī¸ Recurring events edit is available for Free, Entry, Core, and Plus plans.

Create a recurring event

When you make a Create Event request, you can include the recurrence object to set a repeating schedule for the event. This is useful when setting weekly meetings or monthly events.

The recurrence array can include an RRULE string, which sets the recurrence schedule (for example, WEEKLY) and any EXDATE values, which set dates to be excluded from the schedule.

"recurrence": [
  "RRULE:FREQ=WEEKLY;BYDAY=MO",
  "EXDATE:20211011T000000Z"
]

Recurring events in Nylas do not support the EXRULE or RDATE parameters.

📝 If you don't specify a time zone for a recurring event, Nylas creates the event in UTC. Participants in other timezones receive the event invitation with the time zone listed, but participant calendars render the event in their local time zone.

When a calendar provider receives a create-event request from Nylas, it creates the events in the series at the specified intervals and times. All occurrences in the series have the same information, including the title, description, and other settings. They also share a master_event_id which the provider uses to identify events in the sequence.

Providers send event.created notifications for master events only, for each participant. This can still generate a lot of notifications.

Omit recurring event occurrences

To omit individual recurring event instances from a Return all events query's results, set the expand_recurring parameter to false. When set to false, Nylas only returns master events and any event overrides that occur in the time period you request.

Edit a recurring event

Recurring events behave differently depending on how you edit them. You can edit individual occurrences (similar to "Edit this event only"), part of a sequence (similar to "Edit this and following events"), or the entire sequence from start to end (similar to "Edit all events"). Each of these actions can have different results depending on the provider.

Edit a single occurrence

To edit a single occurrence in a sequence, delete the individual event occurrence and re-create it as a stand-alone event. Then, edit the original sequence's EXDATE to include the standalone event. You might see an event.deleted, event.created, and event.updated notification for each participant, or you might see two event.updated notifications, depending on how the provider treats the edit.

The standalone event might or might not keep the master_event_id from the original sequence, and might or might not receive content edits to the original title, description, or participants from the original master event. This behavior varies both by provider and the attributes you edited, so you might want to check the event after editing if this inheritance is important to your project.

When you update a single occurrence of an event series, Nylas sends only one event.updated notification for the master event. For convenience, Nylas adds the following arrays to the notification:

  • occurrences: A list of event IDs for affected event occurrences.
  • cancelled_occurrences: A list of event IDs for cancelled event occurrences.

The occurrences and cancelled_occurrences fields are supported by Google and Microsoft Graph accounts only.

⚠ī¸ You cannot change an event from recurring to non-recurring on iCloud accounts. You can only create, update, or delete recurring event information.

Edit part of a sequence

Often, you'll want to edit a sequence of events after a few occurrences have passed, when you find that the time, date, or frequency of the event doesn't work well for its intended purpose. This is the equivalent to editing an event in the provider UI and selecting "Edit this event and all following".

To edit part of a sequence, edit the original master event to end it before your chosen occurrence. Then, delete the edited event occurrence and all following events in the sequence, and create an event sequence with the new date and time, and a new master_event_id.

To edit a recurring event starting from the first event in the sequence, delete the whole original sequence and re-create it as a new sequence with a new master_event_id.

For each participant, you receive an event.updated notification for the original master event and an event.created notification for the new master event.

Edit a whole sequence

To change an entire sequence of events, including occurrences that have already passed, edit the master event only. You should receive an event.updated notification for each participant.

RRULE formatting syntax

RRULE uses a specific syntax for recurring events in calendars. The formatting described below is for the request body of an Events API request, or for the recurrence object in the Nylas SDKs.

Parameter Type Description
rrule array An array of RRULE and EXDATE strings. See RFC-5545 for more information.
timezone string An IANA time zone database-formatted string (for example, America/New_York).

The rrule parameter is an array of two strings. The first 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, the following array represents a sample recurring event.

rrule: ["RRULE: OPTIONS=VALUE;OPTIONS=VALUE", "EXDATE: 2023-01-31"], timezone: "America/New_York"

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. Only ISO 8601 are valid.

RRULE configuration options

The following table shows common options for RRULE configurations.

Option Values 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).

Events inherit their time zone from the when object. Nylas recommends that you use the when object to specify the start time and the end time.

For more information about RRULE standards, see the following documentation:

Each option in the rrule array corresponds to a pattern. 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"

Best practices

The following sections cover various RRULE behaviors that you might 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 edits all instances of the event. You can omit individual events using the EXDATE property.

Default settings for recurring events

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 an Update Event request.

If you don't include BYDAY 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

The table below 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 remaining 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. It does update for overrides created through Microsoft's native calendar interface.
Deleting a single occurrence from a series within the provider's native calendar UI. Google marks deleted occurrences as cancelled events and creates a hidden master event to track them. This master event has a different ID from the individual occurrences. The deleted occurrences aren't visible in the UI, but you can retrieve them by making a GET events request with the show_cancelled=true query parameter. Google doesn't reflect cancelled events in the EXDATE of the master event for the recurring series. Microsoft entirely removes the deleted occurrences from the system instead of marking them as cancelled. As a result, you can't retrieve them using the Nylas API. Microsoft doesn't reflect deleted occurrences in the EXDATE of the master event for the recurring series.
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.

Microsoft provider 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 separate event to represent a recovered EXDATE, or use the 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-the-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

If you edit the EXDATE value after creating a recurring event, Nylas returns a 200 response, but doesn't remove or delete events. You must make a Delete Event request to remove an individual event from a recurrence schedule.

Virtual calendars don't support DTSTART and TZID.

What's next?

Video walkthrough

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

Resources

The following documentation covers RRULE and recurring events:

The rrule.js demo repository is a demo Javascript library. This is a comprehensive reference for RRULE options, as well as input and output descriptions.