npm package: @mqasimca/moltbot-nylas
Description: Nylas API v3 client for Node.js — email, calendar, and contacts with auto-discovery. Send emails, manage events, search contacts. TypeScript SDK wrapper with multi-account support.
Latest version: 1.0.1

# @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.

[![npm version](https://img.shields.io/npm/v/@mqasimca/moltbot-nylas)](https://www.npmjs.com/package/@mqasimca/moltbot-nylas)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue)](https://www.typescriptlang.org/)
[![Nylas API v3](https://img.shields.io/badge/Nylas%20API-v3-purple)](https://developer.nylas.com/docs/v3/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)

## 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](https://www.npmjs.com/package/nylas).

## Quick Start

### Standalone (npm package)

```bash
npm install @mqasimca/moltbot-nylas
```

```typescript
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: "recipient@example.com" }],
  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`) |

```bash
export NYLAS_API_KEY="nyl_v0_your_key_here"
```

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

## Installation as a Moltbot/Clawdbot Plugin

```bash
# 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:

```bash
# 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)

```bash
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:

```typescript
// 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):

```bash
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)

```bash
# 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

```bash
# 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](https://dashboard.nylas.com) > 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](https://developer.nylas.com/docs/v3/)
- [Nylas Dashboard](https://dashboard.nylas.com)
- [Nylas Node SDK](https://www.npmjs.com/package/nylas)
- [Nylas Support](mailto:support@nylas.com)

## License

MIT