Registry / communication / nylas
library6.15.0pypypi✓ verified 84d ago

The Nylas Python SDK provides convenient Python bindings for interacting with the Nylas API platform (v3). It simplifies access to email, calendar, and contacts functionalities, abstracting away direct HTTP requests. Currently at version 6.14.3, the library maintains an active release cadence with frequent updates and bug fixes.

pip install nylas
INSTALL
IMPORT
SIG · NYLAS
N
nylas
communicationpythonv6.15.0
Install
5.4s avg
Import
1013ms
Disk
39MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v6.15.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 1.045s · 40.7MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 5.4s · import 0.982s · 41MB
39MB installed
● package 39MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
from nylas import Client
APIClient
This class is deprecated in v6.x. Use `Client` instead.
from nylas import APIClient
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.

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}")
Debug
Known issues
breakingNylas 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.
affects: <6.0.0
gotchaIncorrect `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.
affects: All v6.x
gotchaInsufficient 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.
affects: All v6.x
gotchaOlder 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.
affects: <6.14.2
Errors
Common errors & fixes
nylas.models.errors.NylasAPIError: 401 Unauthorized (invalid_client or invalid_grant)
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)
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)
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'
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.
Upgrade
Version history
6.15.0latest on PyPI · released Apr 24, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
33 hits · last 30 days
node
28
Amazon
1
OpenAI (training)
1
Resources
nylas — pip install nylas · libregistry