Version:
Only show these results:

Changes to Calendar and Events APIs in Nylas v3

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 Event RSVP endpoint 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 reference documentation and RFC-5545.

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 (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 propertyin GET calls.
  • organizer_name propertyin GET calls.
  • owner property isin 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").
  • 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.

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/<grant_id>/events/<event_id>/send-rsvp.
  • You now need to pass only the RSVP status in your POST requests.