@mqasimca/moltbot-nylas

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 a Moltbot/Clawdbot plugin

Built on the official Nylas Node SDK.

Quick Start

Standalone (npm package)

npm install @mqasimca/moltbot-nylas

import { createNylasClient } from "@mqasimca/moltbot-nylas";

// 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: "[email protected]" }],
  subject: "Hello from Nylas",
  body: "<p>Sent via @mqasimca/moltbot-nylas</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.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 Moltbot/Clawdbot Plugin

# Install the plugin
clawdbot plugins install @mqasimca/moltbot-nylas

# Restart the gateway to load the plugin
clawdbot gateway restart

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

Optional settings:

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

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

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

Local Development (link mode)

clawdbot plugins install --link ~/Code/moltbot-nylas
clawdbot config set 'plugins.entries.moltbot-nylas.config.apiKey' 'nyl_v0_your_key_here'

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):

clawdbot config set 'plugins.entries.moltbot-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
clawdbot nylas status

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

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

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

Prerequisites

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

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