# Using the Ruby SDK

Source: https://developer.nylas.com/docs/v3/sdks/ruby/

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.


> **Warn:** 
> **⚠️ The v6.x Nylas Ruby SDK is only compatible with v3.x Nylas APIs**. If you're still using an earlier version of Nylas, you should keep using the v5.x Ruby SDK until you can upgrade to Nylas v3.


## Before you begin

Before you can start using the Nylas Ruby SDK, make sure you have done the following:

- [Create a free Nylas developer account](https://dashboard-v3.nylas.com/register?utm_source=docs&utm_medium=devrel-surfaces&utm_campaign=&utm_content=ruby-sdk).
- [Get your developer keys](/docs/dev-guide/dashboard/#get-your-api-key). 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](/docs/dev-guide/platform/data-residency/).
  - `NYLAS_GRANT_ID`: The grant ID provided when you authenticate an account to your Nylas application.
- Install [Ruby v3.0 or later](https://www.ruby-lang.org/en/documentation/installation/).
- Install the following gems:
  - [`rest-client`](https://rubygems.org/gems/rest-client).
  - [`yajl-ruby`](https://rubygems.org/gems/yajl-ruby).

## Install the Nylas Ruby SDK

To install the Nylas Ruby SDK, follow these steps:

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

   ```bash
   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 the following commands in your terminal to install OpenSSL.

```bash
sudo brew install openssl
sudo brew link openssl --force
gem 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.

```ruby
#!/usr/bin/env ruby
require '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 (Iowa)   | `https://api.us.nylas.com` |
| Europe (London)        | `https://api.eu.nylas.com` |

For more information, see our [data residency documentation](/docs/dev-guide/platform/data-residency/).


To change the API URL, pass the `NYLAS_API_URI` parameter with the API URL of your location.

```ruby
#!/usr/bin/env ruby
require 'nylas'

nylas = Nylas::Client.new(
    api_key: "<NYLAS_API_KEY>",
    api_uri: "<NYLAS_API_URI>"
)
```

> **Info:** 
> **The base API URL defaults to the Nylas U.S. region**. See the [data residency documentation](/docs/dev-guide/platform/data-residency/) for more information.

## 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.

```ruby

# frozen_string_literal: true

# Load gems
require 'nylas'

# Initialize Nylas client
nylas = Nylas::Client.new(
  api_key: '<NYLAS_API_KEY>'
)

application = nylas.applications.get_details()
puts application


```

## Authenticate 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](/docs/v3/auth/).

In practice, Nylas' REST API simplifies the OAuth process to two steps: [redirecting the user to Nylas](#redirect-user-to-nylas), and [handling the auth response](#handle-the-authentication-response).

### Redirect user to Nylas

The following code sample redirects a user to Nylas for authentication.

```ruby
# frozen_string_literal: true

require 'nylas'
require 'sinatra'

set :show_exceptions, :after_handler
enable :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',
    login_hint: 'swag@nylas.com',
    access_type: 'offline'
  }

  url = nylas.auth.url_for_oauth2(config)
  redirect url
end
```

> **Info:** 
> **Nylas provides granular scopes that allow you to control the level of access your application has to users' data**. For a list of scopes that Nylas supports, see [Using granular scopes to request user data](/docs/dev-guide/scopes/).

### Handle the authentication response

Next, your application has to handle the authentication response from Nylas, as in the example below.

```ruby
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]
  end
end
```

## Latest supported version

For the latest supported version of the SDK, see the [Releases page on GitHub](https://github.com/nylas/nylas-ruby/releases).

## Method reference

The Nylas Ruby SDK includes [method documentation](https://nylas-ruby-sdk-reference.pages.dev/), so you can easily find the implementation details that you need.

## GitHub repositories

The [Nylas Ruby SDK repository](https://github.com/nylas/nylas-ruby) 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](https://github.com/nylas-samples).

## Tutorials

- [Read messages and threads](/docs/v3/sdks/ruby/read-messages-threads/)
- [Send messages](/docs/v3/sdks/ruby/send-email/)
- [Manage contacts](/docs/v3/sdks/ruby/manage-contacts/)

## Recipes in the Cookbook

The [Nylas Cookbook](/docs/cookbook/) has task-focused recipes with examples in Ruby and every other SDK language. A few good starting points:

- [Send transactional email](/docs/cookbook/email/transactional-send/)
- [Schedule a message to send later](/docs/cookbook/email/schedule-send/)
- [Create and manage drafts](/docs/cookbook/email/manage-drafts/)
- [Organize folders and labels](/docs/cookbook/email/organize-folders/)
- [Reply to a thread](/docs/cookbook/email/threads/reply-to-a-thread/)
- [Work with the Contacts API](/docs/cookbook/contacts/contacts-api-guide/)