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
- Sign up for a free Nylas account and grab your API key from the Nylas Dashboard.
- Read the Getting started guide for the core concepts (applications, grants, API keys).
- 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, 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.
1 maintainer
Metadata
1 maintainer
Release files for nylas 6.18.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| nylas-6.18.0.tar.gz | 73.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nylas-6.18.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 169.3 kB
Release files / nylas-6.18.0.tar.gz
| Download URL | nylas-6.18.0.tar.gz |
|---|---|
| Size | 73.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d97eab10068fa12fd08ae9e64aa33954117dc6aea17bd01b39d3699e26da4ef0
|
|
BLAKE2b-256 checksum How to use checksums |
ed8e28029e658f933641595dbc75d38d9cb9bf93fe511454a3ed19cc0e6fd761
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
Release files / nylas-6.18.0-py3-none-any.whl
| Download URL | nylas-6.18.0-py3-none-any.whl |
|---|---|
| Size | 96.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2ff1e7fc5f4b066280be31f644a2d33439325ee623927a0015f1fc45224c2a72
|
|
BLAKE2b-256 checksum How to use checksums |
1ce51371d443d6bed21d0fe96c7027515263863e76466f2f8786a8964e5bccfd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
