# How to install the OpenClaw Nylas plugin

Source: https://developer.nylas.com/docs/cookbook/ai/openclaw/install-plugin/

The `@nylas/openclaw-nylas-plugin` gives OpenClaw agents access to the Nylas API for email, calendar, and contacts. Once installed, your agents can send email, create calendar events, search contacts, and manage messages across Gmail, Outlook, Exchange, and any IMAP provider through a unified set of tools.

The plugin handles grant discovery automatically, so agents can work with multiple connected accounts without hardcoding grant IDs.

## Prerequisites

1. **Create Nylas account** - Sign up at [dashboard-v3.nylas.com](https://dashboard-v3.nylas.com)
2. **Create application** - All apps > Create new app > Choose region (US/EU)
3. **Get API key** - API Keys section > Create new key
4. **Add grants** - Grants section > Add Account > Authenticate your email accounts
5. **Grant IDs are auto-discovered** - The plugin resolves them from just the API key

## Install the plugin

You can install the plugin through the OpenClaw CLI or directly with npm.

### Install with OpenClaw CLI

```bash [installPlugin-OpenClaw CLI]
openclaw plugins install @nylas/openclaw-nylas-plugin
openclaw gateway restart
```

### Install with npm

```bash
npm install @nylas/openclaw-nylas-plugin
```

## Configure the plugin

The plugin needs your Nylas API key to authenticate requests. You can configure it through the OpenClaw CLI or environment variables.

### Configure with OpenClaw CLI

Set your API key and optional settings through the OpenClaw config:

```bash [configPlugin-OpenClaw CLI]
# Required: set your API key
openclaw config set 'plugins.entries.nylas.config.apiKey' 'nyl_v0_your_key_here'

# Optional: set the API region (defaults to US)
openclaw config set 'plugins.entries.nylas.config.apiUri' 'https://api.us.nylas.com'

# Optional: set a default timezone
openclaw config set 'plugins.entries.nylas.config.defaultTimezone' 'America/New_York'

# Restart the gateway to apply changes
openclaw gateway restart
```

### Configure with environment variables

If you're using the plugin directly with npm (outside of OpenClaw), set these environment variables:

| Variable         | Required | Description                                                             |
| ---------------- | -------- | ----------------------------------------------------------------------- |
| `NYLAS_API_KEY`  | Yes      | Your API key from the [Nylas Dashboard](https://dashboard-v3.nylas.com) |
| `NYLAS_GRANT_ID` | No       | Explicit grant ID (skip auto-discovery)                                 |
| `NYLAS_API_URI`  | No       | API region endpoint (defaults to `https://api.us.nylas.com`)            |
| `NYLAS_TIMEZONE` | No       | Default timezone for calendar operations (defaults to UTC)              |

## Set up multi-account access

The plugin supports multiple connected accounts (grants) through named aliases. This lets agents reference accounts by name instead of raw grant IDs.

```bash [multiAccount-OpenClaw CLI]
openclaw config set 'plugins.entries.nylas.config.grants' '{"work":"grant-id-1","personal":"grant-id-2"}'
```

Once configured, agents can target a specific account by name when calling any tool:

```typescript
const { client, discovered } = await createNylasClient({
  apiKey: "nyl_v0_your_key_here",
});

// Use the default grant
await client.listMessages({ limit: 5 });

// Use a named grant
await client.listMessages({ grant: "work", limit: 5 });

// Use a raw grant ID
await client.listMessages({ grant: "abc123-grant-id", limit: 5 });
```

If you don't configure named grants, the plugin auto-discovers available grants from your Nylas application.

## Available tools

After installation, the plugin exposes these tools to your OpenClaw agents:

### Email tools

| Tool                 | Description                                                            |
| -------------------- | ---------------------------------------------------------------------- |
| `nylas_list_emails`  | List email messages with optional filters (folder, date range, search) |
| `nylas_get_email`    | Retrieve a single message by ID, including full body and attachments   |
| `nylas_send_email`   | Send an email with recipients, subject, body, and optional attachments |
| `nylas_create_draft` | Create a draft message without sending                                 |
| `nylas_list_threads` | List email threads with filters                                        |
| `nylas_list_folders` | List all folders and labels for the connected account                  |

### Calendar tools

| Tool                       | Description                                                              |
| -------------------------- | ------------------------------------------------------------------------ |
| `nylas_list_calendars`     | List all calendars for the connected account                             |
| `nylas_list_events`        | List calendar events with optional date range and calendar filters       |
| `nylas_get_event`          | Retrieve a single event by ID                                            |
| `nylas_create_event`       | Create a new calendar event with title, time, participants, and location |
| `nylas_update_event`       | Update an existing event                                                 |
| `nylas_delete_event`       | Delete a calendar event                                                  |
| `nylas_check_availability` | Check free/busy availability for one or more participants                |

### Contact tools

| Tool                  | Description                              |
| --------------------- | ---------------------------------------- |
| `nylas_list_contacts` | List contacts with optional search query |
| `nylas_get_contact`   | Retrieve a single contact by ID          |

### Discovery tools

| Tool                    | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `nylas_discover_grants` | Auto-discover available grants (connected accounts) for your application |

## Verify the installation

After installing and configuring the plugin, verify it's working:

```bash [verify-OpenClaw CLI]
# Check the plugin is loaded
openclaw plugins list

# Test grant discovery
openclaw run "List my connected email accounts" --plugin nylas
```

You can also verify programmatically:

```typescript
const { client, discovered } = await createNylasClient({
  apiKey: process.env.NYLAS_API_KEY!,
});

console.log(`Discovered ${discovered.length} grants`);

const calendars = await client.listCalendars();
console.log(`Found ${calendars.length} calendars`);
```

## Things to know

- **Auto-discovery** queries all grants on your Nylas application at startup. If you have many grants, set `NYLAS_GRANT_ID` or use named grants to skip discovery and reduce startup time.
- **Rate limits** apply per grant, not per plugin instance. If multiple agents share the same grant, they share the same rate limit budget. See [Rate limits best practices](/docs/dev-guide/best-practices/rate-limits/) for details.
- **The plugin uses Nylas API v3.** All tool calls go through the [Nylas v3 REST API](/docs/reference/api/), so provider-specific behaviors (folder naming, sync timing, search syntax) are the same as documented in the [provider guides](/docs/cookbook/).
- **TypeScript types** are included. If you're extending the plugin or building custom tools on top of it, you get full type safety for all Nylas objects (messages, events, contacts, grants).
- **MoltBot compatibility** is built in. The plugin works as both a standalone Node.js client and as an OpenClaw/MoltBot gateway plugin.

## What's next

- [Email API reference](/docs/api/v3/ecc/#tag--Messages) -- full endpoint documentation for messages
- [Calendar API reference](/docs/api/v3/ecc/#tag--Events) -- full endpoint documentation for events
- [Authentication overview](/docs/v3/auth/) -- learn about connecting accounts with grants
- [Webhooks](/docs/v3/notifications/) -- get real-time notifications when email or calendar data changes
- [Rate limits](/docs/dev-guide/best-practices/rate-limits/) -- understand per-grant rate limiting
- [Use cases](/docs/cookbook/use-cases/) -- end-to-end tutorials combining multiple Nylas APIs
- [Install the OpenClaw Nylas plugin with the CLI](https://cli.nylas.com/guides/install-openclaw-nylas-plugin) -- install and verify the plugin using the Nylas CLI
- [Build a personal assistant with OpenClaw](https://cli.nylas.com/guides/nylas-openclaw-personal-assistant) -- end-to-end guide for building an OpenClaw agent with email and calendar access