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 Calendar API. The Calendar API connects to all major providers including Google, Exchange, iCal, Outlook, and more.
This page discusses 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 tasks:
- Read calendars and events.
- Create events and send email notifications to participants.
- RSVP to events.
Prerequisites
Before you start this tutorial, you must install the Nylas Ruby SDK and set up your environment. See Get started with the Nylas Ruby SDK for more information.
Step 1: Initialize the API
object
All of the functionality of the Nylas 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, see Get started with the Nylas Ruby SDK.
Step 2: (Optional) Change the base API URL
You can choose to 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 the API_URL
parameter 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
)
If you're using the Nylas EU region: The base API URL defaults to the US region, but you can specify api_server: 'https://ireland.api.nylas.com'
to use the EU region. See Data Residency for more information.
Step 3: Read calendars and events
You can use the nylas
object to read calendars and events from a user's account.
Read calendars
To access the calendars associated with an account, use the nylas.calendar
object. You can access the account's default calendar and its custom calendars, such as those that the user created, or their shared team calendars.
-
Call
nylas.calendars
to return all calendars. -
(Optional) Specify attributes for the calendar object. For example, this code 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's ID.Name
: The calendar's name.Description
: The calendar's description.Read Only
: A Boolean that specifies whether the user has Write access to the calendar.
Learn More
Learn more about the Calendar endpoint.
Read events
To access the events associated with a user's account, use the nylas.events
object.
Here, we'll read the next five events that occur on the user's calendar after the current time (now
). Each event that's returned will include its title, start time, and list of participants.
- Define the
now
parameter (the current time in Unix epoch format) with theTime to_i
method. - Call the
.where()
method to display thecalendar_id
and events that are scheduled to occur after the current time (starts_after: now
). - Set the
limit
parameter to5
to read only the next five events. For more information on using limits and offsets to paginate results, see the Pagination documentation. - Using the
each
method, specify theTitle
,When
, andParticipants
variables.
When put together, the code looks like this:
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
Learn more about the Events endpoint.
Example: Read calendars and events
This example reads calendars and events from a user's 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
When you create an event, you can set certain variables associated with its attributes. For more information on available event attributes, see the POST /events documentation.
-
Set the event's
title
,location
, anddescription
variables:title = "New Years Party!"
location = "My House!"
description = "We'll ring in the new year in style!" -
Set the event's start and end times, 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 these event subobjects:
- Time:
time
,timezone
- Timespan:
startTime
,endTime
,startTimezone
,endTimezone
- Date:
date
- Datespan:
startDate
,endDate
- Time:
-
Participants are added as an array of participant subobjects. Each participant object requires an
email
value. Thename
value is optional.
Time.local in Ruby: You can use
Time.local
to convert UTC timestamps to a human-readable format. -
-
Next, set the calendar ID and create an event. To enable email notifications, set the
notify_participants
parameter 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
must be the ID for a calendar that the user has Write access to. For information on how to retrieve calendar IDs, see Read calendars.- The default value of
notify_participants
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)
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 these 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 platform works.
- Read our How to manage calendar events with the Nylas Ruby SDK blog post.