Manage events with the Nylas Ruby SDK
The Nylas Ruby SDK is the quickest way to integrate calendars into your app with Ruby and the Nylas Calendar API. The Nylas Calendar API connects to all major providers including Google, Exchange, iCal, Outlook, and more.
This guide explains how to use the Nylas Ruby SDK and Calendar API to create events.
What you'll learn
In this tutorial, you'll learn how to do the following:
- Read calendars and events.
- Create events and send email notifications to participants.
- RSVP to events.
Prerequisites
Prerequisites include installing the Nylas Ruby SDK and setting up your environment. Before you start this tutorial, make sure that you complete the Getting started with the Nylas Ruby SDK tutorial.
Step 1: Initialize the API object
All of the functionality of the Nylas Communications Platform is available through the API
object. Before you make requests, initialize the API
object with your client ID, client secret, and access token.
#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
require 'nylas'
nylas = Nylas::API.new(
app_id: CLIENT_ID,
app_secret: CLIENT_SECRET,
access_token: ACCESS_TOKEN
)
For more information on initializing the API
object, refer to the Getting started with the Nylas Ruby SDK tutorial.
Step 2: Change the base API URL
You can optionally change the base API URL depending on your location:
Location | API URL | Scheduler API URL |
---|---|---|
United States (Oregon) | https://api.nylas.com |
https://api.schedule.nylas.com |
Europe (Ireland) | https://ireland.api.nylas.com |
https://ireland.api.schedule.nylas.com |
For more information, see Data residency and Migration guide for data centers.
Pass API_URL
to change the base API URL.
#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
API_URL='your_base_api_url'
require 'nylas'
nylas = Nylas::API.new(
app_id: CLIENT_ID,
app_secret: CLIENT_SECRET,
access_token: ACCESS_TOKEN,
api_server: API_URL
)
Step 3: Read calendars and events
Learn how to read calendars and events.
Read calendars
Use the nylas.calendar
object to access calendars associated with an account. Available calendars include the account’s default calendar and other custom calendars, such as calendars that the user created or the user’s shared team calendars.
-
Call
nylas.calendars
to return all calendars. -
Optionally, specify attributes for the calendar object.
The following example logs each calendar's
ID
,Name
,Description
, andRead Only
values:calendars = nylas.calendars
calendars.each{ |calendar|
puts(
"Id: #{calendar.id} | "\
"Name: #{calendar.name} | "\
"Description: #{calendar.description} | "\
"Read Only: #{calendar.read_only}"
)
}ID
- The calendar IDName
- The calendar nameDescription
- The calendar descriptioRead Only
- A true/false Boolean that specifies whether the user has write access to the calendar
Learn more about the Calendar endpoint.
Read events
Use the nylas.events
object to access events that are found for a user’s account.
In this tutorial, we'll read the next five events on the user’s calendar after the current time (now
). Each event will include the title, time, and list of participants.
-
Define the
now
variable with the theTime to_i
method.
Thenow
variable represents the current time in Unix epoch time format. -
Set the
calendar
variable tonylas.calendars.first()
to define the first calendar returned in the user's account. -
Call the
.where()
method to show the calendar ID (calendar_id
) and events after the current time (starts_after: now
). -
Set
limit
to5
to read the next five events only.
For more information on using limits and offsets to paginate results, refer to Pagination. -
Using the
each
method, specifyTitle
,When
, andParticipants
.
now = Time.now.to_i
calendar = nylas.calendars.first()
events = nylas.events.where(calendar_id: calendar.id,starts_after: now).limit(5)
events.each{ |event|
puts(
"Title: #{event.title} | "\
"When: #{event.when.start_time} | "\
"Partcipants: #{event.participants.first.name}"
)
}
Learn more about the Events endpoint.
Example: Read calendars and events
The following example reads calendars and events from a user account:
#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
require 'nylas'
require `date`
nylas = Nylas::API.new(
app_id: CLIENT_ID,
app_secret: CLIENT_SECRET,
access_token: ACCESS_TOKEN
)
# Most user accounts have multiple calendars where events are stored
calendars = nylas.calendars
calendars.each{ |calendar|
# Print the id, name and description of each calendar and whether or not the calendar is read only
puts(
"Id: #{calendar.id} | "\
"Name: #{calendar.name} | "\
"Description: #{calendar.description}"\
"Read Only: #{calendar.read_only}"
)
}
# Get today's date
now = Time.now.to_i
# Get the calendar that we want to look into
calendar = nylas.calendars.first()
# Return the next five events on the user's calendar
events = nylas.events.where(calendar_id: calendar.id,starts_after: now).limit(5)
events.each{ |event|
puts(
"Title: #{event.title} | "\
"When: #{event.when.start_time} | "\
"Partcipants: #{event.participants.first.name}"
)
}
Step 4: Create events and send email notifications
Set variables for event attributes and create a event. For more information on available event attributes, refer to POST /events.
-
Set
title
,location
, anddescription
for the event.title = "New Years Party!"
location = "My House!"
description = "We'll ring in the new year in style!" -
Set the event time and add a participant.
start_time = 1653400800
end_time = 1653404400
participants = [{name: "My Friend", email: "[email protected]"}]-
Event times are in UTC time format and can be one of the following event subobjects:
- Time -
time
,timezone
- Timespan -
startTime
,endTime
,startTimezone
,endTimezone
- Date -
date
- Datespan -
startDate
,endDate
- Time -
-
Participants are added as an array of the participant subobject and require an
email
field. Thename
field is optional.
Time.local in Ruby
You can use
Time.local
to convert UTC timestamps to a human readable format in Ruby. -
-
Set the calendar ID and create an event using the variables.
To enable email notifications, set
notify_participants
totrue
.calendar_id = "CALENDAR_ID"
event = nylas.events.create(title: title, location: location, description: description,
when: { start_time: start_time, end_time: end_time },
calendar_id: calendar_id, notify_participants: true)calendar_id
-CALENDAR_ID
must be the ID for the calendar that the user has write access to. For information on how to retrieve calendar IDs, refer to Read calendars.- The default
notify_participants
value isfalse
.
Example: Create events and send email notifications
The following example creates an event and sends email notifications to participants:
#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
require 'nylas'
nylas = Nylas::API.new(
app_id: "CLIENT_ID",
app_secret: "CLIENT_SECRET",
access_token: "ACCESS_TOKEN"
)
title = "New Years Party!"
location = "My House!"
description = "We'll ring in the new year in style!"
start_time = "1653400800"
end_time = "1653404400"
participants = [{name: "My Friend", email: "[email protected]"}]
calendar_id = "CALENDAR_ID"
event = nylas.events.create(title: title, location: location, description: description,
when: { start_time: start_time, end_time: end_time },
participants: participants, calendar_id: calendar_id,
notify_participants: true)
Step 5: RSVP to events
Retrieve events from the Emailed Events calendar and RSVP to the events. The Emailed Events calendar contains all events that the user has received notifications through email. The RSVP feature only works for events in the Emailed Events calendar.
For more information on sending RSVPs, refer to POST /send-rsvp.
-
Use the
.select
method to get the Emailed Events calendar'sid
.If you know the
id
of the specific event that you want to respond to, usenylas.events.find({EVENT_ID})
. -
Use the
.where()
method to filter the event list.For example, the
title
argument specifies the title of the event that you respond to. Learn more about filters.calendar = nylas.calendars.select { |c| c.name == "Emailed events" }.first
event = calendar.events.where(title: "Party").first -
Use the
event.rsvp()
method to set the response value.Supported response values are
yes
,no
, andmaybe
.event.rsvp(:yes, notify_participants: true)
Example: RSVP to events
The following example retrieves the Party event from the Emailed Events calendar and responds "Yes" to the event:
#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
require 'nylas'
nylas = Nylas::API.new(
app_id: "CLIENT_ID",
app_secret: "CLIENT_SECRET",
access_token: "ACCESS_TOKEN"
)
calendar = nylas.calendars.select { |c| c.name == "Emailed events" }.first
event = calendar.events.where(title: "Party").first
event.rsvp(:yes, notify_participants: true)
More resources
If you’ve made it this far, congrats! You’ve integrated your first calendar with the Nylas Calendar API. There's plenty more that you can do with Nylas. Take a look at the following resources:
- Follow our Ruby SDK tutorials.
- Learn more about the Nylas API.
- Learn more about the Nylas Calendar API.
- Learn more about how the Nylas Communications Platform works.
- Read the blog post How to manage calendar events with the Nylas Ruby SDK.