# AI prompts for building with Nylas

Source: https://developer.nylas.com/docs/v3/getting-started/ai-prompts/

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](https://github.com/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.

```bash [nylasSkill-Skills CLI]
# Install both Nylas skills (API + CLI)
npx skills add nylas/skills

# Or install individually
npx skills add nylas/skills/nylas-api
npx skills add nylas/skills/nylas-cli
```

```text [nylasSkill-Claude Code plugin]
/plugin marketplace add nylas/skills
/plugin install nylas-skills
```

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`](https://developer.nylas.com/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`](https://developer.nylas.com/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.

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

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

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

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

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

```md
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.

````md
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

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.

````md
## 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: "alice@example.com" }],
    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:billing@stripe.com", 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.

````md
## 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: "alice@example.com" }],
  },
  queryParams: { calendarId: "primary" },
});
```

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

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.

````md
## 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](/docs/v3/getting-started/cli/)** -- run `nylas init` to create an account, generate an API key, and connect a test account.
- **[Get started with the Dashboard](/docs/v3/getting-started/dashboard/)** -- do the same steps through the web UI.

## What's next

- **[Guide for AI coding agents](/docs/v3/getting-started/coding-agents/)** -- detailed rules and patterns for coding agents building with Nylas
- **[Email API quickstart](/docs/v3/getting-started/email/)** -- send and read email with full SDK examples in all languages
- **[Calendar API quickstart](/docs/v3/getting-started/calendar/)** -- schedule meetings and check availability
- **[Notetaker API quickstart](/docs/v3/getting-started/notetaker/)** -- record meetings and get transcripts
- **[API reference](/docs/reference/api/)** -- full endpoint documentation