# Events

Source: https://developer.nylas.com/docs/reference/api/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](/docs/reference/api/events/send-rsvp/), 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](/docs/dev-guide/metadata/).

## Virtual calendars

Nylas allows you to create virtual calendars for users and resources that might not have calendars on your providers (for example, external contractors or meeting rooms). You can use the Nylas Calendar and Events APIs with the virtual accounts that power virtual calendars, just like you would any other account. Virtual accounts don't provide email or contacts features, so you can't use them with the Email or Contacts APIs.

For more information, see [Using virtual calendars](/docs/v3/calendar/virtual-calendars/).

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

| Endpoint                                                                                                                            | Google Scopes</br>`https://www.googleapis.com/auth/...`                                                                               | Microsoft Scopes</br>`https://graph.microsoft.com/...` |
| :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------- |
| **GET** `/events`</br>**GET** `/events/<EVENT_ID>`                                                                                  | `/calendar.events.readonly` ☑️</br>`/calendar.events`</br>`/calendar` (Required to use `primary` keyword when referencing calendars.) | `Calendars.Read` ☑️</br>`Calendars.ReadWrite`          |
| **POST** `/events`</br>**PUT** `/events/<EVENT_ID>`</br>**DELETE** `/events/<EVENT_ID>`</br>**POST** `/events/<EVENT_ID>/send-rsvp` | `/calendar.events` ☑️</br>`/calendar` (Required to use `primary` keyword when referencing calendars.)                                 | `Calendars.ReadWrite` ☑️                               |

For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).

## 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](/docs/reference/notifications/#event-notifications).

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

```json
"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](/docs/dev-guide/best-practices/search/#search-for-events).


## Endpoints

- **GET** `/v3/grants/{grant_id}/events` - [Return all events](https://developer.nylas.com/docs/reference/api/events/get-all-events/)
- **POST** `/v3/grants/{grant_id}/events` - [Create an event](https://developer.nylas.com/docs/reference/api/events/create-event/)
- **GET** `/v3/grants/{grant_id}/events/import` - [Import events](https://developer.nylas.com/docs/reference/api/events/import-events/)
- **GET** `/v3/grants/{grant_id}/events/{event_id}` - [Return an event](https://developer.nylas.com/docs/reference/api/events/get-events-id/)
- **PUT** `/v3/grants/{grant_id}/events/{event_id}` - [Update an event](https://developer.nylas.com/docs/reference/api/events/put-events-id/)
- **DELETE** `/v3/grants/{grant_id}/events/{event_id}` - [Delete an event](https://developer.nylas.com/docs/reference/api/events/delete-events-id/)
- **POST** `/v3/grants/{grant_id}/events/{event_id}/send-rsvp` - [Send RSVP](https://developer.nylas.com/docs/reference/api/events/send-rsvp/)