Only show these results:

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

Step 1: Install the Nylas Ruby SDK

  1. Add a reference to the Nylas gem in your application's Gemfile:

    gem 'nylas'

  2. Open your terminal and run the bundle command.

  3. 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 and CLIENT_SECRET parameters 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 the CLIENT_ID, CLIENT_SECRET, and ACCESS_TOKEN parameters for the specific user account to initialize the API 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)
}

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

Learn More

Learn more about the Calendars and Events API endpoints.

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?