Only show these results:

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.

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.