What is Nylas

Nylas is a unified API platform that lets you integrate email, calendar, scheduling, and transcription into your application. Instead of building and maintaining separate integrations for Gmail, Microsoft, IMAP, and other providers, you write your code once against the Nylas API and it works across all of them.

Choose your path

Two ways to get a mailbox and calendar. Pick the one that matches who owns the inbox.

Path	What you get	What it requires	Best for
Agent Accounts	A Nylas-hosted `[email protected]` mailbox and calendar, created through the API	An API key and a registered domain. No OAuth.	AI agents, system mailboxes like `support@` or `scheduling@`, automated tests, ephemeral inboxes
Connected accounts	Read and write access to a user’s existing Gmail, Outlook, iCloud, Yahoo, or IMAP account	An API key and a user to complete OAuth in a browser	Products that act on your users’ own inboxes and calendars

Both produce a grant ID, and every endpoint works the same way afterward. You can mix them in one application.

If all you have is an API key

An API key can’t complete OAuth, but it can find or create a grant. Work through these in order and stop at the first success.

1. Check the grants your application already has. List grants needs only an API key. Filter to valid ones; an invalid grant needs its user to re-authenticate first.

curl "https://api.us.nylas.com/v3/grants?grant_status=valid&limit=5" \
  -H "Authorization: Bearer $NYLAS_API_KEY"

Grants carry id, email, and provider. Match on email rather than taking the first result, then send a message:

curl -X POST "https://api.us.nylas.com/v3/grants/$GRANT_ID/messages/send" \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Your order has shipped",
    "to": [{ "name": "Dana Whitfield", "email": "[email protected]" }],
    "body": "Tracking number 1Z999AA10123456784."
  }'

Send an email covers attachments, scheduled send, tracking, and the SDK equivalents.

2. If no usable grant exists, create an Agent Account. Custom authentication with "provider": "nylas" returns a grant ID with no OAuth. The address needs a domain registered to your organization.

curl -X POST "https://api.us.nylas.com/v3/connect/custom" \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "nylas",
    "name": "Orders Bot",
    "settings": { "email": "[email protected]" }
  }'

Send with the returned grant_id as in step 1. The Agent Accounts quickstart covers display names, app passwords, and workspaces; Provisioning Agent Accounts covers doing this at scale.

3. If no domain is registered, register one. Domains belong to your Dashboard organization, not to an application, so an API key can’t create them. The CLI can, without a browser:

nylas dashboard login --email --user "$NYLAS_DASHBOARD_USER" --password "$NYLAS_DASHBOARD_PASSWORD"
nylas dashboard domains create your-application.nylas.email --region us

*.nylas.email subdomains are free and usable immediately. Match --region to your application’s region. Custom domains need DNS: register the same way, then run nylas dashboard domains dns <domain> and nylas dashboard domains verify <domain>. See Set up domains.

You can also register a domain in Organization Settings → Domains, or through the Manage Domains API with a Nylas Service Account.

Every send needs either a connected mailbox or a domain you control. Do step 3 once and steps 1 and 2 cover everything afterward.

Other starting points

Giving an agent terminal or MCP access to an inbox? The Nylas for AI Agents guides cover the CLI and MCP server, which work with either path.
Designing your integration? A Nylas Professional Services architecture review maps your email and scheduling workflows to best practices before you commit to a design you’ll build on for months.

Set up your account

Every path starts here. Pick the setup method you prefer — both get you an API key in under a minute.

Get started with the CLI — run nylas init and the interactive wizard handles everything: account creation, app setup, API key generation, and account connection.
Get started with the Dashboard — use the web UI if you prefer a visual walkthrough.

To create Agent Accounts you also need a domain. Register a free *.nylas.email trial subdomain in the Dashboard in Organization Settings → Domains, or add your own domain with a TXT and MX record.

Core concepts

A few terms you’ll see throughout the docs.

Application — the container for your integration. Holds your API keys, connected accounts, and configuration. Create one in the Dashboard or via the CLI.

API key — authenticates your server-side requests. Include it as a Bearer token in the Authorization header. Keep it secret — it grants full access to all connected accounts.

Grant — represents a single mailbox and calendar that Nylas can act on. You get a grant ID when a user connects an existing account through OAuth, or when you create an Agent Account. Pass it in the request path: /v3/grants/<GRANT_ID>/messages.

Connector — configures how Nylas authenticates with a specific provider (e.g., your Google Cloud OAuth credentials). Sandbox apps come with pre-configured connectors.

Providers — Nylas supports Google, Microsoft, Exchange (EWS), iCloud, IMAP, Yahoo, and Zoom through a single API. See the provider guides for provider-specific details.

Explore the APIs

Once you’re set up, dive into the product area you need:

Email — read, send, and manage messages, threads, folders, and attachments
Calendar — manage calendars, events, and availability
Scheduler — add embeddable scheduling to your app
Notetaker — transcribe and summarize meetings
Agent Accounts — spin up Nylas-hosted email and calendar mailboxes programmatically
Notifications — receive real-time webhooks when data changes
Authentication — connect user accounts with OAuth
API reference — full endpoint documentation