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 and CLIENT_SECRET to initialize the API 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, and ACCESS_TOKEN for the specific user account to initialize the API object. Learn more about the Accounts API endpoint.

Do one of the following:

To initialize the API object for the Nylas app client, pass CLIENT_ID and CLIENT_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, pass 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
)

Alternately, you can pass CLIENT_ID and CLIENT_SECRET first, then add with_access_token to pass the ACCESS_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)
}

Learn More

Learn more about the Messages and Threads API endpoints.

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}"
        )
}

Learn More

Learn more about the Calendars and Events API endpoints.

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.