# Changes to Calendar and Events APIs in Nylas v3 Source: https://developer.nylas.com/docs/new/in-v3/calendar-changes/ This page lists and explains the changes to Calendar and Events APIs between Nylas v2.7 and v3. ## Changes to Calendar and Events in v3 Nylas v3 includes the same basic ability to create, read, update, and delete both Events and Calendars (which contain Events). It also includes the new ability to list all Events and Calendars for a specific account, and the new [Send RSVP endpoint](/docs/reference/api/events/send-rsvp/) allows users to set participant statuses for a given Event. The `calendar_id` is now a required query parameter for most `/events` endpoints. This means that you can no longer list all Events from all Calendars, and you must be able to identify which Calendar an Event is associated with in order to retrieve, update, or delete it (you can set the `calendar_id` to the user's email address, or set it to `default` to select the default or main Calendar for the user on the service provider). The requirements for Event start and end times have also been changed. The `starts_before`, `starts_after`, `ends_before`, and `ends_after` parameters have been simplified to only two variables: `start` and `end`. `start` is equivalent to `ends_after` and `end` is equivalent to `starts_before`. When you use either in a query, an Event is returned if any part of it occurs between the `start` and `end` times. The timezone format for recurring events has been updated. In v3, recurring events use an array of `RRULE` and `EXDATE` strings. The time zone is now inherited from the `when` object. Nylas recommends that you use the `when` object to set the start time and the end time, instead of the Recurrence array. For more information, see the [Create an Event references](/docs/reference/api/events/create-event/) and [RFC-5545](https://tools.ietf.org/html/rfc5545#section-3.8.5). Nylas v3 doesn't include an "Emailed Events" calendar for IMAP accounts. Finally, round-robin has been updated. It now uses the value of the Nylas `key5` metadata to indicate Events to consider when calculating the next available time amongst group members. Set `key5` to a specific string to mark events to consider when calculating a round robin order. Calendar and event support is now available for iCloud using the iCloud connector, and Exchange on-prem using the EWS connector. ## Changes to Calendar endpoints in v3 - Added `is_owned_by_user` property, available on all Calendar calls. - Added `hex_color` Calendar property, available for Microsoft and Google calendars on all calls. - Added access to shared calendars using the `GET` endpoint, for Microsoft only. - You can no longer use a `free_busy` object to override or add busy data to an Availability request. - The `time_slots` and `tentative_busy` parameters for Availability requests have been removed. - The `POST /calendars/availability/consecutive` endpoint has been deprecated. ### Changes to Availability requests The [Consecutive Availability](/docs/api/v2/#post-/calendars/availability/consecutive) (Availability for multiple meetings) endpoint is deprecated. The `time_slots` and `tentative_busy` parameters of availability requests have also been removed. You can no longer use a `free_busy` object to override or add busy data to an Availability request. The way you specify Open Hours (working hours) has changed. In v2, you specified a top-level object for each participant with this information. In v3, you add a `default_open_hours` object in the `availability_rules` object, and you can override that default by specifying a different availability for each participant. Round-robin availability now uses the value of the Nylas `key5` metadata to indicate Events to consider when calculating the next available time among group members. Use this key to mark events to include in this calculation. ## Changes to Events endpoints in v3 The following properties are new: - `calendar_id` is now required on all Events calls. - Added `order_by` query parameter in `GET` calls. - Added `html_link` property in `GET` calls. - Added `capacity` property in all Events calls. The following properties have been deprecated: - `event_id` query parameter in `GET` calls. - `updated_at_before` in `GET` calls. - `updated_at_before` in `GET` calls. - `participants query parameter` in `GET` calls. - `customer_event_id` query parameter and property in all calls. - `notifications property` in `POST` and `PUT` calls. - `original_start_time property` in `GET` calls. - `organizer_email property`in `GET` calls. - `organizer_name property`in `GET` calls. - `owner property is`in `GET` calls. - `message_id` in `GET` calls. - `event.recurrence.timezone` in `GET` calls. The following properties have been changed in v3: - The new `start` and `end` replace all date bracketing query parameters (for example, `starts_after`, `ends_after`, `starts_before`, `ends_before`) in `GET` calls. - Events are now unordered, unless you apply the `order_by` query parameter in `GET` calls. - Dates within `RRULE` no longer need `Z` at the end in `POST` and `PUT` calls. ## Changes to virtual calendars in v3 - You can now have up to 10 virtual calendars per account (now called a "grant"). - As in v2, you can create as many grants as you need. Nylas bills you for each grant. - You can create virtual calendars using the [`POST /v3/grants//calendars` endpoint](/docs/api/v3/ecc/#post-/v3/grants/-grant_id-/calendars). - You must provide an identifier when you create a virtual calendar grant. Previously, this was optional. The identifier can be any arbitrary string, and no longer needs to be in email address format. - Virtual calendars use the new v3 Calendar and Events APIs, and all Calendar-related endpoint changes also apply to virtual calendars. - Virtual calendars in v3 allow you to specify a "primary" calendar. - For virtual calendars, the `primary` calendar is the first one created for a grant, and you can't delete it. - You can specify `primary` in place of a `calendar_id` in calls to the Nylas APIs. For a complete list of changes, see the [v3 diff view](/docs/v2/upgrade-to-v3/diff-view/#changes-to-calendars-and-events-in-v3). ## Changes to RSVPs in v3 Although RSVPs largely function the same as in the private-preview version available in v2, a few things things have changed in v3: - The API is more stable and reliable. - The endpoint has changed from `/send-rsvp` to `/v3/grants//events//send-rsvp`. - You now need to pass only the RSVP status in your `POST` requests.