Nylas Docs

The Nylas Developer Hub

Welcome to the Nylas developer hub. You'll find comprehensive guides and documentation to help you start working with Nylas as quickly as possible, as well as support if you get stuck. Let's jump right in!

Developer Guide

Ruby SDK

The Nylas Ruby SDK Quickstart Guide

The Nylas Communications Platform allows developers to quickly build features that connect to every inbox, calendar, and contacts book in the world. The Nylas SDKs are the quickest way to integrate the Nylas Email, Calendar, and Contacts APIs into your app.

This guide will help you get started with the Nylas Ruby SDK.

Setup your developer account first!

Before following this guide, sign up for a Nylas developer account, and follow our guide to get your developer API keys.

Create Your Developer Account

Before you install the SDK, sign up for a Nylas developer account, and follow our guide to get your developer API keys. You will need three values from this guide to run the code examples found here:

  • 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 that is provided when you authenticate an account to your Nylas App

Install the Nylas Ruby SDK

Prerequisites

  • Ruby 2.3 or above.
  • Ruby Frameworks: rest-client, json, yajl-ruby, em-http-request.

We support Rails 4.2 and above. A more detailed compatibility list can be found in our list of Gemfiles.

Install

Add this line to your application's Gemfile:

gem 'nylas'

And then execute:

bundle

To run scripts that use the Nylas Ruby SDK, install the nylas gem.

gem install nylas

MacOS 10.11 (El Capitan) Note

Apple stopped bundling OpenSSL with MacOS 10.11. However, one of the dependencies of this gem (EventMachine) requires it. If you're on El Capitan and are unable to install the gem, try running the following commands in a terminal:

sudo brew install openssl
sudo brew link openssl --force
gem install nylas

Quickstart Code Examples

Create a Client Object to Connect to Your Nylas App

All of the functionality of the Nylas Communications Platform is available through the API object. There are two ways to initialize API: for a Nylas App, and for an individual user account.

Create Nylas App Client For Account Management
A Nylas App client allows you to access and modify the Account Management endpoint, which lets you check the status of user accounts connected to your Nylas app and upgrade/downgrade them. To create a Nylas App client object, initialize an API object, passing only the CLIENT_ID and CLIENT_SECRET for your Nylas app.

#!/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
)

# Return all accounts that are connected to your Nylas App
accounts = nylas.accounts
accounts.each{ |account|
    puts(
        "Email: #{account.email} | " \
        "Billing State: #{account.billing_state} | " \
        "Sync State: #{account.sync_state} | " \
        "ID: #{account.id}" \
    )
}

Create Nylas User Account Client
A Nylas account client object lets you access all email, calendar, and contacts functionality and data for a specific user account. To create a Nylas account client object, initialize an API object, passing the CLIENT_ID and CLIENT_SECRET for your Nylas App and the ACCESS_TOKEN for the specific user 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'

nylas = Nylas::API.new(
    app_id: CLIENT_ID,
    app_secret: CLIENT_SECRET,
    access_token: ACCESS_TOKEN
)

account = nylas.current_account
puts(
    "Email: #{account.email_address} | " \
    "Provider: #{account.provider} | " \
    "Organization: #{account.organization_unit}"
)
Ready to Build Your Integration?

Read the API reference for the accounts endpoint to learn more about the information you can access for accounts. Now, you should be ready to take a look at how to use the Nylas Ruby SDK to leverage the Nylas email, calendar, and contacts APIs.

Email API

The Nylas Email API makes it easy to integrate Gmail, Outlook, Microsoft Exchange, Office 365 and every other email service provider into your application, and it offers full Create, Read, Update, and Delete (CRUD) operations.

Messages and Threads

The Nylas Email API allows you to work with both messages and threads.

Messages are the fundamental object of the Nylas platform, and the core building block for most email applications. They contain several pieces of information, such as when a message was sent, the sender's address, to whom it was sent, and the message body. They can also contain files (attachments), calendar event invitations, and more.

Threads are first-class objects that represent a collection of messages. Messages are threaded together with a variety of heuristics to match the format of third-party accounts as close as possible.

View Email 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)
}
Ready to Build Your Email Integration?

View the API reference for messages and threads to learn more. You can also check out the email API quickstart guide to learn more about the functionality of the Nylas Email API.

Search Messages and Threads

The search sub-endpoint is used to run a full-text search, that is proxied to the account's provider. Results are matched with objects that have been synced, and then returned.

#!/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)

View the API reference for messages and threads to learn more. You can also check out the email API quickstart guide to learn more about the functionality of the Nylas Email API.

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!
Ready to Build Your Email Integration?

View the API reference for sending to learn more. You can also check out the email API quickstart guide to learn more about the functionality of the Nylas Email API.

Calendar API

The Nylas Calendar API acts as a layer of abstraction on top of all calendar providers. The Nylas calendar API offers full Create, Read, Update, and Delete (CRUD) operations for all major calendar providers, with just a few lines of code you can add full-featured scheduling & calendar sync to your application.

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}"
        )
}
Ready to Build Your Calendar Integration?

Check out the API reference docs for calendars and events to learn more about the features of these endpoints. You can also take a look at the calendar API quickstart guide to learn more about the functionality of the Nylas calendar API.

Contacts API

The Nylas contacts API connects address books and contact databases associated with users' email accounts directly into your application. It offers full Create, Read, Update, and Delete (CRUD) operations to perform bi-directional sync with contact data including addresses, email addresses, birthdays, job titles, and more.

Read Contact Information

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'

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
Ready to Build Your Contacts Integration?

Check out the API reference docs for the contacts endpoint to learn more. You can also take a look at the contacts API quickstart guide to learn more about the functionality of the Nylas contacts API.

Next Steps

How Nylas Works - Take a look at the Nylas architecture to see how we sync billions of emails.

Quickstart Guides - Get up to speed quickly with our SDKs using our quickstart guides for Python and Node.js, or explore the Nylas Email, Calendar, and Contacts APIs.

Tutorials - Check out our plethora of tutorials to learn how to carry out common functionality, like sending emails, reading data from an email inbox, accessing file attachments, and organizing inboxes with labels and folders.

Integration Guides - Ready to start building your integration? Our integration guides cover what it takes to incorporate email functionality into your app. They cover best practices for using the Nylas Communications Platform and provider-specific advice for Google, Microsoft, and more.

Set up Postman - Postman makes it easy to explore the Nylas Email API.

API Reference - Our API reference provides all the detail you need to know to use the Nylas Communications Platform.

Updated about a month ago

Ruby SDK


The Nylas Ruby SDK Quickstart Guide

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.