# Using the Events API

Source: https://developer.nylas.com/docs/v3/calendar/using-the-events-api/

The Nylas Events API gives your application a secure, reliable connection to the events on your users' calendars. It provides a REST interface that lets you create, update, and delete events.

## How the Events API works

Every user who authenticates with your Nylas application can have zero, one, or multiple calendars, all of which serve as containers for Event objects.

Event objects are containers for information about scheduled events. This includes a list of the people involved, details about the time, meeting location (in-person address or virtual conferencing details), and a description. They can also include `.ics` files and other attachments, and information about who has confirmed their attendance.

In most cases, you make requests to the Availability endpoints ([Get Availability](/docs/reference/api/calendar/post-availability/) or [Get Free/Busy Schedule](/docs/reference/api/calendar/post-calendars-free-busy/)) _before_ you make requests to the Event endpoints, to ensure the time for an event you want to book is available.

### Conferencing details

The Nylas Events API includes both the ability to read conferencing details from an event, and create conferences as you create events. See [Manually add conferencing to an event](/docs/v3/calendar/add-conferencing/#manually-add-conferencing-to-an-event) for more information.

## Before you begin


To follow along with the samples on this page, you first need to [sign up for a Nylas developer account](https://dashboard-v3.nylas.com/register?utm_source=docs&utm_medium=devrel-surfaces&utm_campaign=&utm_content=using-apis), which gets you a free Nylas application and API key.

For a guided introduction, you can follow the [Getting started guide](/docs/v3/getting-started/) to set up a Nylas account and Sandbox application. When you have those, you can connect an account from a calendar provider (such as Google, Microsoft, or iCloud) and use your API key with the sample API calls on this page to access that account's data.


## Get a list of events

To return a list of events from a user's calendar, make a [Get all Events request](/docs/reference/api/events/get-all-events/) that includes the specific calendar ID.

```bash
curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'
```

```json [getEvents-Response (JSON)]

{
  "request_id": "cbd60372-df33-41d3-b203-169ad5e3AAAA",
  "data": [
    {
      "busy": true,
      "calendar_id": "primary",
      "conferencing": {
        "details": {
          "meeting_code": "ist-****-tcz",
          "url": "https://meet.google.com/ist-****-tcz"
        },
        "provider": "Google Meet"
      },
      "created_at": 1701974804,
      "creator": {
        "email": "anna.molly@example.com",
        "name": ""
      },
      "description": null,
      "grant_id": "1e3288f6-124e-405d-a13a-635a2ee54eb2",
      "hide_participants": false,
      "html_link": "https://www.google.com/calendar/event?eid=NmE0dXIwabQAAAA",
      "ical_uid": "6aaaaaaame8kpgcid6hvd0q@google.com",
      "id": "6aaaaaaame8kpgcid6hvd",
      "object": "event",
      "organizer": {
        "email": "anna.molly@example.com",
        "name": ""
      },
      "participants": [
        {
          "email": "jenna.doe@example.com",
          "status": "yes"
        },
        {
          "email": "anna.molly@example.com",
          "status": "yes"
        }
      ],
      "read_only": true,
      "reminders": {
        "overrides": null,
        "use_default": true
      },
      "status": "confirmed",
      "title": "Holiday check in",
      "updated_at": 1701974915,
      "when": {
        "end_time": 1701978300,
        "end_timezone": "America/Los_Angeles",
        "object": "timespan",
        "start_time": 1701977400,
        "start_timezone": "America/Los_Angeles"
      }
    }
  ]
}


```

```js [getEvents-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function fetchAllEventsFromCalendar() {
  try {
    const events = await nylas.events.list({
      identifier: "<NYLAS_GRANT_ID>",
      queryParams: {
        calendarId: "<CALENDAR_ID>",
      },
    });

    console.log("Events:", events);
  } catch (error) {
    console.error("Error fetching calendars:", error);
  }
}

fetchAllEventsFromCalendar();


```

```python [getEvents-Python SDK]

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"

events = nylas.events.list(
    grant_id,
    query_params={
      "calendar_id": "<CALENDAR_ID>"
    }
)

print(events)

```

```ruby [getEvents-Ruby SDK]

require 'nylas'

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

query_params = {
	calendar_id: "<CALENDAR_ID>"
}

# Read events from our main calendar in the specified date and time
events, _request_ids = nylas.events.list(identifier: "<NYLAS_GRANT_ID>", query_params: query_params)

events.each {|event|
	case event[:when][:object]
		when 'timespan'
			start_time = Time.at(event[:when][:start_time]).strftime("%d/%m/%Y at %H:%M:%S")
			end_time = Time.at(event[:when][:end_time]).strftime("%d/%m/%Y at %H:%M:%S")
			event_date = "The time of the event is from: #{start_time} to #{end_time}"
		when 'datespan'
			start_time = event[:when][:start_date]
			end_time = event[:when][:end_date]
			event_date = "The date of the event is from: #{start_time} to: #{end_time}"
		when 'date'
			start_time = event[:when][:date]
			event_date = "The date of the event is: #{start_time}"
		end
		event[:participants].each {|participant|
			participant_details += "Email: #{participant[:email]} " \
			"Name: #{participant[:name]} Status: #{participant[:status]} - "
		}
		print "Id: #{event[:id]} | Title: #{event[:title]} | #{event_date} | " 
		puts "Participants: #{participant_details.chomp(' - ')}"
		puts "\n"
}

```

```java [getEvents-Java SDK]

import com.nylas.NylasClient;
import com.nylas.models.When;

import com.nylas.models.*;
import java.text.SimpleDateFormat;
import java.util.List;
import java.util.Objects;

public class read_calendar_events {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    // Build the query parameters to filter our the results
    ListEventQueryParams listEventQueryParams = new ListEventQueryParams.Builder("<CALENDAR_ID>").build();

    // Read the events from our main calendar
    List<Event> events = nylas.events().list("<NYLAS_GRANT_ID>", listEventQueryParams).getData();

    for (Event event : events) {
      System.out.print("Id: " + event.getId() + " | ");
      System.out.print("Title: " + event.getTitle());

      // Dates are handled differently depending on the event type
      switch (Objects.requireNonNull(event.getWhen().getObject()).getValue()) {
        case "datespan" -> {
          When.Datespan date = (When.Datespan) event.getWhen();

          System.out.print(" | The date of the event is from: " + 
              date.getStartDate() + " to " + 
              date.getEndDate());
        }
        case "date" -> {
          When.Date date = (When.Date) event.getWhen();
          
          System.out.print(" | The date of the event is: " +date.getDate());
        }
        case "timespan" -> {
          When.Timespan timespan = (When.Timespan) event.getWhen();

          String initDate = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").
          format(new java.util.Date((timespan.getStartTime() * 1000L)));

          String endDate = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").
          format(new java.util.Date((timespan.getEndTime() * 1000L)));

          System.out.print(" | The time of the event is from: " + 
          initDate + " to " + endDate);
        }
      }

      System.out.print(" | Participants: ");

      for(Participant participant : event.getParticipants()){
        System.out.print(" Email: " + participant.getEmail() +
            " Name: " + participant.getName() +
            " Status: " + participant.getStatus());
      }

      System.out.println("\n");
    }
  }
}

```

```kt [getEvents-Kotlin SDK]

import com.nylas.NylasClient
import com.nylas.models.*

import java.util.*

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")

  val eventquery: ListEventQueryParams = ListEventQueryParams(calendarId = "<CALENDAR_ID>")

  // Get a list of events
  val myevents: List<Event> = nylas.events().list(
      "<NYLAS_GRANT_ID>", 
      queryParams = eventquery).data

  // Loop through the events
  for(event in myevents){
    print("Id: " + event.id + " | ");
    print("Title: " + event.title);

    // Get the details of Date and Time of each event.
    when(event.getWhen().getObject().toString()) {
      "DATE" -> {
        val datespan = event.getWhen() as When.Date

        print(" | The date of the event is: " + datespan.date);
      }
      "DATESPAN" -> {
        val datespan = event.getWhen() as When.Datespan

        print(" | The date of the event is: " + datespan.startDate);
      }
      "TIMESPAN" -> {
        val timespan = event.getWhen() as When.Timespan
        val startDate = Date(timespan.startTime.toLong() * 1000)
        val endDate = Date(timespan.endTime.toLong() * 1000)

        print(" | The time of the event is from: $startDate to $endDate");
      }
    }

    print(" | Participants: ");

    // Get a list of the event participants
    val participants = event.participants

    // Loop through and print their email, name and status
    for(participant in participants) {
      print(" Email: " + participant.email + " Name: " + participant.name +
          " Status: " + participant.status)
    }
    
    println("\n")
  }
}

```

```bash
nylas calendar events list
```


> **Info:** 
> **The [Nylas CLI](https://cli.nylas.com/) runs commands against your default grant.** Run [`nylas auth list`](https://cli.nylas.com/docs/commands/auth-list) to see your connected accounts and [`nylas auth switch <email>`](https://cli.nylas.com/docs/commands/auth-switch) to change which one commands run against. See the full [command reference](https://cli.nylas.com/docs/commands).


By default, Nylas returns a list of 50 Event objects.

The results are sorted by the start date and time, beginning with the oldest event. If you use `master_event_id` to fetch recurring events with a Google grant, the order of the results is not guaranteed.

If you know the ID for a specific event, you can make a [Get Event request](/docs/reference/api/events/get-events-id/) to fetch it instead.

### Filter a list of events

You can add query parameters to a `GET` request to filter the events that Nylas returns. For example, you can filter to return only events from a single calendar. The following code snippet uses several query parameters to filter events.

```bash
curl --compressed --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>&start=<TIMESTAMP>&end=<TIMESTAMP>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

```

```json [filterEvents-Response (JSON)]

{
  "request_id": "cbd60372-df33-41d3-b203-169ad5e3AAAA",
  "data": [
    {
      "busy": true,
      "calendar_id": "primary",
      "conferencing": {
        "details": {
          "meeting_code": "ist-****-tcz",
          "url": "https://meet.google.com/ist-****-tcz"
        },
        "provider": "Google Meet"
      },
      "created_at": 1701974804,
      "creator": {
        "email": "anna.molly@example.com",
        "name": ""
      },
      "description": null,
      "grant_id": "1e3288f6-124e-405d-a13a-635a2ee54eb2",
      "hide_participants": false,
      "html_link": "https://www.google.com/calendar/event?eid=NmE0dXIwabQAAAA",
      "ical_uid": "6aaaaaaame8kpgcid6hvd0q@google.com",
      "id": "6aaaaaaame8kpgcid6hvd",
      "object": "event",
      "organizer": {
        "email": "anna.molly@example.com",
        "name": ""
      },
      "participants": [
        {
          "email": "jenna.doe@example.com",
          "status": "yes"
        },
        {
          "email": "anna.molly@example.com",
          "status": "yes"
        }
      ],
      "read_only": true,
      "reminders": {
        "overrides": null,
        "use_default": true
      },
      "status": "confirmed",
      "title": "Holiday check in",
      "updated_at": 1701974915,
      "when": {
        "end_time": 1701978300,
        "end_timezone": "America/Los_Angeles",
        "object": "timespan",
        "start_time": 1701977400,
        "start_timezone": "America/Los_Angeles"
      }
    }
  ]
}


```

```js [filterEvents-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function fetchAllEventsFromCalendar() {
  try {
    const events = await nylas.events.list({
      identifier: "<NYLAS_GRANT_ID>",
      queryParams: {
        calendarId: "<CALENDAR_ID>",
      },
    });

    console.log("Events:", events);
  } catch (error) {
    console.error("Error fetching calendars:", error);
  }
}

fetchAllEventsFromCalendar();


```

### All-day event handling

When Nylas returns an all-day event (`datespan`) from Google and Microsoft calendars, the end date is set to the day _after_ the event ends. This is due to how Google and Microsoft handle all-day events. To display the correct number of days for all-day events, make sure that you subtract a day.

For example, an event scheduled for December 1st will have an end date of December 2nd.

```json [all_day-Nylas response]
{
  ...
  "data": [{
    ...
    "when": {
      "start_date": "2024-12-01",
      "end_date": "2024-12-02",
      "object": "datespan"
    }
  }]
}
```

```json [all_day-Google response]
{
  "start": {
    "date": "2024-12-01"
  },
  "end": {
    "date": "2024-12-02"
  }
}
```

```json [all_day-Microsoft response]
{
  "start": {
    "dateTime": "2024-12-01T00:00:00.0000000"
  },
  "end": {
    "dateTime": "2024-12-02T00:00:00.0000000"
  }
}
```

## Create an event

The code samples below show how to create an event — in this case, a New Year's Eve party in a specific room at the Ritz Carlton.

```bash
curl --compressed --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Annual Philosophy Club Meeting",
    "busy": true,
    "conferencing": {
        "provider": "Zoom Meeting",
        "autocreate": {
          "conf_grant_id": "<NYLAS_GRANT_ID>",
          "conf_settings": {
            "settings": {
              "join_before_host": true,
              "waiting_room": false,
              "mute_upon_entry": false,
              "auto_recording": "none"
            }
          }
        }
      },
    "participants": [
      {
        "name": "Leyah Miller",
        "email": "leyah@example.com"
      },
      {
        "name": "Nyla",
        "email": "nyla@example.com"
      }
    ],
    "resources": [{
      "name": "Conference room",
      "email": "conference-room@example.com"
    }],
    "description": "Come ready to talk philosophy!",
    "when": {
      "start_time": 1674604800,
      "end_time": 1722382420,
      "start_timezone": "America/New_York",
      "end_timezone": "America/New_York"
    },
    "location": "New York Public Library, Cave room",
    "recurrence": [
      "RRULE:FREQ=WEEKLY;BYDAY=MO",
      "EXDATE:20211011T000000Z"
  ],
}'

```

```json [createEvent-Response (JSON)]

{
  "request_id": "1",
  "data": {
    "busy": true,
    "calendar_id": "primary",
    "conferencing": {
      "details": {
        "meeting_code": "<MEETING_CODE>",
        "url": "<MEETING_URL>"
      },
      "provider": "Google Meet"
    },
    "created_at": 1701974804,
    "creator": {
      "email": "leyah@example.com",
      "name": "Leyah Miller"
    },
    "description": null,
    "grant_id": "<NYLAS_GRANT_ID>",
    "hide_participants": false,
    "html_link": "<EVENT_LINK>",
    "ical_uid": "6aaaaaaame8kpgcid6hvd0q@google.com",
    "id": "<NYLAS_EVENT_ID>",
    "object": "event",
    "organizer": {
      "email": "leyah@example.com",
      "name": "Leyah Miller"
    },
    "participants": [
      {
        "email": "jenna.doe@example.com",
        "status": "yes"
      },
      {
        "email": "leyah@example.com",
        "status": "yes"
      }
    ],
    "read_only": true,
    "reminders": {
      "overrides": null,
      "use_default": true
    },
    "status": "confirmed",
    "title": "Holiday check in",
    "updated_at": 1701974915,
    "when": {
      "end_time": 1701978300,
      "end_timezone": "America/Los_Angeles",
      "object": "timespan",
      "start_time": 1701977400,
      "start_timezone": "America/Los_Angeles"
    }
  }
}


```

```js [createEvent-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

const now = Math.floor(Date.now() / 1000); // Time in Unix timestamp format (in seconds)

async function createAnEvent() {
  try {
    const event = await nylas.events.create({
      identifier: "<NYLAS_GRANT_ID>",
      requestBody: {
        title: "Build With Nylas",
        when: {
          startTime: now,
          endTime: now + 3600,
        },
      },
      queryParams: {
        calendarId: "<CALENDAR_ID>",
      },
    });

    console.log("Event:", event);
  } catch (error) {
    console.error("Error creating event:", error);
  }
}

createAnEvent();


```

```python [createEvent-Python SDK]

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"

events = nylas.events.create(
  grant_id,
  request_body={
    "title": 'Build With Nylas',
    "when": {
      "start_time": 1609372800,
      "end_time": 1609376400
    },
  },
  query_params={
    "calendar_id": "<CALENDAR_ID>"
  }
)

print(events)

```

```ruby [createEvent-Ruby SDK]

require 'nylas'
require 'date'

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

query_params = {
  calendar_id: "<CALENDAR_ID>"
}

today = Date.today
start_time = Time.local(today.year, today.month, today.day, 13, 0, 0).to_i
end_time = Time.local(today.year, today.month, today.day, 13, 30, 0).to_i

request_body = {
  when: {
    start_time: start_time,
    end_time: end_time
  },
  title: "Let's learn some Nylas Ruby SDK!",
  location: "Nylas' Headquarters",
  description: "Using the Nylas API with the Ruby SDK is easy.",
  participants: [{
    name: "Blag",
    email: "atejada@gmail.com",
    status: 'noreply'
  }]
}

event, _request_id = nylas.events.create(
  identifier: "<NYLAS_GRANT_ID>",
  query_params: query_params,
  request_body: request_body
)

puts event


```

```java [createEvent-Java SDK]

import com.nylas.NylasClient;
import com.nylas.models.*;

import java.time.Instant;
import java.time.LocalDate;
import java.time.ZoneOffset;
import java.time.temporal.ChronoUnit;
import java.util.*;

public class create_calendar_events {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    // Get today's date
    LocalDate today = LocalDate.now();

    // Set time. Because we're using UTC we need to add the hours in difference from our own timezone.
    Instant sixPmUtc = today.atTime(13, 0).toInstant(ZoneOffset.UTC);

    // Set the date and time for the event. We add 30 minutes to the starting time.
    Instant sixPmUtcPlus = sixPmUtc.plus(30, ChronoUnit.MINUTES);

    // Get the Date and Time as a Unix timestamp
    long startTime = sixPmUtc.getEpochSecond();
    long endTime = sixPmUtcPlus.getEpochSecond();

    // Define title, location, and description of the event
    String title = "Let's learn some about the Nylas Java SDK!";
    String location = "Nylas Headquarters";
    String description = "Using the Nylas API with the Java SDK is easy.";

    // Create the timespan for the event
    CreateEventRequest.When.Timespan timespan = new CreateEventRequest.
        When.Timespan.
        Builder(Math.toIntExact(startTime), Math.toIntExact(endTime)).
        build();

    // Create the list of participants.
    List<CreateEventRequest.Participant> participants_list = new ArrayList<>();

    participants_list.add(new CreateEventRequest.
        Participant("johndoe@example.com", ParticipantStatus.NOREPLY,
        "John Doe", "", ""));

    // Build the event details.
    CreateEventRequest createEventRequest = new CreateEventRequest.Builder(timespan)
        .participants(participants_list)
        .title(title)
        .location(location)
        .description(description)
        .build();

    // Build the event parameters. In this case, the Calendar ID.
    CreateEventQueryParams createEventQueryParams = new CreateEventQueryParams.Builder("<CALENDAR_ID>").build();

    // Create the event itself
    Event event = nylas.events().create(
        "<NYLAS_GRANT_ID>",
        createEventRequest,
        createEventQueryParams).getData();
  }
}

```

```kt [createEvent-Kotlin SDK]

import com.nylas.NylasClient
import com.nylas.models.*

import java.time.LocalDateTime
import java.time.ZoneOffset

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  var startDate = LocalDateTime.now()

  // Set the time. Because we're using UTC, we need to add the difference in hours from our own timezone.
  startDate = startDate.withHour(13);
  startDate = startDate.withMinute(0);
  startDate = startDate.withSecond(0);
  val endDate = startDate.withMinute(30);

  // Convert the dates from Unix timestamp format to integer.
  val iStartDate: Int = startDate.toEpochSecond(ZoneOffset.UTC).toInt()
  val iEndDate: Int = endDate.toEpochSecond(ZoneOffset.UTC).toInt()

  // Create the timespan for the event.
  val eventWhenObj: CreateEventRequest.When = CreateEventRequest.When.
  Timespan(iStartDate, iEndDate);

  // Define the title, location, and description of the event.
  val title: String = "Let's learn about the Nylas Kotlin/Java SDK!"
  val location: String = "Blag's Den!"
  val description: String = "Using the Nylas API with the Kotlin/Java SDK is easy."

  // Create the list of participants.
  val participants: List<CreateEventRequest.Participant> = listOf(CreateEventRequest.
      Participant("<PARTICIPANT_EMAIL>", ParticipantStatus.NOREPLY, "<PARTICIPANT_NAME>"))

  // Create the event request. This adds date/time, title, location, description, and participants.
  val eventRequest: CreateEventRequest = CreateEventRequest(eventWhenObj, title, location, description, participants)

  // Set the event parameters.
  val eventQueryParams: CreateEventQueryParams = CreateEventQueryParams("<CALENDAR_ID>")

  val event: Response<Event> = nylas.events().create("<NYLAS_GRANT_ID>",
      eventRequest, eventQueryParams)
}

```

```bash
nylas calendar events create \
  --title "New Year's Eve Party" \
  --start "2026-12-31 9:00pm" \
  --end "2026-12-31 11:59pm"
```

The CLI creates the event with the core time and title fields. To set a description, location, or other rich fields, send a full [Create Event request](/docs/reference/api/events/create-event/) or update the event afterwards.

Nylas' response includes an `id` for the new event.

## Modify an event and send an email invitation

You can now modify the event from the [previous step](#create-an-event) to add a participant for the New Year's Eve party and send an invitation.

> **Error:** 
> **You're about to send a real event invite!** The following samples send an email from the account you connected to the Nylas API to any email addresses you put in the `participants` sub-object. Make sure you actually want to send this invite to those addresses before running this command!

```bash
curl --compressed --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Birthday Party",
    "busy": true,
    "participants": [{
      "name": "Leyah Miller",
      "email": "leyah@example.com",
      "comment": "Might be late."
    }],
    "resources": [{
      "name": "Conference room",
      "email": "conference-room@example.com"
    }],
    "description": "Come ready to skate",
    "when": {
      "start_time": 1406887200,
      "end_time": 1417435200,
      "start_timezone": "America/New_York",
      "end_timezone": "America/New_York"
    },
    "location": "Roller Rink",
    "recurrence": [
      "RRULE:FREQ=WEEKLY;BYDAY=MO",
      "EXDATE:20211011T000000Z"
    ],
    "conferencing": {
        "provider": "Zoom Meeting",
        "autocreate": {
          "conf_grant_id": "<NYLAS_GRANT_ID>",
          "conf_settings": {
            "settings": {
              "join_before_host": true,
              "waiting_room": false,
              "mute_upon_entry": false,
              "auto_recording": "none"
            }
          }
        }
      },
    "reminder_minutes": "[20]",
    "reminder_method": "popup"
}'

```

```json [modifyEvent-Response (JSON)]

{
  "request_id": "cbd60372-df33-41d3-b203-169ad5e3AAAA",
  "data": [
    {
      "busy": true,
      "calendar_id": "primary",
      "conferencing": {
        "details": {
          "meeting_code": "ist-****-tcz",
          "url": "https://meet.google.com/ist-****-tcz"
        },
        "provider": "Google Meet"
      },
      "created_at": 1701974804,
      "creator": {
        "email": "anna.molly@example.com",
        "name": ""
      },
      "description": null,
      "grant_id": "1e3288f6-124e-405d-a13a-635a2ee54eb2",
      "hide_participants": false,
      "html_link": "https://www.google.com/calendar/event?eid=NmE0dXIwabQAAAA",
      "ical_uid": "6aaaaaaame8kpgcid6hvd0q@google.com",
      "id": "6aaaaaaame8kpgcid6hvd",
      "object": "event",
      "organizer": {
        "email": "anna.molly@example.com",
        "name": ""
      },
      "participants": [
        {
          "email": "jenna.doe@example.com",
          "status": "yes"
        },
        {
          "email": "anna.molly@example.com",
          "status": "yes"
        }
      ],
      "read_only": true,
      "reminders": {
        "overrides": null,
        "use_default": true
      },
      "status": "confirmed",
      "title": "Holiday check in",
      "updated_at": 1701974915,
      "when": {
        "end_time": 1701978300,
        "end_timezone": "America/Los_Angeles",
        "object": "timespan",
        "start_time": 1701977400,
        "start_timezone": "America/Los_Angeles"
      }
    }
  ]
}


```

```js [modifyEvent-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function addParticipantToAndEvent() {
  try {
    const event = await nylas.events.update({
      identifier: "<NYLAS_GRANT_ID>",
      eventId: "<EVENT_ID>",
      requestBody: {
        participants: [
          {
            name: "Nylas DevRel",
            email: "devrel-@-nylas.com",
          },
        ],
      },
      queryParams: {
        calendarId: "<CALENDAR_ID>",
      },
    });
  } catch (error) {
    console.error("Error adding participant to event:", error);
  }
}

addParticipantToAndEvent();


```

```python [modifyEvent-Python SDK]

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"
event_id = "<EVENT_ID>"

event = nylas.events.update(
    grant_id,
    event_id,
    request_body={
      "participants": [{
        "name": "Nylas DevRel",
        "email": "devrel-@-nylas.com"
      }]
    },
    query_params={
      "calendar_id": "<CALENDAR_ID>"
    }
)

print(event)

```

```ruby [modifyEvent-Ruby SDK]

require 'nylas'

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

request_body = {
	location: "Nylas' Theatre",
}

query_params = {
	calendar_id: "<CALENDAR_ID>"
}

events, _request_ids = nylas.events.update(
		identifier: "<NYLAS_GRANT_ID>", 
		event_id: "<EVENT_ID>", 
		query_params: query_params,
		request_body: request_body)


```

```java [modifyEvent-Java SDK]

import com.nylas.NylasClient;
import com.nylas.models.*;

public class update_calendar_events {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
    UpdateEventQueryParams params = new UpdateEventQueryParams("<CALENDAR_ID>", Boolean.FALSE);
    UpdateEventRequest requestBody = new UpdateEventRequest.Builder().location("Nylas' Theatre'").build();

    Response<Event> event = nylas.events().update(
      "<NYLAS_GRANT_ID>",
      "<EVENT_ID>",
      requestBody,
      params);
  }
}

```

```kt [modifyEvent-Kotlin SDK]

import com.nylas.NylasClient
import com.nylas.models.*

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  val queryParams = UpdateEventQueryParams("<CALENDAR_ID>", false)

  val requestBody : UpdateEventRequest = UpdateEventRequest.Builder().
      location("Nylas' Theatre").
      build()

  val response : Response<Event> = nylas.events().update(
      "<NYLAS_GRANT_ID>",
      "<EVENT_ID>",
      requestBody,
      queryParams)
}

```

For more information about the parameters you can modify, see the [Events references](/docs/reference/api/events/).

### Notify participants

The query string parameter `notify_participants=true` sends an email invitation to all email addresses listed in the `participants` sub-object. The query string parameter defaults to `true`.

> **Warn:** 
> **Keep in mind**: When `notify_participants=false`, your request doesn't create an event for the participant. Participants don't receive a message or an ICS file.

## Delete an event

If an event is cancelled, you can delete it and send an email notification to all participants.

```bash
curl --compressed --request DELETE \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

```

```bash [deleteEvent-Response (JSON)]

{
  "request_id": "1"
}


```

```js [deleteEvent-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function deleteEvent() {
  try {
    const event = await nylas.events.destroy({
      identifier: "<NYLAS_GRANT_ID>",
      eventId: "<EVENT_ID>",
      queryParams: {
        calendarId: "<CALENDAR_ID>",
      },
    });

    console.log("Event deleted:", event);
  } catch (error) {
    console.error("Error to delete event:", error);
  }
}

deleteEvent();


```

```python [deleteEvent-Python SDK]

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"
event_id = "<EVENT_ID>"

event = nylas.events.destroy(
    grant_id,
    event_id,
    query_params={
      "calendar_id": "<CALENDAR_ID>"
    }
)

print(event)

```

```ruby [deleteEvent-Ruby SDK]

require 'nylas'	

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

query_params = {
  calendar_id: "<CALENDAR_ID>"
}

result, _request_ids = nylas.events.destroy(
    identifier: "<NYLAS_GRANT_ID>", 
    event_id: "<EVENT_ID>",
    query_params: query_params)

puts result


```

```java [deleteEvent-Java SDK]

import com.nylas.NylasClient;
import com.nylas.models.*;

public class delete_calendar_events {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
    DestroyEventQueryParams queryParams = new DestroyEventQueryParams("<CALENDAR_ID>", Boolean.FALSE);

    DeleteResponse event = nylas.events().destroy(
        "<NYLAS_GRANT_ID>",
        "<EVENT_ID>",
        queryParams);
  }
}

```

```kt [deleteEvent-Kotlin SDK]

import com.nylas.NylasClient
import com.nylas.models.*

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  val queryParams = DestroyEventQueryParams("<CALENDAR_ID>", false)

  val event = nylas.events().destroy(
      "<NYLAS_GRANT_ID>",
      "<EVENT_ID>", 
      queryParams)
}

```

## RSVP to an event

To make event planning even easier, the Nylas Event API lets you send an RSVP response to an event's organizer.

The [Send RSVP endpoint](/docs/reference/api/events/send-rsvp/) lets you send a response to a specified event's organizer with an RSVP status (`yes`, `no`, or `maybe`). This lets the organizer know whether you plan to come, and updates the event with your RSVP status.

Nylas sends event RSVPs as email updates. If your application does not include the email send API scopes, Nylas updates the RSVP for the event and returns a `200` error message. If this happens, event participants on the _same_ provider will see the RSVP update, but participants on other providers will not.

```bash
curl --compressed --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>/send-rsvp?calendar_id=<CALENDAR_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "yes"
  }'

```

```json [sendRSVP-Response (JSON)]

{
  "request_id": "1"
}


```

```js [sendRSVP-Node.js SDK]

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function sendEventRSVP() {
  try {
    const response = await nylas.events.sendRsvp({
      identifier: "<NYLAS_GRANT_ID>",
      eventId: "<EVENT_ID>",
      requestBody: {
        status: "yes",
      },
      queryParams: {
        calendarId: "<CALENDAR_ID>",
      },
    });

    console.log("Event RSVP:", response);
  } catch (error) {
    console.error("Error sending RSVP:", error);
  }
}

sendEventRSVP();


```

```python [sendRSVP-Python SDK]

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

response = nylas.events.send_rsvp(
    identifier="<NYLAS_GRANT_ID>",
    event_id="<EVENT_ID>",
    request_body={"status": "yes"},
    query_params={"calendar_id": "<CALENDAR_ID>"},
)

print(response)


```

```ruby [sendRSVP-Ruby SDK]

require 'nylas'	

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

request_body = {
  status: "yes"
}

query_params = {
  calendar_id: "<CALENDAR_ID>"
}

event_rsvp = nylas.events.send_rsvp(
    identifier: "<NYLAS_GRANT_ID>",
    event_id: "<EVENT_ID>", 
    request_body: request_body,
    query_params: query_params)
    
puts event_rsvp

```

```java [sendRSVP-Java SDK]

import com.nylas.NylasClient;
import com.nylas.models.*;

public class rsvp {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
    SendRsvpRequest requestBody = new SendRsvpRequest(RsvpStatus.YES);
    SendRsvpQueryParams queryParams = new SendRsvpQueryParams("<CALENDAR_ID>");

    DeleteResponse rsvp = nylas.events().sendRsvp(
        "<NYLAS_GRANT_ID>",
        "<EVENT_ID>", 
        requestBody,
        queryParams);
        
    System.out.println(rsvp);
  }
}

```

```kt [sendRSVP-Kotlin SDK]

import com.nylas.NylasClient
import com.nylas.models.RsvpStatus
import com.nylas.models.SendRsvpQueryParams
import com.nylas.models.SendRsvpRequest

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  val requestBody : SendRsvpRequest = SendRsvpRequest(RsvpStatus.YES)
  val queryParams : SendRsvpQueryParams = SendRsvpQueryParams("<CALENDAR_ID>")

  val rsvp = nylas.events().sendRsvp(
      "<NYLAS_GRANT_ID>",
      "<EVENT_ID>", 
      requestBody,
      queryParams)

  print(rsvp)
}

```

```bash
nylas calendar events rsvp <EVENT_ID> --status yes
```

## Get available room resources

You can use the [`GET /v3/grants/<GRANT_ID>/resources` endpoint](/docs/reference/api/room-resources/) to get a list of resources such as conference rooms or other equipment that the user can book.

Nylas returns only items that the user's grant has access to. You cannot book a resource on behalf of a user if they don't have access to that resource.

At minimum, each resource has an email address, which also serves as its calendar identifier. You can add a resource to an event by including its email address in an event invitation, and you can use the same email address to query the resource's availability (for example, by passing it as a value in calendar_ids for Availability or Free/Busy requests).

> **Warn:** 
> **Room resource calendars do not list all-day bookings in [**Free/Busy request responses**](/docs/reference/api/calendar/post-calendars-free-busy/) on Google or Microsoft**. However, these events do appear in [Availability requests](/docs/reference/api/calendar/post-availability/).

## Limited attendance events

Limited attendance events allow an organizer to set specific times when they're available to meet with a group, and limit the number of people who can attend. This is useful for events such as online classes or seminars.

The event owner creates and schedules the event, and sets a maximum number of attendees. They then make the event available to book, provide a way for attendees to select it, and send potential attendees an invitation to choose a time. Attendees can choose to sign up if one of the set times works for them.

When an attendee books an event, Nylas checks that the event hasn't met its `capacity` limit yet, creates an event on the attendee's calendar, and increments the `capacity` counter for the event.

### Enable attendance limits

To limit the number of attendees for an event, pass the `capacity` value in your [Create Event request](/docs/reference/api/events/create-event/). The `capacity` field defaults to `-1`, meaning the event is open to an unlimited number of attendees. Set it to the desired number of attendees (not counting the event owner) to create a limited attendance event.

```json
{
  "title": "Philosophy Club Lecture series",
  "busy": true,
  "capacity": 5,
  "organizer": {
      "name": "Aristotle",
      "email": "aristotle@example.com"
    },
  "participants": [{
    "name": "Jane Stephens",
    "email": "jane.stephens@example.com"
  }],
  "hide_participants": true,
  "description": "Come ready to talk philosophy!",
  "when": {
      "start_time": 1674604800,
      "end_time": 1722382420,
      "start_timezone": "America/New_York",
      "end_timezone": "America/New_York"
  },
  "location": "New York Public Library, Cave room",
}'
```

If the participant count for a limited attendance event exceeds the `capacity` when an attendee tries to book the event, Nylas returns a `400` error response with the updated message.

## What's next

- [Manage calendar events from the terminal](https://cli.nylas.com/guides/manage-calendar-from-terminal) — List, create, and update events from the command line using the Nylas CLI.