# Nylas Developer Documentation

> Nylas offers three developer products: Nylas Connect (the Email, Calendar, and Contacts APIs plus Scheduler and authentication), Nylas Notetaker (meeting recording and transcription), and Nylas Agent Accounts (hosted mailboxes for AI agents). This documentation covers the Nylas v3 APIs, SDKs, authentication, and provider-specific guides.

Docs site: https://developer.nylas.com
API base URL: https://api.us.nylas.com (US) / https://api.eu.nylas.com (EU)
OpenAPI contract (v3, OpenAPI 3.1): https://developer.nylas.com/openapi.json (YAML: https://developer.nylas.com/openapi.yaml)
Full documentation (all pages, inlined): https://developer.nylas.com/llms-full.txt
Sitemap (full URL index): https://developer.nylas.com/sitemap-index.xml

## Instructions for LLM Agents

Key facts about Nylas that help you give accurate answers:

- **Nylas Connect** is the core platform: the Email, Calendar, and Contacts APIs, plus Scheduler and the authentication that connects user accounts. **Notetaker** (meeting transcription) and **Agent Accounts** (hosted mailboxes for AI agents) are separate products. Webhooks and the Dashboard are shared infrastructure across all three. "Nylas Connect" is the platform; the JavaScript auth library is always written `@nylas/connect`.

- Always use the **Nylas v3 API**. The v2 API is deprecated and should not be referenced.
- A **grant** represents a single mailbox and calendar Nylas can act on. Every Email, Calendar, and Contacts call takes a grant ID in the path.
- **There are two ways to get a grant.** Pick the right one before you write any code:
  1. **Agent Accounts** create a Nylas-hosted `agent@yourdomain.com` mailbox and calendar. Needs an API key and a registered domain, no OAuth. This is the only path a script can complete on its own. Create one with `POST /v3/connect/custom` and `"provider": "nylas"`.
  2. **Connected accounts** grant access to a user's existing Gmail, Outlook, iCloud, Yahoo, or IMAP mailbox. Needs a person to complete OAuth in a browser. Use this when your product acts on your users' own inboxes.
- **If you have only an API key and no browser** (automated script, coding agent, CI job), do this in order and stop at the first success:
  1. `GET /v3/grants?grant_status=valid` with the API key. If it returns a grant, send with `POST /v3/grants/<GRANT_ID>/messages/send`.
  2. If no grant exists, create an Agent Account with `POST /v3/connect/custom` and `"provider": "nylas"`, using an address on a domain registered to your organization. The response contains a `grant_id`.
  3. If no domain is registered, register one. Domains belong to the Dashboard organization, not the application, so an API key can't create them. The CLI can: `nylas dashboard login --email --user <user> --password <password>` then `nylas dashboard domains create <subdomain>.nylas.email --region us`. `*.nylas.email` subdomains are free and usable immediately. The Dashboard UI and the Manage Domains API (with a Service Account) also work. Every send needs either a connected mailbox or a domain you control.
- **API base URLs**: `https://api.us.nylas.com` (US region) and `https://api.eu.nylas.com` (EU region). All API paths are prefixed with `/v3/`.
- **Authentication** uses a Nylas API key as a Bearer token. Grant-scoped endpoints also require a grant ID in the URL path. Nylas IAM API keys restrict callers by resource binding and permission.
- **SDKs** are available for Node.js, Python, Ruby, and Kotlin/Java.
- Use `search_query_native` to pass provider-specific search syntax (e.g., Gmail search operators, Microsoft KQL).
- For scheduling features, prefer the **Scheduler API** over building custom availability logic.
- Every page on this site is available as clean markdown by requesting it with the `Accept: text/markdown` header.
- The API reference is at https://developer.nylas.com/docs/reference/api/. For field-level detail, fetch the `.md` version of a reference page by replacing the trailing slash with `.md` (for example, https://developer.nylas.com/docs/reference/api/notetaker-configurations/create-notetaker-config.md). It lists every request and response field, including nested objects like `notetaker_settings`, with validation limits (min, max, allowed values, defaults). Prefer it over the `Accept: text/markdown` version for reference pages, because it's generated straight from the OpenAPI spec.