Version:
Only show these results:

Using the Events API

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

How the Events API works

Every end 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 or Get Free/Busy Schedule) 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 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, which gets you a free Nylas application and API key.

For a guided introduction, you can follow the Getting started guide 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 an end user's calendar, make a Get Events request that includes the specific calendar ID.

⚠️ You must include a calendar ID in your request. If you don't, Nylas returns a 400 error.

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'   
{
  "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"
    }
  }]
}

By default, Nylas returns a list of 100 Event objects. The results are sorted by the start date and time, beginning with the oldest event.

If you know the ID for a specific event, you can make a Get Event request to fetch it instead.

You can also get a list of events using the Nylas SDKs, as in the following examples.

import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI
}

const nylas = new Nylas(NylasConfig)

async function fetchAllEventsFromCalendar() { 
  try {
    const events = await nylas.events.list({
      identifier: process.env.NYLAS_GRANT_ID,
      queryParams: {
        calendarId: process.env.CALENDAR_ID,
      }
    })
  
    console.log('Events:', events)
  } catch (error) {
    console.error('Error fetching calendars:', error)
  }
}

fetchAllEventsFromCalendar()   
from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("NYLAS_GRANT_ID")

events = nylas.events.list(
    grant_id,
    query_params={
      "calendar_id": os.environ.get("CALENDAR_ID")
    }
)

print(events)   
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"
}   
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");
    }
  }
}   
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.name + " Name: " + participant.email + 
          " Status: " + participant.status)
    }
    
    println("\n")
  }
}

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.

⚠️ You must include a calendar ID in your request. If you don't, Nylas returns a 400 error.

curl --request GET \
  --url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>&start=<EPOCH_TIMESTAMP>&end=<EPOCH_TIMESTAMP> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/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"
    }
  }]
}

For information about the parameters you can use in queries to the Get Events endpoint, see the Events reference.

You can also filter results using the Nylas SDKs, as in the example below.

import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI
}

const nylas = new Nylas(NylasConfig)

async function fetchAllEventsFromCalendar() { 
  try {
    const events = await nylas.events.list({
      identifier: process.env.NYLAS_GRANT_ID,
      queryParams: {
        calendarId: process.env.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.

{
  ...
  "data": [{
    ...
    "when": {
      "start_date": "2024-12-01",
      "end_date": "2024-12-02",
      "object": "datespan"
    }
  }]
}   
{
  "start": {
    "date": "2024-12-01"
  },
  "end": {
    "date": "2024-12-02"
  }
}   
{
  "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.

curl --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",
    "status": "confirmed",
    "busy": true,
    "participants": [
      {
        "name": "Aristotle",
        "email": "aristotle@example.com"
      },
      {
        "name": "Jane Stephens",
        "email": "jane.stephens@example.com"
      }
    ],
    "resources": [
      {
        "name": "Conference room",
        "email": "conference-room@resources.google.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"
  ],
}'   
{
  "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"
    }
  }]
}   
import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

const now = Math.floor(Date.now() / 1000)

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

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

createAnEvent()   
from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("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": os.environ.get("CALENDAR_ID")
  }
)

print(events)   
require 'nylas'

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

query_params = {
	calendar_id: "<NYLAS_GRANT_ID>"
}

today = Date.today
start_time = Time.local(today.year, today.month, today.day, 13, 0, 0).strftime("%s")
end_time = Time.local(today.year, today.month, today.day, 13, 30, 0).strftime("%s")

request_body = {
	when: {
		start_time: start_time.to_i,
		end_time: end_time.to_i
	},
	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'
	}]
}

events, _request_ids = nylas.events.create(
		identifier: "<NYLAS_GRANT_ID>", 
		query_params: query_params,
		request_body: request_body)   
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 Epoch
    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();
  }
}   
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 epoch 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(dotenv["NYLAS_GRANT_ID"],
      eventRequest, eventQueryParams)
}

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 to add a participant for the New Year's Eve party and send an invitation.

⛔️ 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!

curl --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": "Dorothy Vaughan",
      "email": "dorothy@example.com",
      "comment": "string"
    }],
    "resources": [{
      "name": "Conference room",
      "email": "conference-room@resources.google.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": "WebEx",
      "details": {
        "password": "string",
        "pin": "string",
        "url": "string"
      }
    },
    "reminder_minutes": "[20]",
    "reminder_method": "popup"
}'   
{
  "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"
    }
  }]
}   
import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI
}

const nylas = new Nylas(NylasConfig)

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

addParticipantToAndEvent()   
from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("NYLAS_GRANT_ID")
event_id = os.environ.get("EVENT_ID")

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

print(event)   
require 'nylas'

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

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

query_params = {
	calendar_id: "<NYLAS_GRANT_ID>"
}

events, _request_ids = nylas.events.update(
		identifier: "<NYLAS_GRANT_ID>", 
		event_id: "<EVENT_ID>", 
		query_params: query_params,
		request_body: request_body)   
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);
  }
}   
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 reference documentation.

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.

⚠️ Keep in mind: When notify_participants=false, your request doesn't create an event for the participant. Participants don't receive an email 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.

curl --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'   
{
  "request_id": "1"
}   
import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI
}

const nylas = new Nylas(NylasConfig)

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

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

deleteEvent()   
from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("NYLAS_GRANT_ID")
event_id = os.environ.get("EVENT_ID")

event = nylas.events.destroy(
    grant_id,
    event_id,
    query_params={
      "calendar_id": os.environ.get("CALENDAR_ID")
    }
)

print(event)   
require 'nylas'	

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

query_params = {
  calendar_id: "<NYLAS_GRANT_ID>"
}

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

puts result   
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);
  }
}   
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 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.

curl --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": "string"
}'   
{
  "request_id": "1"
}   
import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI
}

const nylas = new Nylas(NylasConfig)

async function sendEventRSVP() {
  try {
    const event = await nylas.events.update({
      identifier: process.env.NYLAS_GRANT_ID,
      eventId: process.env.EVENT_ID,
      requestBody: {
        participants: [{
          name: 'Nylas DevRel',
          email: 'devrelram@nylas.com',
          status: 'yes',
        }]
      },
      queryParams: {
        calendarId: process.env.CALENDAR_ID,
      },
    })

    console.log('Event RSVP:', event)
  } catch (error) {
    console.error('Error to RSVP participant for event:', error)
  }
}

sendEventRSVP()   
from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("NYLAS_GRANT_ID")
event_id = os.environ.get("EVENT_ID")

event = nylas.events.update(
    grant_id,
    event_id,
    request_body={
      "participants": [{
        "name": "Nylas DevRel",
        "email": "devrel@nylas.com",
        "status": "yes"
      }]
    },
    query_params={
      "calendar_id": os.environ.get("CALENDAR_ID")
    }
)

print(event)   
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   
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);
  }
}   
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)
}

Get available room resources

You can use the GET /v3/grants/<GRANT_ID>/resources endpoint to get a list of resources such as conference rooms or other equipment that the end user can book.

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

At minimum, each resource has an email address and a calendar. You can add a resource to an event by including its email address in an event invitation, and you can use the calendar ID to get the resource's availability.

⚠️ Room resource calendars do not list all-day bookings in free/busy request responses on Google or Microsoft. However, these events do appear in availability requests.

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

{
  "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.

More resources

The Nylas Samples Github repository includes working example applications in several languages that use the Nylas Event API. The following examples are interesting places to start exploring: