diff --git a/README.md b/README.md index f9d3307..f923483 100644 --- a/README.md +++ b/README.md @@ -1,123 +1,190 @@ - - Aimeos logo - +
+ + Nylas + -# Nylas Python SDK +

Nylas Python SDK

-[![PyPI - Version](https://img.shields.io/pypi/v/nylas)](https://pypi.org/project/nylas/) -[![codecov](https://codecov.io/gh/nylas/nylas-python/branch/main/graph/badge.svg?token=HyxGAn5bJR)](https://codecov.io/gh/nylas/nylas-python) +

+ The official Python SDK for Nylas โ€” the infrastructure that powers communications +

-This is the GitHub repository for the Nylas Python SDK. The repo is primarily for anyone who wants to install the SDK from source or make contributions to it. +

+ version + code coverage + downloads + license +

-If you're looking to use Python to access the Nylas Email, Calendar, or Contacts APIs, see our [Python SDK Quickstart guide](https://docs.nylas.com/docs/quickstart-python). +

+ ๐Ÿ“– SDK Guide ยท + ๐Ÿ“š API Reference ยท + ๐Ÿš€ Sign up ยท + ๐Ÿ’ก Samples ยท + ๐Ÿ’ฌ Forum +

+
-The Nylas platform provides REST APIs for [Email](https://docs.nylas.com/docs/quickstart-email), [Calendar](https://docs.nylas.com/docs/quickstart-calendar), and [Contacts](https://docs.nylas.com/docs/quickstart-contacts), and the Python SDK is the quickest way to build your integration using Python. +
-Here are some resources to help you get started: +The official Python SDK for [Nylas](https://developer.nylas.com/docs/v3/) โ€” the infrastructure that powers communications. Integrate with Gmail, Microsoft, IMAP, Zoom, and 250+ email, calendar, and meeting providers in 5 minutes. Covers [Email](https://developer.nylas.com/docs/v3/email/), [Calendar](https://developer.nylas.com/docs/v3/calendar/), [Contacts](https://developer.nylas.com/docs/v3/email/contacts/), [Scheduler](https://developer.nylas.com/docs/v3/scheduler/), [Notetaker](https://developer.nylas.com/docs/v3/notetaker/), and [Agent Accounts](https://developer.nylas.com/docs/v3/agent-accounts/). -- [Sign up for a free Nylas account](https://dashboard.nylas.com/register). -- Follow the [Nylas API v3 Quickstart guide](https://developer.nylas.com/docs/v3-beta/v3-quickstart/). -- Browse the [Nylas SDK reference docs](https://nylas-python-sdk-reference.pages.dev/). -- Browse the [Nylas API reference docs](https://developer.nylas.com/docs/api/). -- See our code samples in the [Nylas Samples repo](https://github.com/orgs/nylas-samples/repositories?q=&type=all&language=python). +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**](https://developer.nylas.com/docs/v3/sdks/python/) on developer.nylas.com. -If you have any questions about the Nylas platform, please reach out to support@nylas.com. +## Get started -## โš™๏ธ Install +1. [Sign up for a free Nylas account](https://dashboard-v3.nylas.com/register) and grab your API key from the [Nylas Dashboard](https://dashboard-v3.nylas.com/). +2. Read the [Getting started guide](https://developer.nylas.com/docs/v3/getting-started/) for the core concepts (applications, grants, API keys). +3. Install the SDK and make your first request โ€” see below. -The Nylas Python SDK is available via pip: +You can also bootstrap from the terminal: ```bash -pip install nylas --pre +brew install nylas/nylas-cli/nylas +nylas init ``` -To install the SDK from source, clone this repo and run the install script: +More options in the [CLI getting-started guide](https://cli.nylas.com/guides/getting-started). + +## โš™๏ธ Install + +> **Requirements:** Python 3.8 or later. ```bash -git clone https://github.com/nylas/nylas-python.git && cd nylas-python -python setup.py install +pip install nylas ``` -## โšก๏ธ Usage +To install from source: -Before you use the Nylas Python SDK, you must first [create a Nylas account](https://dashboard.nylas.com/register). Then, follow our [API v3 Quickstart guide](https://developer.nylas.com/docs/v3-beta/v3-quickstart/) to set up your first app and get your API keys. +```bash +git clone https://github.com/nylas/nylas-python.git +cd nylas-python +pip install -e . +``` -For code samples and example applications, take a look at our [Python repos in the Nylas Samples collection](https://github.com/orgs/nylas-samples/repositories?q=&type=all&language=python). +### Runtime support -### ๐Ÿš€ Make your first request +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. -After you've installed and set up the Nylas Python SDK, you can make your first API request. To do so, use the `Client` class from the `nylas` package. +## โšก๏ธ Usage -The SDK is organized into different resources, each of which has methods to make requests to the Nylas API. Each resource is available through the `Client` object that you configured with your API key. For example, you can use this code to get a list of Calendars: +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](https://developer.nylas.com/docs/dev-guide/platform/data-residency/). ```python +import os from nylas import Client nylas = Client( - api_key="API_KEY", + 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 ) +``` -calendars, request_id, next_cursor = nylas.calendars.list("GRANT_ID") - -event, request_id = nylas.events.create( - identifier="GRANT_ID", - request_body={ - "title": "test title", - "description": "test description", - "when": { - "start_time": start_unix_timestamp, - "end_time": end_unix_timestamp, - } - }, - query_params={"calendar_id": "primary", "notify_participants": True}, - ) -) +Once initialized, use it to make requests against a [grant](https://developer.nylas.com/docs/v3/auth/) (an authenticated end-user account): -event, request_id = nylas.events.find( - identifier="GRANT_ID", - event_id=event.id, - query_params={ - "calendar_id": "primary", - }, +```python +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`](https://github.com/lidatong/dataclasses-json) dataclasses, so every payload is fully type-hinted and supports `to_dict()` / `from_dict()`. -nylas.events.destroy("GRANT_ID", event.id, {"calendar_id": "primary"}) +### 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. + +```python +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) ``` -## ๐Ÿ“š Documentation +Step-by-step walkthroughs in the SDK guide: -This SDK makes heavy use of [Python 3 dataclasses](https://realpython.com/python-data-classes/) to define the REST resources and request/response schemas of the Nylas APIs. The Client object is a wrapper around all of these resources and is used to interact with the corresponding APIs. Basic CRUD operations are handled by the `create()`, `find()`, `list()`, `update()`, and `destroy()` methods on each resource. Resources may also have other methods which are all detailed in the [reference guide for the Python SDK](https://nylas-python-sdk-reference.pages.dev/). In the code reference, start at `client`, and then `resources` will give more info on available API call methods. `models` is the place to find schemas for requests, responses, and all Nylas object types. +- [Send messages](https://developer.nylas.com/docs/v3/sdks/python/send-email/) +- [Read messages and threads](https://developer.nylas.com/docs/v3/sdks/python/read-messages-threads/) +- [Manage events on a calendar](https://developer.nylas.com/docs/v3/sdks/python/manage-events/) +- [Manage contacts](https://developer.nylas.com/docs/v3/sdks/python/manage-contacts/) +- [Manage folders and labels](https://developer.nylas.com/docs/v3/sdks/python/manage-folders-labels/) -While most resources are accessed via the top-level Client object, note that `auth` contains the sub-resource `grants` as well as a collection of other auth-related API calls. +### Debugging -You'll want to catch `nylas.models.errors.NylasAPIError` to handle errors. +To inspect the raw HTTP traffic the SDK sends, turn on `requests`-level logging: -Have fun!! +```python +import logging -## โœจ Upgrade from v5.x +logging.basicConfig(level=logging.DEBUG) +logging.getLogger("urllib3").setLevel(logging.DEBUG) +``` -See [UPGRADE.md](UPGRADE.md) for instructions on upgrading from v5.x to v6.x. +## ๐Ÿ’ก Examples -## ๐Ÿ’™ Contribute +Runnable examples live in [`examples/`](examples/) โ€” including [send email](examples/send_email_demo/), [inline attachments](examples/inline_attachment_demo/), [folders](examples/folders_demo/), [import events](examples/import_events_demo/), [Notetaker API](examples/notetaker_api_demo/), [Notetaker calendar](examples/notetaker_calendar_demo/), [message fields](examples/message_fields_demo/), [metadata fields](examples/metadata_field_demo/), [provider errors](examples/provider_error_demo/), [response headers](examples/response_headers_demo/), [`select` parameter](examples/select_param_demo/), [special characters](examples/special_characters_demo/), [hidden folders](examples/include_hidden_folders_demo/), and [plain text](examples/is_plaintext_demo/). -Please refer to [Contributing](Contributing.md) for information about how to make contributions to this project. We welcome questions, bug reports, and pull requests. +For full sample apps and product quickstarts, browse [**nylas-samples** on GitHub](https://github.com/orgs/nylas-samples/repositories?q=python) โ€” every official SDK has Email, Calendar, Contacts, Scheduler, and Webhooks quickstarts. -## ๐Ÿ› ๏ธ Debugging +## ๐Ÿค– AI agents -It can sometimes be helpful to turn on request logging during development. Adding the following snippet to your code that calls the SDK should get you sorted: +[nylas/skills](https://github.com/nylas/skills) drops Nylas into Claude Code, Cursor, Codex, and other agents that support the skills format: +```bash +npx skills add nylas/skills +/plugin marketplace add nylas/skills # Claude Code ``` -import logging -import requests -# Set up logging to print out HTTP request information -logging.basicConfig(level=logging.DEBUG) -requests_log = logging.getLogger("requests.packages.urllib3") -requests_log.setLevel(logging.DEBUG) -requests_log.propagate = True +The CLI also installs an MCP server for Claude Desktop, Claude Code, Cursor, Windsurf, or VS Code: + +```bash +brew install nylas/nylas-cli/nylas +nylas mcp install ``` +Walkthrough: [give AI agents email access via MCP](https://cli.nylas.com/guides/give-ai-agents-email-access-via-mcp). + +## ๐Ÿ“š Reference + +- **SDK guide:** [developer.nylas.com/docs/v3/sdks/python](https://developer.nylas.com/docs/v3/sdks/python/) +- **API reference:** [developer.nylas.com/docs/api/v3](https://developer.nylas.com/docs/api/v3/) +- **Python SDK reference:** [nylas-python-sdk-reference.pages.dev](https://nylas-python-sdk-reference.pages.dev/) โ€” generated method/class docs for this SDK +- **Webhooks (notifications):** [developer.nylas.com/docs/v3/notifications](https://developer.nylas.com/docs/v3/notifications/) +- **Auth flows:** [developer.nylas.com/docs/v3/auth](https://developer.nylas.com/docs/v3/auth/) +- **Dev guide & best practices:** [developer.nylas.com/docs/dev-guide](https://developer.nylas.com/docs/dev-guide/) +- **Changelog:** [CHANGELOG.md](CHANGELOG.md) + +## โœจ Upgrading + +See [`CHANGELOG.md`](CHANGELOG.md) for per-release notes. Older upgrade guidance (v5.x โ†’ v6.x) lives in [`UPGRADE.md`](UPGRADE.md). + +## ๐Ÿ’™ Contributing + +Issues, ideas, and pull requests welcome โ€” see [Contributing.md](Contributing.md). Before opening a large change, please open an issue or post in the [forum](https://forums.nylas.com) 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](https://www.nylas.com/security/vulnerability-disclosure-policy/). + +## ๐Ÿ”— Other Nylas SDKs + +- [nylas-nodejs](https://github.com/nylas/nylas-nodejs) ยท `npm install nylas` +- [nylas-ruby](https://github.com/nylas/nylas-ruby) ยท `gem install nylas` +- [nylas-java](https://github.com/nylas/nylas-java) ยท Maven / Gradle (Kotlin too) + ## ๐Ÿ“ License -This project is licensed under the terms of the MIT license. Please refer to [LICENSE](LICENSE) for the full terms. +MIT โ€” see [LICENSE](LICENSE). diff --git a/diagrams/nylas-logo.png b/diagrams/nylas-logo.png new file mode 100644 index 0000000..87ad1f1 Binary files /dev/null and b/diagrams/nylas-logo.png differ