Schedule recurring events in Nylas v2
You can use the RRULE
format to schedule recurring events with Nylas. This page explains how to create recurring events, what to expect when using them, and how to use RRULE
with the Events API.
Create a recurring event
When you create a new event using the Nylas Events endpoint, you can include the recurrence
object to set a repeating schedule for the event. This is useful for scheduling weekly meetings or monthly dinners.
The recurrence
object can include the RRULE
string, which sets the recurrence schedule (for example, WEEKLY
), and any EXDATE
values, which set dates to be excluded from the schedule. Recurring events in Nylas do not support the EXRULE
or RDATE
parameters.
"recurrence": {
"rrule": ["RRULE:FREQ=WEEKLY;BYDAY=MO"],
"timezone": "America/New_York"
}
đ If you don't specify a timezone for a recurring event, Nylas uses the time zone of the event owner's calendar. Participants in other time zones receive the event invitation with the owner's time zone listed, but participant calendars render the event in their local time zone.
When the calendar provider receives the 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.
The provider also sends an event.created
notification for the master event only, but for each participant. That can be a lot of webhooks.
Retrieve events in a recurring sequence
To find all of the events in a recurring sequence, make a GET /events
request and set the expand_recurring
query parameter to true
. You should also add another query parameter that includes any information you know about the sequence, such as the event title.
Edit recurring events
Recurring events behave differently depending on how you edit them. You can edit individual occurrences of the event (similar to "Edit this event only"), you can edit all events in the sequence starting from somewhere in the sequence (similar to "Edit this and following events"), and you can edit 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 exclude 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 event title, description, or participants from the original master event. This behavior varies both by provider and which attributes you edited, so you might want to check the event after editing if this inheritance is important to your project.
â ī¸ 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 equivalent to editing an event in the provider GUI and selecting "Edit this event and all following".
To edit part of a sequence, edit the original master event to end it before the edited occurrence. Then, delete the edited event occurrence and all following events in the sequence, and create a new 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 in both cases, you get 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 the master event 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 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, 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 values are valid in this array.
RRULE
configuration options
This table shows common options for RRULE
configurations:
Option | Value | Description |
---|---|---|
DTSTART |
<Date> or <Date-Time> |
The start date or time of the recurrence. |
UNTIL |
<Date> or <Date-Time> |
The end date or time of the recurrence. UNTIL must have the same value type as DTSTART . |
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). |
For more information on RRULE
standards, see the links in the What's next? section.
The following SDK examples 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 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 impacts all instances of the event. You can omit or "exclude" individual events using the EXDATE
property.
The Expand Recurring parameter
When you retrieve events using the Nylas Events API, you can set the expand_recurring
parameter to true
to include individual occurrences of a recurring event, or set it to false
to omit them. If you request events and expand_recurring
is false
, the Events endpoint returns only the master
events that fall within the requested time range. In v2.x expand_recurring
defaults to false
.
Recurring events that have overrides (for example, changes to individual events) are returned separately. Setting expand_recurring
to true
doesn't change how these events return. 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
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 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. |
Nylas no longer returns the event occurrence. |
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 Event endpoint to remove individual events from a recurrence schedule.
What's next?
- Read more about
RRULE
in calendar events on the Nylas blog. - Read more about how to create recurring events using
RRULE
on the Nylas blog. - Browse the v2 Events API reference documentation.
Video walkthrough
Prefer video? You can watch our Coding with Nylas livestream.
Resources
Here are some more resources covering RRULE
and recurring events:
The following is a demo Javascript library. This is a comprehensive reference for RRULE options as well as input and output descriptions.