Only show these results:

Migrate the Nylas Ruby SDK from v5 to v6 beta

Version 6.0.0 of the Nylas Ruby SDK is a major release that prepares the SDK for the upcoming launch of the Nylas API v3. The goal of this release was to make the SDK more intuitive and easier to use. It includes documentation for the SDK's methods and usage, so you can easily find the implementation details that you need.

The Nylas API v3 brings a lot of changes. Be sure to familiarize yourself with them before you start upgrading. For more information, see the list of v3 features and changes and the v3 diff list.

⚠️ The Nylas Ruby SDK v6 is not compatible with Nylas APIs earlier than v3 Beta. If you're still using an earlier version of the API, Nylas recommends that you keep using the Ruby SDK v5.x until you can start using the Nylas v3 APIs.

Migrate to Nylas Ruby SDK v6

📝 Note: The minimum Ruby version is now the lowest-supported long-term stable release (LTS): v3.0.

To upgrade your v5.x Nylas Ruby SDK to v6, download and install the new gem.

gem install nylas --pre

Initialize the Nylas SDK

After you migrate to v6 of the SDK, you need to set up your environment. To do this, initialize a new instance of the Nylas SDK by passing your API key to the constructor, as below.

require 'nylas'

nylas = Nylas::API.new(
  api_key: "NYLAS_API_KEY",
)

You can now use the Nylas instance to make API requests.

Making requests to the Nylas API

To make requests to the Nylas API, you use the Nylas instance that you configured when you initialize the Nylas SDK.

The Nylas SDK is organized into resources corresponding to each of the Email and Calendar APIs. Each resource includes all of the available methods to make requests to a specific API.

ℹ️ Available v3 APIs: Currently, only the v3 Email and Calendar APIs are available. The Messages, Drafts, Threads, and Contacts APIs are coming soon!

For example, to get a list of Events, you can use the events.list method as in the code sample below.

require 'nylas'

nylas = Nylas::API.new(
  api_key: "NYLAS_API_KEY",
)

events, _request_ids = nylas.events.list(identifier: "grant_id")

Changes to requests in the Ruby SDK v6

There are some new concepts in the Ruby SDK that you may notice when making requests. These are explained in more detail in the following sections.

Resource parameters

In v6 of the Nylas Ruby SDK, each resource takes different parameters.

All resources take an identifier, which is the ID of the account ("Grant") that you want to make the request on behalf of. This is usually the Grant ID or the email address associated with the account.

Some resources also take query parameters, which are mainly used to filter data or pass additional information.

Standard response objects

The Nylas API v3 returns a JSON response for each request that it receives. The Nylas Ruby SDK parses the JSON response and returns a response hash containing the data that the API returned, and a string that represents the original request ID. You can use this string for debugging and troubleshooting, as necessary.

List request responses include the same data, but the response hash contains an array of the data that was returned from the API. If there are multiple pages of data, the response hash also contains a next_cursor key that includes a token representing the next page of data. You can extract this token and use it as a query parameter in a request for the next page of data.

🛠️ Pagination features are coming to the Nylas Ruby SDK soon!

Standard error objects

The Nylas API v3 includes standard error objects for all requests. The Nylas Ruby SDK includes two superclass error classes in v6:

  • AbstractNylasApiError: Used for errors returned by the API.
  • AbstractNylasSdkError: Used for errors returned by the SDK.

The AbstractNylasApiError class includes two subclasses:

  • NylasOAuthError: Used for API errors that are returned from OAuth endpoints.
  • NylasApiError: Used for all other Nylas API errors.

The Ruby SDK extracts error details from the request response and stores them in an error object, along with the associated request ID and HTTP status code.

Currently, the AbstractNylasSdkError class has only one subclass: the NylasSdkTimeoutError, which is thrown when a request times out.

Example: Error handling

The following example demonstrates how to make a request to create a new Event and handle any errors that may occur.

require 'nylas'

nylas = Nylas::API.new(
  api_key: "NYLAS_APP_KEY",
)

begin
  # Build the create Event request.
  create_event_request = nylas.events.create(
    identifier: "GRANT_ID",
    query_params: {
      calendar_id: "CALENDAR_ID", # A Calendar ID is required.
    },
    request_body: {
      when: {
        start_time: 1686765600,
        end_time: 1686769200,
      }, # A "When" type is required.
      title: "My Event", # Title is optional.
      description: "My event description", # Description is optional.
      location: "My event location", # Location is optional.
    }
  )
rescue Nylas::NylasApiError => e
  # Handle the error.
  puts e.message
  puts e.request_id
  puts e.status_code
rescue Nylas::NylasSdkTimeoutError => e
  # Handle the error.
  puts e.message
  puts e.url
end

Authentication changes in the Ruby SDK v6

The authentication methods available in the Ruby SDK v6 reflect those available in the new Nylas API v3.

While you can only create and manage your application's connectors (formerly known as "integrations") in the v3 Dashboard, you can manage almost everything else directly from the Ruby SDK. This includes managing Grants, auth callback URIs (redirect URIs), and OAuth tokens, and authenticating your users.

The Nylas Ruby SDK v6 offers two main methods for authenticating users to your Nylas application:

  • Auth#urlForOAuth2: Returns the redirect URL for authentication with Nylas' OAuth 2.0 implementation.
  • Auth#exchangeCodeForToken: Exchanges an authorization code that Nylas returned from an authentication redirect for an access token from the OAuth provider.

Nylas' response to the Auth#exchangeCodeForToken method includes an access token and information about the Grant that was created.

You do not need to use a grant_id to make a request. Instead, you can use a Grant's associated email address as the identifier for the account. If you prefer to use the grant_id, you can extract it from the CodeExchangeResponse object and use it.

Example: Authenticate a user

The following example demonstrates how to authenticate a user into a Nylas application.

require 'nylas'

nylas = Nylas::API.new(
  api_key: "NYLAS_APP_KEY",
)

# Build the URL for authentication.
auth_url = nylas.auth.url_for_oauth2(
  client_id: "CLIENT_ID",
  redirect_uri: "REDIRECT_URI",
  login_hint: "[email protected]"
)

# Write code here to redirect the user to the URL and parse the code.
...

# Exchange the code for an access token.
code_exchange_response = nylas.auth.exchange_code_for_token({
  redirect_uri: "REDIRECT_URI",
  client_id: "CLIENT_ID",
  client_secret: "CLIENT_SECRET",
  code: "CODE"
})

# Use either the email address that was authenticated or the Grant ID from the response as the identifier.
response_with_email = nylas.calendars.list(
  identifier: "[email protected]"
)

response_with_grant = nylas.calendars.list(
  identifier: code_exchange_response.grant_id
)

What's next?