# What is Nylas

Source: https://developer.nylas.com/docs/v3/getting-started/

Nylas is a unified API platform that lets you integrate [email](/docs/v3/email/), [calendar](/docs/v3/calendar/), [scheduling](/docs/v3/scheduler/), and [transcription](/docs/v3/notetaker/) 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](/docs/v3/getting-started/agent-accounts/)** | A Nylas-hosted `agent@yourdomain.com` 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](/docs/v3/getting-started/email/)** | 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 |

> **Info:** 
> **No human in the loop?** Use [Agent Accounts](/docs/v3/getting-started/agent-accounts/). OAuth needs a person in a browser, so a script can't finish it. `POST /v3/connect/custom` with `"provider": "nylas"` returns a grant ID immediately.

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](/docs/reference/api/manage-grants/get-all-grants/) needs only an API key. Filter to valid ones; an `invalid` grant needs its user to re-authenticate first.

```bash
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](/docs/reference/api/messages/send-message/):

```bash
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": "dana.whitfield@example.com" }],
    "body": "Tracking number 1Z999AA10123456784."
  }'
```

[Send an email](/docs/v3/email/send-email/) covers attachments, scheduled send, tracking, and the SDK equivalents.

**2. If no usable grant exists, create an Agent Account.** [Custom authentication](/docs/reference/api/manage-grants/byo_auth/) with `"provider": "nylas"` returns a grant ID with no OAuth. The address needs a domain registered to your organization.

```bash
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": "orders@your-application.nylas.email" }
  }'
```

Send with the returned `grant_id` as in step 1. The [Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/) covers display names, app passwords, and workspaces; [Provisioning Agent Accounts](/docs/v3/agent-accounts/provisioning/) 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](https://cli.nylas.com/) can, without a browser:

```bash
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](/docs/v3/agent-accounts/dns-provider-setup/).

You can also register a domain in [Organization Settings → Domains](https://dashboard-v3.nylas.com/organization/domains), or through the [Manage Domains API](/docs/v3/email/domains/) with a [Nylas Service Account](/docs/v3/auth/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](/docs/v3/getting-started/cli-for-agents/) guides cover the CLI and MCP server, which work with either path.
- **Designing your integration?** A Nylas [Professional Services](/docs/support/professional-services/#architecture-design-and-workflow-review) 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](/docs/v3/getting-started/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](/docs/v3/getting-started/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](https://dashboard-v3.nylas.com/organization/domains), or [add your own domain](/docs/v3/agent-accounts/dns-provider-setup/) 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](https://dashboard-v3.nylas.com) or via the [CLI](https://cli.nylas.com).

**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](/docs/v3/agent-accounts/). 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](/docs/provider-guides/) for provider-specific details.

## Explore the APIs

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

- **[Email](/docs/v3/email/)** -- read, send, and manage messages, threads, folders, and attachments
- **[Calendar](/docs/v3/calendar/)** -- manage calendars, events, and availability
- **[Scheduler](/docs/v3/scheduler/)** -- add embeddable scheduling to your app
- **[Notetaker](/docs/v3/notetaker/)** -- transcribe and summarize meetings
- **[Agent Accounts](/docs/v3/agent-accounts/)** -- spin up Nylas-hosted email and calendar mailboxes programmatically
- **[Notifications](/docs/v3/notifications/)** -- receive real-time webhooks when data changes
- **[Authentication](/docs/v3/auth/)** -- connect user accounts with OAuth
- **[API reference](/docs/reference/api/)** -- full endpoint documentation