@nylas/openclaw-nylas-plugin

Nylas API v3 client for Node.js — send emails, manage calendar events, and search contacts with automatic account discovery. Just provide an API key and start building.

Features

• Email — List, search, read, send, reply, draft lifecycle, attachments, threads, folders, message flags, scheduled send (Gmail, Outlook, IMAP/SMTP)
• Calendar — List calendars, create/update/delete events, check availability, smart schedule (find slot + create event in one call)
• Contacts — Full CRUD: list, search, create, update, delete contacts
• Auto-Discovery — Provide only an API key; grant ID is resolved automatically (prefers real providers over virtual inbox)
• Multi-Account — Switch between accounts with named grants (e.g., work, personal)
• TypeScript — Full type safety with Zod-validated config and TypeBox tool schemas
• Standalone or Plugin — Use as an npm package or as an OpenClaw plugin (also supports legacy Moltbot/Clawdbot)

Built on the official Nylas Node SDK.

Prerequisites

1. Create Nylas Account — Sign up at 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

Installation as a Plugin

openclaw plugins install @nylas/openclaw-nylas-plugin

# Trust the plugin and expose its tools to agent sessions
openclaw config set 'plugins.allow' '["nylas"]'
openclaw config set 'tools.alsoAllow' '["nylas"]'

# Restart the gateway to load the plugin
openclaw gateway restart

Configuration

# Set your API key (only thing required — grant ID is auto-discovered)
openclaw config set 'plugins.entries.nylas.config.apiKey' 'nyl_v0_your_key_here'

# Restart the gateway to apply config changes
openclaw gateway restart

Optional settings:

# Explicit grant ID (skips auto-discovery)
openclaw config set 'plugins.entries.nylas.config.defaultGrantId' 'your-grant-id'

# API region: US or EU
openclaw config set 'plugins.entries.nylas.config.apiUri' 'https://api.us.nylas.com'  # US (default)
openclaw config set 'plugins.entries.nylas.config.apiUri' 'https://api.eu.nylas.com'  # EU

# Timezone for date/time operations
openclaw config set 'plugins.entries.nylas.config.defaultTimezone' 'America/New_York'

# Restart the gateway after any config change
openclaw gateway restart

Important notes:

• plugins.entries.nylas.enabled = true loads the plugin, but OpenClaw may still hide nylas_* tools from agent sessions unless tools.alsoAllow includes "nylas" under restrictive profiles like "coding".
• After changing tool policy, start a new agent session so the refreshed effective tool inventory is picked up cleanly.

Legacy Platforms (Moltbot / Clawdbot)

This plugin also supports Moltbot and Clawdbot. Replace openclaw with clawdbot (or moltbot) in the commands above.

Standalone (npm package)

npm install @nylas/openclaw-nylas-plugin

import { createNylasClient } from "@nylas/openclaw-nylas-plugin";

// Auto-discovers the default grant/account from just the API key
const { client, discovered } = await createNylasClient({
  apiKey: "nyl_v0_your_key_here",
});
console.log(`Connected as: ${discovered?.email}`);

// Send an email
await client.sendMessage({
  to: [{ email: "[email protected]" }],
  subject: "Hello from Nylas",
  body: "<p>Sent via @nylas/openclaw-nylas-plugin</p>",
});

// List recent emails
const emails = await client.listMessages({ limit: 5 });

// List calendars and events
const calendars = await client.listCalendars();
const events = await client.listEvents({ calendarId: "primary" });

// Search contacts
const contacts = await client.listContacts({ limit: 10 });

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | NYLAS_API_KEY | Yes | API key from dashboard-v3.nylas.com | | NYLAS_GRANT_ID | No | Explicit grant ID (skips auto-discovery) | | NYLAS_API_URI | No | API region (default: https://api.us.nylas.com) | | NYLAS_TIMEZONE | No | Default timezone (default: UTC) |

export NYLAS_API_KEY="nyl_v0_your_key_here"

// When env vars are set, no options needed
const { client } = await createNylasClient();

Standalone usage does not read OpenClaw runtime config. It uses explicit options or NYLAS_* environment variables only.

API Reference

Email (17 tools)

| Tool | Description | |------|-------------| | nylas_list_emails | List and search emails with filters (folder, from, subject, date, unread, starred) | | nylas_get_email | Get full email content by message ID | | nylas_send_email | Send email with to, cc, bcc, subject, HTML body, and optional send_at for scheduled send | | nylas_reply_to_email | Reply or reply-all with proper threading (honors Reply-To header) | | nylas_create_draft | Create an email draft | | nylas_list_drafts | List email drafts with filters | | nylas_update_draft | Update an existing draft | | nylas_send_draft | Send a draft as an email | | nylas_delete_draft | Delete a draft | | nylas_update_message | Mark read/unread, star/unstar, move to folder | | nylas_get_attachment | Download an email attachment (returns base64) | | nylas_get_thread | Get a thread with all messages (supports fields=summary for AI-friendly format) | | nylas_list_threads | List email threads (conversations) | | nylas_list_folders | List email folders (INBOX, SENT, DRAFTS, etc.) | | nylas_create_folder | Create a new email folder/label | | nylas_update_folder | Rename a folder | | nylas_delete_folder | Delete a folder |

Calendar (8 tools)

| Tool | Description | |------|-------------| | nylas_list_calendars | List all available calendars | | nylas_list_events | List and filter events by date range | | nylas_get_event | Get event details by ID | | nylas_create_event | Create event with attendees, location, and conferencing | | nylas_update_event | Update an existing event | | nylas_delete_event | Delete an event | | nylas_check_availability | Check free/busy availability for participants | | nylas_smart_schedule | Find the best available slot across participants and create the event in one call |

Contacts (5 tools)

| Tool | Description | |------|-------------| | nylas_list_contacts | List and search contacts | | nylas_get_contact | Get contact details by ID | | nylas_create_contact | Create a new contact (supports comma-separated emails) | | nylas_update_contact | Update contact fields | | nylas_delete_contact | Delete a contact |

Account Discovery (1 tool)

| Tool | Description | |------|-------------| | nylas_discover_grants | Discover all authenticated email accounts (grants) for the API key |

Cross-Cutting Features

Many tools support these optional parameters:

| Parameter | Description | |-----------|-------------| | fields | "summary" for compact responses (fewer fields, smaller context) or "full" (default) on supported list/get tools | | page_token | Pass next_page_token from a previous response on paginated list tools | | grant | Named grant or grant ID for multi-account access on tools that act on a specific account |

Error Intelligence — Every error includes an action field with recovery hints for AI agents (e.g., "Use nylas_discover_grants to find valid grant IDs" on 404).

Pagination Hints — When more results are available, responses include a hint field telling the caller exactly how to get the next page.

Multi-Account Support

Switch between email accounts using named grants:

// Use the default (auto-discovered) 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 });

Configure named grants (plugin mode):

openclaw config set 'plugins.entries.nylas.config.grants' '{"work":"grant-id-1","personal":"grant-id-2"}'

Supported Email Providers

Works with any email provider connected through Nylas:

• Google — Gmail, Google Workspace
• Microsoft — Outlook.com, Office 365, Exchange
• IMAP/SMTP — Any standard mail server

CLI Commands (Plugin Mode)

# Check API connection and auto-discover grants
openclaw nylas status

# Discover all authenticated accounts
openclaw nylas discover
openclaw nylas discover --json

# Test API with a specific grant
openclaw nylas test
openclaw nylas test --grant work

# List configured and available grants
openclaw nylas grants
openclaw nylas grants --configured

Troubleshooting

"apiKey is required"

• Set your API key via env var or config: export NYLAS_API_KEY=nyl_v0_...

"No grants found"

• Add an account in the Nylas Dashboard > Grants > Add Account

401 Unauthorized

• Check that your API key is valid and not expired
• Verify the grant ID exists in your Nylas dashboard

404 Not Found

• Ensure the resource (message, event, contact) ID is correct
• Check that you're using the right grant for that resource
• Error responses include an action hint suggesting which tool to use next

Replies going to wrong recipient

• The plugin honors the Reply-To header when present (for aliases, ticketing systems, mailing lists)
• Falls back to From only when Reply-To is empty

Links

• Nylas API v3 Documentation
• Nylas Dashboard
• Nylas Node SDK
• Nylas Support

License

MIT