Only show these results:

Migrate the Nylas Python SDK from v5 to v6 beta

Version 6.0.0 of the Nylas Python 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 idiomatic and easier to use. It includes function and model documentation, 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 Python 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 Python SDK v5.x until you can start using the Nylas v3 APIs.

Migrate to Nylas Python SDK v6

The minimum Python version is now the lowest-supported long-term stable release (LTS): v3.8.

To upgrade a v5.x Nylas Python SDK to v6, use pip to download and install the new version.

pip install nylas --pre

Initialize a Nylas instance

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

from nylas import Client

nylas = Client(
    api_key="API_KEY",
)

📝 Note: The Python SDK's entry point has been changed to Client.

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

Changes to models in the Python SDK v6

Models have been completely changed in v6 of the Nylas Python SDK.

First, the SDK now includes specific models for each request to and response from the Nylas API. This change is designed to make it easier to work with the SDK.

Second, because v6 of the SDK drops support for Python versions lower than v3.8, it takes advantage of some new Python features:

  • Models that represent response objects use dataclasses. This makes them more readable and easier to use, and provides some type hinting and in-IDE hinting.
  • Response objects implement the dataclasses-json library, which provides utility functions such as to_dict() and to_json(). This allows you to use your data in different formats.
  • Models that represent request objects use TypedDicts to provide a seamless guided experience when building objects for outgoing requests.
  • Both dataclass and TypedDict classes are fully typed, meaning that you have all the information you need to make a successful API request.

Example: Calendar models

In v5.x of the Nylas Python SDK, only one Calendar object was available. It simultaneously represented a Calendar in the following states:

  • To be created.
  • To be updated.
  • To be retrieved.

This meant that all models had to be configured with all possible fields that could ever be used in any of the above scenarios. This made objects very large and difficult to anticipate as a developer.

v6 of the Python SDK has split the Calendar model into three:

  • Calendar: A model for retrieving a Calendar object.
  • CreateCalendarRequest: A model for creating a Calendar object.
  • UpdateCalendarRequest: A model for updating a Calendar object.

Making requests to the Nylas API

To make requests to the Nylas API, you use the nylas instance that you initialized during set up.

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 Calendars, you can use the calendars.list method as in the example below.

from nylas import Client

nylas = Client(
    api_key="API_KEY",
)

response = nylas.calendars.list(identifier="GRANT_ID")

Changes to requests in the Python SDK v6

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

Standard response objects

The Nylas API v3 includes standard response objects for all requests, except those made to OAuth endpoints. Generally, you'll encounter two types of response objects:

  • Response: Used for requests that return a single object, such as retrieving a single Calendar. This returns a parameterized object of the type that you requested, and a string representing the request ID.
  • ListResponse: Used for requests that return a list of objects, such as retrieving a list of Calendars. This returns a list of parameterized objects of the type that you requested, a string representing the request ID, and a next_cursor string representing the next page's token.

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

Both dataclass and TypedDict classes also support destructuring. This means that you can use code like the snippet below to manipulate your data.

from nylas import Client

nylas = Client(
    api_key="API_KEY",
)

response = nylas.calendars.list(identifier="GRANT_ID")
calendars = response.data # The list of Calendars.

# Or...

calendars, request_id = nylas.calendars.list(identifier="CALENDAR_ID") # The list of Calendars and the request ID.

Standard error objects

Like the response objects, the Nylas API v3 includes standard error objects for all requests. The Nylas Python 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 Python 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.

Pagination changes in the Python SDK v6

Pagination has changed in the Nylas API v3. In v3, if the ListResponse returns more than one page of results, Nylas sends a next_cursor parameter that contains a token for the next page.

Currently, the Nylas Python SDK v6 does not support Nylas' pagination features. Until pagination support is added, you can use the next_cursor parameter to make a request that returns the next page, as in the example below.

from nylas import Client

nylas = Client(
    api_key="API_KEY",
)

response = nylas.calendars.list(identifier="GRANT_ID")
all_calendars = list(response)

while response.next_cursor:
    response = nylas.calendars.list(identifier="GRANT_ID", query_params={"page_token": response.next_cursor})
    all_calendars.extend(response)

Authentication changes in the Python SDK v6

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

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

The Nylas Python 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.

from nylas import Client

nylas = Client(
    api_key="API_KEY",
)

# Build the URL for authentication.
auth_url = nylas.auth.url_for_oauth2({
    "client_id": "CLIENT_ID",
    "redirect_uri": "abc",
    "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({
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "code": "CODE",
    "redirect_uri": "abc"
})

# 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]")

# Or...

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

What's next?