Getting started with the Nylas Ruby SDK
Ruby is an open-source programming language focusing 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:
- Install the Nylas Ruby SDK.
- Initialize the API object.
- Change the base API URL.
- Integrate with the Nylas Email, Calendar, and Contacts APIs.
Prerequisites
-
Sign up for your developer account.
-
Get your Nylas keys:
CLIENT_ID
- The CLIENT ID found on the dashboard page for your Nylas App.CLIENT_SECRET
- The CLIENT SECRET found on the dashboard page for your Nylas App.ACCESS_TOKEN
- The access token provided when you authenticate an account to your Nylas App.
-
Install Ruby 2.3 or later.
-
Install the following RubyGems:
Step 1: Install the Nylas Ruby SDK
-
Add the following to your application's Gemfile:
gem 'nylas'
-
Run the
bundle
command.bundle
-
Install the Nylas gem so you can run scripts that use the Nylas Ruby SDK.
gem install nylas
MacOS 10.11 (El Capitan)
The Nylas gem dependencies require that you 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 the following commands in your terminal to install OpenSSL separately.
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 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.
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/downgrade them. You need
CLIENT_ID
andCLIENT_SECRET
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
CLIENT_ID
,CLIENT_SECRET
, andACCESS_TOKEN
for the specific user account to initialize theAPI
object. Learn more about the Accounts API endpoint.
Do one of the following:
-
To initialize the
API
object for the Nylas app client, passCLIENT_ID
andCLIENT_SECRET
.#!/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
) -
To initialize the
API
object for the Nylas user account client, passCLIENT_ID
,CLIENT_SECRET
, andACCESS_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
)Alternately, you can pass
CLIENT_ID
andCLIENT_SECRET
first, then addwith_access_token
to pass theACCESS_TOKEN
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)
You can use the dotenv
gem to store environment variables and access them.
Step 3: 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
)
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, and it offers full Create, Read, Update, and Delete (CRUD) operations for most of the providers. For more information on the functionality of the Nylas Email API, see the Email API documentation.
The following are common tasks you can perform using the Nylas Ruby SDK and Email API.
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 Create, Read, Update, and Delete (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 are 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 connects your end-users' address books and contact databases directly into your application. It offers full Create, Read, Update, and Delete (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 are common tasks you can perform using the Nylas Ruby SDK and Contacts API.
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.