Get started with the Nylas Ruby SDK
Ruby is an open-source programming language that focuses on simplicity and productivity. The Nylas Ruby SDK provides the quickest way to build your email, calendar, and contacts integrations using Ruby.
What you'll learn
In this tutorial, you'll learn how to do the following tasks:
- Install the Nylas Ruby SDK.
- Initialize the API object.
- Change the base API URL.
- Integrate with the Nylas Email, Calendar, and Contacts APIs.
Prerequisites
-
CLIENT_ID
: The client ID for your application in the Nylas Dashboard.CLIENT_SECRET
: The client secret for your application in the Nylas Dashboard.ACCESS_TOKEN
: The access token provided when you authenticate an account to your Nylas application.
-
Install Ruby v2.3 or later.
-
Install the following gems:
Step 1: Install the Nylas Ruby SDK
-
Add a reference to the Nylas gem in your application's Gemfile:
gem 'nylas'
-
Open your terminal and run the
bundle
command. -
Run
gem install nylas
to install the Nylas gem.
MacOS 10.11 (El Capitan)
The Nylas gem requires you to have OpenSSL installed. However, Apple stopped bundling OpenSSL with its native Ruby version as of MacOS 10.11. If you're using MacOS El Capitan and have trouble installing the gem, you can run these commands in your terminal to install OpenSSL:
sudo brew install openssl
sudo brew link openssl --force
gem install nylas
Step 2: Initialize the API
object
All of the functionality of the Nylas platform is available through the API
object. Before you make requests, you must initialize the API
object with your client ID, client secret, and access token.
You can initialize the API
object for either a Nylas app client or a Nylas user account client:
- A Nylas app client allows you to access and modify the Application Accounts endpoint, which enables you to check the status of user accounts connected to your Nylas app and upgrade or downgrade them. You need the
CLIENT_ID
andCLIENT_SECRET
parameters to initialize theAPI
object. - A Nylas user account client enables you to access all Email, Calendar, and Contacts functionality and data for a specific user account. You need the
CLIENT_ID
,CLIENT_SECRET
, andACCESS_TOKEN
parameters for the specific user account to initialize theAPI
object. For more information, you can browse the Accounts API endpoint docs.
You can use the dotenv
gem to store environment variables and access them later.
Initialize the API
object for a Nylas app client
To initialize the API
object for a Nylas app client, pass the CLIENT_ID
and CLIENT_SECRET
parameters to the new API
object:
#!/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
)
Initialize the API
object for a Nylas user account client
To initialize the API
object for a Nylas user account client, pass the CLIENT_ID
, CLIENT_SECRET
, and ACCESS_TOKEN
parameters to the new API
object:
#!/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
)
Alternately, you can pass the CLIENT_ID
and CLIENT_SECRET
parameters first, then pass the ACCESS_TOKEN
parameter separately:
#!/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
)
with_access_token = nylas.as(ACCESS_TOKEN)
Step 3: (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.
Use cases: Email API
The Nylas Email API makes it easy to integrate Gmail, Outlook, Microsoft Exchange, Office 365, and other email service providers with your application. It offers full Create, Read, Update, and Delete (CRUD) operations for most providers. For more information, see the Email API documentation.
The following examples show you how to use the Nylas Ruby SDK and Email API to perform common tasks.
View messages and threads
#!/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
)
# Return the most recent email
message = nylas.messages.first
puts(
"Subject: #{message.subject} | "\
"Unread: #{message.unread} | "\
"From: #{message.from.first.email} | "\
"ID: #{message.id} | "\
)
# .threads returns all threads that have been synced to Nylas
threads = nylas.threads.limit(10) # Limit and offset can be used to control pagination
threads.each{ |thread|
puts(
"Subject: #{thread.subject} | "\
"Participant: #{thread.participants.first.email} | "\
)
}
# Filter for the 5 most recent unread threads
threads = nylas.threads.where(unread: true).limit(5)
threads.each{ |thread|
puts(thread.subject)
}
Search messages and threads
You can use the Search sub-endpoint to run a full-text search that is proxied through the account's provider. Nylas matches the results with objects that is has synced, and returns them.
#!/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
)
# Search for the most recent email from a specific address
message = nylas.messages.search("from:[email protected]").first
puts(message.subject)
# You can also search threads
thread = nylas.threads.search("to:[email protected]").first
puts(thread.subject)
Learn More
Learn more about the Search API endpoint.
Send an email
#!/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
)
nylas.send!(
to: [{ email: '[email protected]', name: "Nylas" }],
subject: "With Love, from Nylas",
body: "This email was sent using the Nylas Email API. Visit https://nylas.com for details."
).to_h
Reply to an email
#!/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
)
message_id = 'a8v4hcwpx1ta5obe77eaxvhm9'
message = nylas.messages.find(message_id)
draft = nylas.drafts.create(
reply_to_message_id: message.id,
to: message.from,
body: "This is my reply."
)
draft.send!
Learn More
Learn more about the Sending API endpoint.
Use cases: Calendar API
The Nylas Calendar API provides an abstraction layer on top of all calendar providers, and gives you full CRUD operations. With just a few lines of code, you can add full-featured scheduling and calendar sync to your application. For more information, see the Calendar API documentation.
The following examples show tasks you can perform using the Nylas Ruby SDK and Calendar API.
Read calendars and events
#!/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
)
# Most user accounts have multiple calendars where events are stored
calendars = nylas.calendars
calendars.each{ |calendar|
# Print the name and description of each calendar and whether or not the calendar is read only
puts(
"Name: #{calendar.name} | "\
"Description: #{calendar.description} | "\
"Read Only: #{calendar.read_only}"
)
}
# Pick a calendar to inspect.
calendar = nylas.calendars.first()
events = nylas.events.limit(5)
events.each{ |event|
puts(
"Title: #{event.title} | "\
"When: #{event.when.start_time} | "\
"Partcipants: #{event.participants.first.name}"
)
}
Use cases: Contacts API
The Nylas Contacts API brings your end-users' address books and contact databases directly into your application. It offers full CRUD operations so you can run bi-directional syncs with contact data, including addresses, email addresses, birthdays, job titles, and more. For more information, see the Contacts API documentation.
The following example shows you how to use the Nylas Ruby SDK and Contacts API to create a new contact.
Create a new contact
#!/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
)
contact = nylas.contacts.create
# The contact's given name is typically their first name,
# you can specify a last name with 'surname'
contact.given_name = "My Nylas Friend"
# Phone number type must be one of 'business', 'organization_main',
# 'mobile', 'assistant', 'business_fax', 'home_fax', 'radio', 'car', 'home', or 'pager'
# Google labels 'business' phone numbers as the contact's Work phone number
contact.phone_numbers = [{type: 'business', number: '555 555-5555'}]
# Email address 'type' must be either 'work' or 'personal'
contact.emails = [{type: 'work', email: '[email protected]'}]
contact.notes = "Make sure to keep in Touch!"
# web_pages must be one of type homepage, profile, work, or blog
contact.web_pages = [{type: 'homepage', url: 'https://nylas.com'}]
contact.save
Learn More
Learn more about the Contacts API endpoint.
What's next?
- Follow our Ruby SDK tutorials.