The Nylas Ruby SDK is an open-source software development kit that enables you to use Ruby to integrate the Nylas APIs with your application.
Before you begin
Before you can start using the Nylas Ruby SDK, make sure you have done the following:
- Create a free Nylas v3 developer account.
- Get your developer keys. You need to have your…
NYLAS_API_KEY
: The API key for your application in the Nylas Dashboard.NYLAS_API_URI
: The URI for your application according to your data residency.NYLAS_GRANT_ID
: The grant ID provided when you authenticate an account to your Nylas application.
- Install Ruby v3.0 or later.
- Install the following gems:
Install the Nylas Ruby SDK
To install the Nylas Ruby SDK, follow these steps:
-
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 the following commands in your terminal to install OpenSSL.
sudo brew install opensslsudo brew link openssl --forcegem install nylas
Initialize the Client object
All of Nylas’ functionality is available through the Client
object. Before you make requests, initialize the Client
object with the API key.
#!/usr/bin/env rubyrequire 'nylas'
nylas = Nylas::Client.new( api_key: "<NYLAS_API_KEY>")
(Optional) Change the base API URL
You can choose to change the base API URL depending on your location, as in the table below.
Location | Nylas API URL |
---|---|
United States (Oregon) | https://api.us.nylas.com |
Europe (Ireland) | https://api.eu.nylas.com |
For more information, see the data residency documentation and the Migration guide for data centers.
To change the API URL, pass the NYLAS_API_URI
parameter with the API URL of your location.
#!/usr/bin/env rubyrequire 'nylas'
nylas = Nylas::Client.new( api_key: "<NYLAS_API_KEY>", api_uri: "<NYLAS_API_URI>")
Test Ruby SDK installation
Now that you have the Ruby SDK installed and set up, you can make a simple program to test your installation. For example, the following code makes a request to return information about your Nylas application.
# frozen_string_literal: true
# Load gemsrequire 'nylas'
# Initialize Nylas clientnylas = Nylas::Client.new( api_key: '<NYLAS_API_KEY>')
application = nylas.applications.get_details()puts application
Authenticate end users
The Nylas APIs use OAuth 2.0 and let you choose to authenticate using either an API key or access token. For more information about authenticating with Nylas, see the Authentication guide.
In practice, Nylas’ REST API simplifies the OAuth process to two steps: redirecting the end user to Nylas, and handling the auth response.
Redirect end user to Nylas
The following code sample redirects an end user to Nylas for authentication.
# frozen_string_literal: true
require 'nylas'require 'sinatra'
set :show_exceptions, :after_handlerenable :sessions
error 404 do 'No authorization code returned from Nylas'end
error 500 do 'Failed to exchange authorization code for token'end
nylas = Nylas::Client.new( api_key: '<NYLAS_API_KEY>', api_uri: '<NYLAS_API_URI>')
get '/nylas/auth' do config = { client_id: '<NYLAS_CLIENT_ID>', provider: 'google', redirect_uri: 'http://localhost:4567/oauth/exchange', access_type: 'offline' }
url = nylas.auth.url_for_oauth2(config) redirect urlend
Handle the authentication response
Next, your application has to handle the authentication response from Nylas, as in the example below.
get '/oauth/exchange' do code = params[:code] status 404 if code.nil?
begin response = nylas.auth.exchange_code_for_token({ client_id: '<NYLAS_CLIENT_ID>', redirect_uri: 'http://localhost:4567/oauth/exchange', code: code }) rescue StandardError status 500 else response[:grant_id] response[:email] session[:grant_id] = response[:grant_id] endend
Latest supported version
For the latest supported version of the SDK, see the Releases page on GitHub.
Method reference
The Nylas Ruby SDK includes method documentation, so you can easily find the implementation details that you need.
GitHub repositories
The Nylas Ruby SDK repository houses the Ruby SDK. You can contribute to the SDK by creating an issue or opening a pull request.
For Nylas code samples, visit the Nylas Samples repository.