Events

Events represent scheduled items on a calendar. The Nylas Events API uses the same commands to manage events across providers, and can refer to specific events using the provider's event_id parameter. Events can be public, private, or shared among a group of users. They might include details like participants, locations, and timing, along with other information.

The Events API includes the Send RSVP endpoint, which allows you to send RSVPs directly from your Nylas application, even for participants who might not have access to edit a specific event.

Metadata on events

You can add metadata to new and existing events by including the metadata sub-object in your POST, PUT, or PATCH request. For more information, see the Metadata documentation.

Agent Account grants support metadata on events, with the same 50-pair limit and the same five indexed reserved keys as connected grants.

Agent Account events

When you need to host events for a user or resource that has no account on a provider (for example, an external contractor, a meeting room, or an AI agent), create an Agent Account. All of the Events endpoints work on an Agent Account grant. Because the account is a real mailbox, creating an event with notify_participants=true sends an invitation to each participant, updates and cancellations reach every attendee's calendar, and the Send RSVP endpoint answers invitations the account receives.

Events scopes

The table below lists the Events endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.

The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.

For more information about scopes, see Using scopes to request user data.

Events notifications

You can subscribe to the following notification triggers so Nylas notifies you about changes to your users' event data:

• event.created
• event.updated
• event.deleted

These are separate from the event reminders which you might send to your users. For more information, see the Event webhook notification schemas.

Microsoft event considerations

Microsoft Outlook events are often shared across all calendars in a user's account. If the user creates an event on one of their calendars, you can retrieve it using another calendar ID from their grant.

iCloud query considerations

If you're searching for an event within a certain time range on an iCloud account, the difference between start and end can't be greater than six months. If you include a time range greater than six months, Nylas returns an "Invalid request" error similar to the following example.

"error": {
  "type": "invalid_request_error",
  "message": "The maximum time range for iCloud event queries is 6 months."
}

For more information about searching for events, see Searching with Nylas.