Only show these results:

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.

  1. Call nylas.calendars to return all calendars.

  2. (Optional) Specify attributes for the calendar object. For example, this code logs each calendar's ID, Name, Description, and Read 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.

  1. Define the now parameter (the current time in Unix epoch format) with the Time to_i method.
  2. Call the .where() method to display the calendar_id and events that are scheduled to occur after the current time (starts_after: now).
  3. Set the limit parameter to 5 to read only the next five events. For more information on using limits and offsets to paginate results, see the Pagination documentation.
  4. Using the each method, specify the Title, When, and Participants 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.

  1. Set the event's title, location, and description variables:

    title = "New Years Party!"
    location = "My House!"
    description = "We'll ring in the new year in style!"

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

    • Participants are added as an array of participant subobjects. Each participant object requires an email value. The name value is optional.

    Time.local in Ruby: You can use Time.local to convert UTC timestamps to a human-readable format.

  3. Next, set the calendar ID and create an event. To enable email notifications, set the notify_participants parameter to true:

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

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: