Nylas Python SDK

The official Python SDK for Nylas — the infrastructure that powers communications

📖 SDK Guide · 📚 API Reference · 🚀 Sign up · 💡 Samples · 💬 Forum

The official Python SDK for Nylas — the infrastructure that powers communications. Integrate with Gmail, Microsoft, IMAP, Zoom, and 250+ email, calendar, and meeting providers in 5 minutes. Covers Email, Calendar, Contacts, Scheduler, Notetaker, and Agent Accounts.

This repository is for contributors and anyone installing the SDK from source. If you just want to use the SDK in your app, head straight to the Python SDK guide on developer.nylas.com.

Get started

1. Sign up for a free Nylas account and grab your API key from the Nylas Dashboard.
2. Read the Getting started guide for the core concepts (applications, grants, API keys).
3. Install the SDK and make your first request — see below.

You can also bootstrap from the terminal:

brew install nylas/nylas-cli/nylas
nylas init

More options in the CLI getting-started guide.

⚙️ Install

Requirements: Python 3.8 or later.

pip install nylas

To install from source:

git clone https://github.com/nylas/nylas-python.git
cd nylas-python
pip install -e .

Runtime support

Tested on CPython 3.8+. Runs on standard servers as well as serverless platforms like AWS Lambda, Google Cloud Functions, and Vercel — install nylas like any other dependency in your deployment package.

⚡️ Usage

You access Nylas resources (messages, calendars, events, contacts, …) through an instance of Client. Initialize it with your API key — and optionally an api_uri matching your data residency.

import os
from nylas import Client

nylas = Client(
    api_key=os.environ["NYLAS_API_KEY"],
    api_uri=os.environ.get("NYLAS_API_URI", "https://api.us.nylas.com"),
    timeout=30,  # optional, in seconds
)

Once initialized, use it to make requests against a grant (an authenticated end-user account):

calendars, request_id, next_cursor = nylas.calendars.list(
    identifier=os.environ["NYLAS_GRANT_ID"],
)
print(calendars)

Resources expose a consistent CRUD surface — create(), find(), list(), update(), destroy() — plus resource-specific methods (e.g. messages.send(), events.send_rsvp()). Request and response models are dataclasses-json dataclasses, so every payload is fully type-hinted and supports to_dict() / from_dict().

Error handling

The SDK raises typed exceptions you can catch and inspect. Every API error carries a request_id and status_code — include both when filing a support ticket so we can trace the request end-to-end.

from nylas import Client
from nylas.models.errors import (
    NylasApiError,
    NylasOAuthError,
    NylasSdkTimeoutError,
)

try:
    nylas.calendars.list(identifier=grant_id)
except NylasApiError as err:
    print(err.status_code, err.type, str(err), err.request_id)
except NylasOAuthError as err:
    print(err.error, err.error_code, err.error_description)
except NylasSdkTimeoutError as err:
    print("Timed out:", err.url, err.timeout)

Step-by-step walkthroughs in the SDK guide:

• Send messages
• Read messages and threads
• Manage events on a calendar
• Manage contacts
• Manage folders and labels

Debugging

To inspect the raw HTTP traffic the SDK sends, turn on requests-level logging:

import logging

logging.basicConfig(level=logging.DEBUG)
logging.getLogger("urllib3").setLevel(logging.DEBUG)

💡 Examples

Runnable examples live in examples/ — including send email, inline attachments, folders, import events, events batch, Notetaker API, Notetaker calendar, message fields, metadata fields, provider errors, response headers, select parameter, special characters, hidden folders, and plain text.

For full sample apps and product quickstarts, browse nylas-samples on GitHub — every official SDK has Email, Calendar, Contacts, Scheduler, and Webhooks quickstarts.

🤖 AI agents

nylas/skills drops Nylas into Claude Code, Cursor, Codex, and other agents that support the skills format:

npx skills add nylas/skills
/plugin marketplace add nylas/skills   # Claude Code

The CLI also installs an MCP server for Claude Desktop, Claude Code, Cursor, Windsurf, or VS Code:

brew install nylas/nylas-cli/nylas
nylas mcp install

Walkthrough: give AI agents email access via MCP.

📚 Reference

• SDK guide: developer.nylas.com/docs/v3/sdks/python
• API reference: developer.nylas.com/docs/api/v3
• Python SDK reference: nylas-python-sdk-reference.pages.dev — generated method/class docs for this SDK
• Webhooks (notifications): developer.nylas.com/docs/v3/notifications
• Auth flows: developer.nylas.com/docs/v3/auth
• Dev guide & best practices: developer.nylas.com/docs/dev-guide
• Changelog: CHANGELOG.md

✨ Upgrading

See CHANGELOG.md for per-release notes. Older upgrade guidance (v5.x → v6.x) lives in UPGRADE.md.

💙 Contributing

Issues, ideas, and pull requests welcome — see Contributing.md. Before opening a large change, please open an issue or post in the forum so we can sanity-check the direction.

🔒 Security

Found a vulnerability? Please don't open a public issue. Report it through our Vulnerability Disclosure Policy.

🔗 Other Nylas SDKs

• nylas-nodejs · npm install nylas
• nylas-ruby · gem install nylas
• nylas-java · Maven / Gradle (Kotlin too)

📝 License

MIT — see LICENSE.