Only show these results:
public-beta-v3

Calendars and Events in Nylas API v3

The Nylas API v3 is in public beta. It might contain bugs, and might change before it is generally available. See the v3 Beta documentation for more information.

This page lists and explains the changes to Calendar and Events APIs between Nylas v2.7 and v3.

Calendar and Events changes

The API v3 Beta 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.

By default, Events are no longer returned in any particular order. You can include the order_by=start query parameter to order returned Events by start time. This will make your queries match the API v2.7 behavior.

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 as well. In v3, timezone information uses an array of RRULE and EXDATE strings. With this change, EXRULE, RDATE, and TZID are no longer supported. The timezone is now inherited from the when object's timezone. DTSTART and DTEND are also no longer supported; instead, use the start and end times set in the when object. For more information, see RFC-5545.

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.

Calendar endpoint changes

  • 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.

Events endpoint changes

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.