Only show these results:

Calendars and Events 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, and do not support EXRULE, RDATE, and TZID. 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. Set key5 to a specific string to mark events to consider when calculating a round robin order.

Microsoft Exchange Web Services is no longer supported.

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

  • Virtual calendars are no longer limited to one per account (now called a grant). You can now have 10 calendars per grant.
    • As in v2, you can create as many grants as you need, and you are billed per grant.
    • You can create calendars using the POST /v3/calendars endpoint.
  • You must provide an identifier when you create the Grant for virtual calendars. Previously, this was optional. This can be any arbitrary string, and no longer needs to be in email address format.
  • Virtual calendars use the new v3 Nylas Calendar and Events APIs, and all Calendar-related endpoint changes in v3 API also apply to virtual calendars.
  • Virtual calendars in v3 also allow you to specify a "primary" calendar. In virtual calendars, the primary calendar is the first calendar created for a grant, and it cannot be deleted. You can specify the word primary in place of a calendar_id.

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.