@nylas/openclaw-nylas-plugin

@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, draft, and manage threads and folders (Gmail, Outlook, IMAP/SMTP)
• Calendar — List calendars, create/update/delete events, check participant availability
• Contacts — Search and retrieve contacts from connected accounts
• Auto-Discovery — Provide only an API key; grant ID, client ID, and org are resolved automatically
• 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

• Create Nylas Account — Sign up at https://dashboard-v3.nylas.com
• Create Application — All apps > Create new app > Choose region (US/EU)
• Get API Key — API Keys section > Create new key
• Add Grants — Grants section > Add Account > Authenticate your email accounts
• Grant IDs are auto-discovered — The plugin resolves them from just the API key

Quick Start

Standalone (npm package)

npm install @nylas/openclaw-nylas-plugin

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

// Auto-discovers grant ID, client ID, and org 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: "[e-mail]" }],
  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();

Installation as a Plugin

openclaw plugins install @nylas/openclaw-nylas-plugin

# 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

Local Development (link mode)

openclaw plugins install --link ~/Code/openclaw-nylas-plugin
openclaw config set 'plugins.entries.nylas.config.apiKey' 'nyl_v0_your_key_here'

Legacy Platforms (Moltbot / Clawdbot)

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

API Reference

Email

Method / Tool	Description
listMessages / nylas_list_emails	List and search emails with filters (folder, from, subject, date, unread, starred)
getMessage / nylas_get_email	Get full email content by message ID
sendMessage / nylas_send_email	Send email with to, cc, bcc, subject, and HTML body
createDraft / nylas_create_draft	Create an email draft
listThreads / nylas_list_threads	List email threads (conversations)
listFolders / nylas_list_folders	List email folders (INBOX, SENT, DRAFTS, etc.)

Calendar

Method / Tool	Description
listCalendars / nylas_list_calendars	List all available calendars
listEvents / nylas_list_events	List and filter events by date range
getEvent / nylas_get_event	Get event details by ID
createEvent / nylas_create_event	Create event with attendees, location, and recurrence
updateEvent / nylas_update_event	Update an existing event
deleteEvent / nylas_delete_event	Delete an event
checkAvailability / nylas_check_availability	Check free/busy availability for participants

Contacts

Method / Tool	Description
listContacts / nylas_list_contacts	List and search contacts
getContact / nylas_get_contact	Get contact details by ID

Account Discovery

Method / Tool	Description
autoDiscoverGrant / nylas_discover_grants	Discover all authenticated email accounts (grants) for the API key

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

Testing

# Unit tests (mocked, no API key needed)
npm test

# Live integration tests (requires NYLAS_API_KEY)
NYLAS_API_KEY=nyl_v0_... LIVE=1 npm run test:live

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

Links

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

License

MIT