Nylas Python SDK

Common errors

• nylas.models.errors.NylasAPIError: 401 Unauthorized (invalid_client or invalid_grant)

  cause The API key is invalid, the `grant_id` is incorrect, an access token (for Hosted OAuth) has expired without being refreshed, or the `api_uri` does not match the application's data residency.
  fix Verify your `NYLAS_API_KEY` and `NYLAS_GRANT_ID` in the Nylas Dashboard. Ensure `NYLAS_API_URI` matches your Nylas application's region (e.g., `https://api.us.nylas.com`). Implement token refresh logic for expiring access tokens.

• nylas.models.errors.NylasAPIError: 403 Forbidden (insufficient_scope)

  cause The authenticated grant lacks the necessary OAuth scopes to perform the requested operation. This often occurs when a new feature requires additional permissions that weren't part of the initial authorization.
  fix Check the Nylas API documentation for the specific endpoint you are calling to identify required scopes. Update your application's scope configuration in the Nylas Dashboard and ensure the user re-authenticates to get a new grant with the updated scopes.

• UnicodeEncodeError: 'ascii' codec can't encode character... (or garbled characters in output)

  cause Non-ASCII characters are being incorrectly handled during serialization or deserialization, often due to an older SDK version or a misconfigured environment that defaults to a non-UTF-8 encoding.
  fix Upgrade your `nylas` SDK to version 6.14.2 or higher, as recent versions include specific fixes for UTF-8 encoding. Ensure your Python environment (e.g., system locale, `PYTHONIOENCODING`) and any external data sources consistently use UTF-8.

• AttributeError: 'Client' object has no attribute 'collections'

  cause Attempting to access a deprecated 'collections' attribute on the `Client` object in SDK v6.x. The v6.x SDK transitioned from 'Collections' to 'Resources'.
  fix Replace calls to `nylas.collections.<resource>` with `nylas.<resource>`. For example, instead of `nylas.collections.calendars`, use `nylas.calendars`. Consult the v5 to v6 migration guide for a full overview of changes.

Warnings

• breaking Nylas Python SDK v6.x (current) exclusively supports Nylas API v3. It drops support for Nylas API v2 and Python versions older than 3.8. The primary client class was renamed from `APIClient` to `Client` and the concept of 'Collections' was replaced by 'Resources'.
  Fix: Upgrade your Nylas API integration to v3 and migrate your SDK usage to the v6.x patterns. Ensure your Python environment is 3.8 or newer. Update `APIClient` imports to `Client`. Consult the official v5 to v6 migration guide.
• gotcha Incorrect `NYLAS_API_URI` for your application's data residency will result in a `401 Unauthorized` error. Nylas operates in both US and EU regions, and the API URI must match where your application is provisioned.
  Fix: Set `NYLAS_API_URI` to `https://api.us.nylas.com` for US-based applications or `https://api.eu.nylas.com` for EU-based applications. Verify your application's region in the Nylas Dashboard.
• gotcha Insufficient OAuth scopes assigned to a grant will lead to `403 Forbidden` errors when attempting specific API actions. This is common, especially with Microsoft providers, where `Mail.ReadWrite` may be required in addition to `Mail.Send` for message creation.
  Fix: Review the necessary OAuth scopes for the API calls you are making in the Nylas documentation. If you add new scopes to your Nylas application configuration, users will need to re-authenticate to issue new grants with the updated permissions.
• gotcha Older versions of the SDK (prior to v6.14.2) had issues with UTF-8 encoding for special characters (like emojis or accented letters) in JSON payloads, potentially leading to garbled text or encoding errors.
  Fix: Upgrade to `nylas` SDK version 6.14.2 or newer to benefit from fixes that ensure JSON is encoded as UTF-8 bytes, preserving special characters.

Install

• pip install nylas Install stable version

Imports

• Client

  from nylas import Client

• APIClient
  wrong:

  from nylas import APIClient

  correct:

  This class is deprecated in v6.x. Use `Client` instead.

  The `APIClient` class was used in v5.x and earlier versions of the SDK, which supported Nylas API v2. Version 6.x of the SDK exclusively supports Nylas API v3 and uses the `Client` class.
• NylasAPIError

  from nylas.models.errors import NylasAPIError

  It is recommended to catch `NylasAPIError` for handling API-related errors.

Quickstart

This quickstart initializes the Nylas Python SDK client using API key authentication and then lists the calendars associated with a given grant ID. Ensure your `NYLAS_API_KEY`, `NYLAS_API_URI`, and `NYLAS_GRANT_ID` are set as environment variables or replaced in the code.

import os
from nylas import Client
from nylas.models.errors import NylasAPIError

# Ensure environment variables are set for authentication
NYLAS_API_KEY = os.environ.get('NYLAS_API_KEY', 'YOUR_NYLAS_API_KEY')
NYLAS_API_URI = os.environ.get('NYLAS_API_URI', 'https://api.us.nylas.com') # Or https://api.eu.nylas.com
NYLAS_GRANT_ID = os.environ.get('NYLAS_GRANT_ID', 'YOUR_NYLAS_GRANT_ID')

if NYLAS_API_KEY == 'YOUR_NYLAS_API_KEY' or NYLAS_GRANT_ID == 'YOUR_NYLAS_GRANT_ID':
    print("Please set NYLAS_API_KEY and NYLAS_GRANT_ID environment variables or replace placeholders.")
else:
    try:
        # Initialize the Nylas client
        nylas = Client(
            api_key=NYLAS_API_KEY,
            api_uri=NYLAS_API_URI
        )

        # Example: List calendars for the authenticated grant
        print(f"Attempting to list calendars for Grant ID: {NYLAS_GRANT_ID}")
        calendars, request_id, next_cursor = nylas.calendars.list(identifier=NYLAS_GRANT_ID)

        if calendars:
            print("Successfully retrieved calendars:")
            for calendar in calendars:
                print(f"  - {calendar.name} (ID: {calendar.id}, Read-only: {calendar.read_only})")
        else:
            print("No calendars found for this grant.")

    except NylasAPIError as e:
        print(f"Nylas API Error: {e.status_code} - {e.message}")
        print(f"Details: {e.error_response}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")