{"id":8366,"library":"nylas","title":"Nylas Python SDK","description":"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.","status":"active","version":"6.14.3","language":"en","source_language":"en","source_url":"https://github.com/nylas/nylas-python","tags":["email","calendar","contacts","api-client","oauth","productivity","integrations"],"install":[{"cmd":"pip install nylas","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Client","correct":"from nylas import Client"},{"note":"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.","wrong":"from nylas import APIClient","symbol":"APIClient","correct":"This class is deprecated in v6.x. Use `Client` instead."},{"note":"It is recommended to catch `NylasAPIError` for handling API-related errors.","symbol":"NylasAPIError","correct":"from nylas.models.errors import NylasAPIError"}],"quickstart":{"code":"import os\nfrom nylas import Client\nfrom nylas.models.errors import NylasAPIError\n\n# Ensure environment variables are set for authentication\nNYLAS_API_KEY = os.environ.get('NYLAS_API_KEY', 'YOUR_NYLAS_API_KEY')\nNYLAS_API_URI = os.environ.get('NYLAS_API_URI', 'https://api.us.nylas.com') # Or https://api.eu.nylas.com\nNYLAS_GRANT_ID = os.environ.get('NYLAS_GRANT_ID', 'YOUR_NYLAS_GRANT_ID')\n\nif NYLAS_API_KEY == 'YOUR_NYLAS_API_KEY' or NYLAS_GRANT_ID == 'YOUR_NYLAS_GRANT_ID':\n    print(\"Please set NYLAS_API_KEY and NYLAS_GRANT_ID environment variables or replace placeholders.\")\nelse:\n    try:\n        # Initialize the Nylas client\n        nylas = Client(\n            api_key=NYLAS_API_KEY,\n            api_uri=NYLAS_API_URI\n        )\n\n        # Example: List calendars for the authenticated grant\n        print(f\"Attempting to list calendars for Grant ID: {NYLAS_GRANT_ID}\")\n        calendars, request_id, next_cursor = nylas.calendars.list(identifier=NYLAS_GRANT_ID)\n\n        if calendars:\n            print(\"Successfully retrieved calendars:\")\n            for calendar in calendars:\n                print(f\"  - {calendar.name} (ID: {calendar.id}, Read-only: {calendar.read_only})\")\n        else:\n            print(\"No calendars found for this grant.\")\n\n    except NylasAPIError as e:\n        print(f\"Nylas API Error: {e.status_code} - {e.message}\")\n        print(f\"Details: {e.error_response}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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'.","severity":"breaking","affected_versions":"<6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All v6.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All v6.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<6.14.2"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"nylas.models.errors.NylasAPIError: 401 Unauthorized (invalid_client or invalid_grant)"},{"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.","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.","error":"nylas.models.errors.NylasAPIError: 403 Forbidden (insufficient_scope)"},{"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.","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.","error":"UnicodeEncodeError: 'ascii' codec can't encode character... (or garbled characters in output)"},{"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.","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'.","error":"AttributeError: 'Client' object has no attribute 'collections'"}]}