AI prompts for building with Nylas

When using AI coding tools to build a Nylas integration, the LLM needs context about the Nylas APIs. There are three approaches: install the Nylas skill, point the tool at the docs, or paste a system prompt. Use whichever fits your tool.

Option 1: Install the Nylas skill (recommended)

The Nylas skills pre-load your coding agent with current Nylas API, CLI, and SDK context. Skills work with Claude Code, Cursor, Codex CLI, and 40+ other agents — no system prompt or URL fetching required.

The nylas-api skill covers authentication, email, calendar, contacts, webhooks, scheduler, notetaker, and SDK usage. The nylas-cli skill covers nylas init, auth, email, calendar, mcp, chat, and tui commands. Skills stay current by linking to llms.txt and fetchable doc pages.

Option 2: Point your tool at the docs

The Nylas docs are built for agents. There are three ways to consume them:

llms.txt — a curated sitemap of every key page, grouped by product area. Start here when you need to find the right doc.
llms-full.txt — every doc page concatenated into one file. Good for tools with large context windows.
Accept: text/markdown header — fetch any individual page as clean markdown. Works on every URL on developer.nylas.com. Returns an x-markdown-tokens response header with the estimated token count.

# Curated sitemap -- read this first
curl https://developer.nylas.com/llms.txt

# Full docs in one file
curl https://developer.nylas.com/llms-full.txt

# Any single page as markdown
curl -H "Accept: text/markdown" https://developer.nylas.com/docs/v3/email/

Most AI coding tools can fetch URLs. Add one of the snippets below to your tool’s rules file so it knows to read the docs on demand.

For Claude Code, add this to your project’s CLAUDE.md:

When working with Nylas APIs, read https://developer.nylas.com/llms.txt for a sitemap
of all documentation. For specific pages, fetch them with the Accept: text/markdown header:
curl -H "Accept: text/markdown" https://developer.nylas.com/docs/v3/email/

For Cursor, add this to .cursor/rules:

When building with Nylas APIs, reference https://developer.nylas.com/llms.txt for documentation.
Always use Nylas v3 (not v2). v3 uses API keys and grant IDs. v2 used access tokens and client secrets.

For GitHub Copilot, add to .github/copilot-instructions.md:

For Nylas API integration, reference: https://developer.nylas.com/llms.txt
Use Nylas v3 only. Authentication uses Bearer token with API key. Each user account is a "grant" with a grant_id.

For OpenAI Codex CLI, add to your project’s AGENTS.md or pass via --instructions:

For Nylas API integration, reference: https://developer.nylas.com/llms.txt
Use Nylas v3 only. v3 uses API keys (Bearer token) and grant IDs. Never use v2 patterns (access_token, client_secret).

For ChatGPT / OpenAI API, include in your system prompt or custom GPT instructions:

When helping with Nylas API integration, always use Nylas v3. Reference: https://developer.nylas.com/llms.txt
Key concepts: API key (Bearer token), grant_id (one per connected user account), base URL https://api.us.nylas.com.

Option 3: Paste a system prompt

If your tool doesn’t fetch URLs, or you want tighter control over context, paste one of these prompts directly.

Starter prompt (use this first)

This gives the LLM the core mental model for building with Nylas. Paste it as a system prompt or rules file.

You are building with the Nylas v3 APIs. Follow these rules:

## API basics

- Base URL: `https://api.us.nylas.com` (US) or `https://api.eu.nylas.com` (EU)
- Auth: Bearer token using the API key in the Authorization header
- Every request to user data follows the pattern: `GET/POST /v3/grants/{grant_id}/{resource}`
- A **grant** is one connected user account (Gmail, Outlook, etc). You get a grant_id when a user authenticates through OAuth.

## SDK setup

Use the official SDK for your language. Never use raw HTTP when an SDK is available.

```bash
npm install nylas        # Node.js
pip install nylas        # Python
gem install nylas        # Ruby
```

Initialize the client:

```javascript
import Nylas from "nylas";
const nylas = new Nylas({ apiKey: process.env.NYLAS_API_KEY });
```

```python
from nylas import Client
nylas = Client(os.environ["NYLAS_API_KEY"])
```

## Critical rules

- **Only use v3.** v2 is deprecated. v3 uses `api_key` and `grant_id`. If you see `access_token` or `client_secret`, that's v2 -- don't use it.
- **Never hardcode API keys.** Use environment variables and .env files excluded from version control.
- **Never expose the API key in client-side code.** All Nylas API calls must happen server-side.
- **Handle pagination.** List endpoints return `next_cursor`. Use it to fetch subsequent pages.
- **Use webhooks for real-time updates** instead of polling.

## Key endpoints

| Action | Method | Path |
|--------|--------|------|
| List messages | GET | `/v3/grants/{grant_id}/messages` |
| Send email | POST | `/v3/grants/{grant_id}/messages/send` |
| List events | GET | `/v3/grants/{grant_id}/events?calendar_id={id}` |
| Create event | POST | `/v3/grants/{grant_id}/events?calendar_id={id}` |
| Check availability | POST | `/v3/calendars/availability` |
| List calendars | GET | `/v3/grants/{grant_id}/calendars` |
| List contacts | GET | `/v3/grants/{grant_id}/contacts` |

## Documentation

- Full docs: https://developer.nylas.com/docs/v3/getting-started/
- API reference: https://developer.nylas.com/docs/reference/api/
- SDK docs: https://developer.nylas.com/docs/v3/sdks/
- Any page as markdown: `curl -H "Accept: text/markdown" https://developer.nylas.com/docs/v3/email/`

Email prompt

Paste this after the starter prompt when building email features.

## Nylas Email API

Read messages:
```javascript
const messages = await nylas.messages.list({
  identifier: grantId,
  queryParams: { limit: 10 },
});
```

Send a message:
```javascript
const sent = await nylas.messages.send({
  identifier: grantId,
  requestBody: {
    to: [{ name: "Alice", email: "[email protected]" }],
    subject: "Hello",
    body: "Email body here",
  },
});
```

Search messages (uses provider-native syntax):
```javascript
const results = await nylas.messages.list({
  identifier: grantId,
  queryParams: { search_query_native: "from:[email protected]", limit: 5 },
});
```

Key points:
- Messages are immutable -- you can't edit a sent message
- Use `threads` endpoint to get conversation view
- Attachments are accessed via separate download endpoint
- Filter with `from`, `to`, `subject`, `received_after`, `received_before`, `in` (folder), `unread`
- Docs: https://developer.nylas.com/docs/v3/email/

Calendar prompt

Paste this after the starter prompt when building calendar features.

## Nylas Calendar API

List events (calendar_id is required):
```javascript
const events = await nylas.events.list({
  identifier: grantId,
  queryParams: { calendarId: "primary", limit: 10 },
});
```

Create an event with participants:
```javascript
const event = await nylas.events.create({
  identifier: grantId,
  requestBody: {
    title: "Team sync",
    when: { startTime: startUnix, endTime: endUnix },
    participants: [{ email: "[email protected]" }],
  },
  queryParams: { calendarId: "primary" },
});
```

Check availability across users:
```javascript
const availability = await nylas.calendars.getAvailability({
  requestBody: {
    startTime: startUnix,
    endTime: endUnix,
    durationMinutes: 30,
    participants: [{ email: "[email protected]" }, { email: "[email protected]" }],
  },
});
```

Key points:
- Every event operation requires `calendar_id` as a query parameter
- Use `primary` for the user's default calendar
- Times are Unix timestamps in seconds, not milliseconds
- Nylas sends invitations to participants automatically when creating events
- RSVP via `POST /v3/grants/{grant_id}/events/{event_id}/send-rsvp`
- Docs: https://developer.nylas.com/docs/v3/calendar/

Authentication prompt

Paste this when implementing the OAuth flow to connect your users’ accounts.

## Nylas Authentication (Hosted OAuth)

The flow: Your app redirects the user to Nylas -> Nylas redirects to the email provider -> user authenticates -> Nylas redirects back to your app with a code -> you exchange the code for a grant_id.

Generate the auth URL:
```javascript
const authUrl = nylas.auth.urlForOAuth2({
  clientId: process.env.NYLAS_CLIENT_ID,
  redirectUri: "http://localhost:3000/callback",
});
// Redirect the user to authUrl
```

Handle the callback:
```javascript
const response = await nylas.auth.exchangeCodeForToken({
  clientId: process.env.NYLAS_CLIENT_ID,
  clientSecret: process.env.NYLAS_API_KEY,
  code: req.query.code,
  redirectUri: "http://localhost:3000/callback",
});
const grantId = response.grantId;
// Store grantId associated with your user
```

Key points:
- Register your callback URI in the Nylas Dashboard under Hosted Authentication
- The redirect URI in your code must exactly match what's registered in the Dashboard
- Store the grant_id -- you'll use it for all subsequent API calls for that user
- One grant = one connected email account
- Docs: https://developer.nylas.com/docs/v3/auth/hosted-oauth-apikey/

Before you begin

If you haven’t set up your Nylas account yet:

Get started with the CLI — run nylas init to create an account, generate an API key, and connect a test account.
Get started with the Dashboard — do the same steps through the web UI.

What’s next

Guide for AI coding agents — detailed rules and patterns for coding agents building with Nylas
Email API quickstart — send and read email with full SDK examples in all languages
Calendar API quickstart — schedule meetings and check availability
Notetaker API quickstart — record meetings and get transcripts
API reference — full endpoint documentation