DEV Community: Qasim

Sync and manage contacts across providers: Nylas Contacts API

Qasim — Sun, 21 Jun 2026 21:27:21 +0000

Contacts are messier than they look. A user's real address book is spread across the people they've saved by hand, the people they've emailed often enough that the provider auto-collected them, and the colleagues in their company directory. Google exposes these through the People API; Microsoft through Graph; both model the data differently and split it across sources you have to query separately.

The Nylas Contacts API unifies all of that behind one schema and one grant_id. You read saved contacts, auto-collected contacts, and directory contacts through the same endpoint, create and update entries that sync back to the provider, and organize them into groups. This post walks the contact surface from the HTTP API and the Nylas CLI, which mirrors every operation for terminal use.

I work on the CLI, so the terminal commands below are the ones I run when I'm exploring an address book.

The contact model and its three sources

A contact in Nylas carries the fields you'd expect — given_name, surname, emails, phone_numbers, company_name, job_title, notes — plus richer ones like im_addresses, physical_addresses, and web_pages. The schema is the same across providers, so a Google contact and a Microsoft contact deserialize into one struct.

The detail that trips people up is source. Every contact has one of three sources, and they mean very different things:

address_book — contacts the user saved deliberately. This is the real address book.
inbox — contacts the provider auto-collected because the user emailed them. These were never explicitly saved.
domain — contacts from the organization's directory (coworkers).

Knowing the source matters because "all contacts" usually isn't what you want. If you're building a contact picker, the inbox source can flood it with one-off recipients the user doesn't think of as contacts. Filter by source deliberately. See the Contacts API overview for the full data model.

Before you begin

You need a Nylas API key and a connected account with contacts scopes. The CLI gets you set up in two commands:

nylas init        # create an account, generate an API key
nylas auth login  # connect an account over OAuth, store the grant

After login the CLI runs against that grant by default, so the nylas contacts commands below don't need an explicit ID. For the OAuth scopes Google and Microsoft require to read and write contacts, see the authentication docs.

List contacts

Listing is the first thing you'll do. The CLI returns 50 contacts by default and lets you filter by source so you're not drowning in auto-collected addresses:

# 50 contacts, default
nylas contacts list

# Only the real, saved address book
nylas contacts list --source address_book --limit 100

The --limit flag auto-paginates once you raise it above 200. Over HTTP, the same operation is a GET against the contacts collection, with source, email, phone_number, and group as query parameters:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/contacts?source=address_book&limit=100" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

The list contacts reference documents every filter, and the response paginates with the page_token cursor just like messages and events. The CLI flags live at contacts list.

Create a contact

Creating a contact writes it back to the provider, so it shows up in the user's Google Contacts or Outlook address book too. The CLI uses friendly flag names:

nylas contacts create \
  --first-name "Jane" \
  --last-name "Smith" \
  --email "jane@company.com" \
  --phone "+1-555-123-4567" \
  --company "Acme Corp" \
  --job-title "Engineer"

One thing worth knowing: the CLI flag names are not the API field names. The CLI maps --first-name to given_name, --last-name to surname, --email to the emails array, and --phone to phone_numbers. When you call the API directly, use the API names. Note that emails and phone_numbers are arrays of objects, because a contact can have several of each:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/contacts" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "given_name": "Jane",
    "surname": "Smith",
    "company_name": "Acme Corp",
    "job_title": "Engineer",
    "emails": [{ "email": "jane@company.com", "type": "work" }],
    "phone_numbers": [{ "number": "+1-555-123-4567", "type": "work" }]
  }'

The full field list — including birthday, im_addresses, physical_addresses, manager_name, and web_pages — is in the create contact reference, and the CLI flags are at contacts create.

Those array fields come with provider-specific caps that bite if you assume everyone allows many values. IMAP, iCloud, and Yahoo accept at most one email address and one phone number per contact. Microsoft and EWS allow up to three email addresses. Microsoft caps phone numbers at two home, two work, and one mobile. So a contact with four email addresses that round-trips fine on Google will silently lose values on an iCloud account. Field types carry provider rules too: the mobile phone type is Google and Microsoft Graph only, and the other type is Google and EWS only. If you support multiple providers, store the canonical contact in your own system and treat the provider copy as a projection that may drop fields it can't represent.

Search and filter

When you need to find a contact rather than list everything, the CLI's search layers structured filters on top of the list endpoint. You can match by company, email, phone, group, or restrict to contacts that actually have an email address:

# Everyone at one company who has an email on file
nylas contacts search --company "Acme" --has-email

# A specific person by email
nylas contacts search --email "jane@company.com"

The --company filter does a partial match against the company_name field, which is handy when you don't know the exact legal name. The --has-email flag is the one I reach for most — it strips out directory or auto-collected entries that have a name but no usable email, which is exactly the noise you want gone in a contact picker. Full options are at contacts search.

Organize with contact groups

Providers expose contact groups (Google calls them labels; Outlook calls them categories) and Nylas reads them through a dedicated endpoint. Listing groups gives you the IDs you then use to filter contacts:

nylas contacts groups list

Over HTTP that's a GET to the contact-groups collection:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/contacts/groups" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

Once you have a group ID, pass it as the group filter on a contacts list or search call to get just that group's members. The list contact groups reference and the contacts groups list command cover the rest. Groups are read-mapped from the provider, so the IDs are stable references you can store.

Profile photos and sync

Contacts often have a profile photo, which Nylas serves separately from the contact record so you only fetch image bytes when you need them. The CLI downloads a contact's photo to a file:

nylas contacts photo download <contact-id> --output ./jane.jpg

The contacts photo download command handles the fetch. There's also a nylas contacts sync command that reports sync status for the account's contacts, which is useful when you've just connected a grant and want to know whether the initial contact sync has finished before you rely on the data being complete.

Limits and provider notes

Dimension	Value	Notes
Default page size	50 contacts	`--limit` auto-paginates above 200
Sources	`address_book`, `inbox`, `domain`	Filter deliberately — `inbox` is auto-collected
Providers	Google, Microsoft, and more	One contact schema across all
Multi-value fields	`emails`, `phone_numbers` are arrays	A contact can hold several of each
Groups	Read-mapped from the provider	Google labels / Outlook categories

The biggest practical gotcha is the inbox source. A user who emails a lot can accumulate thousands of auto-collected inbox contacts they never deliberately saved, so a naive "show me all contacts" pulls in a long tail of one-off recipients. Decide up front which sources your feature should surface.

Wrapping up

Contacts are deceptively simple — until you account for the three sources, the multi-value fields, and the fact that two providers model the same address book differently. Reading and writing them through one schema, with the source distinction made explicit, turns a fiddly multi-API integration into a handful of calls. The CLI gives you the same operations in the terminal, so you can inspect an address book and test a write before you build the feature around it.

Where to go next:

Contacts API overview — the full data model and the three sources
Create a contact and list contacts — endpoint references
List contact groups — groups, labels, and categories
Nylas CLI command reference — every nylas contacts subcommand

Written by Qasim Muhammad and Pouya Sanooei.

Record and transcribe meetings with the Nylas Notetaker API

Qasim — Sun, 21 Jun 2026 21:27:02 +0000

Meeting notes are the feature everyone wants and nobody wants to build. The hard part isn't the summary — an LLM handles that. The hard part is getting into the meeting: a bot that joins Zoom, Google Meet, and Microsoft Teams, survives each platform's waiting room and admission flow, records cleanly, and produces a transcript you can feed downstream. Each provider has its own join mechanics, and none of them ships a tidy "record this meeting" API.

The Nylas Notetaker API is that bot as a service. You point it at a meeting link, it joins on schedule, records, and generates a transcript, and you fetch the recording and transcript through one endpoint. This post walks the Notetaker surface from the HTTP API and the Nylas CLI, which mirrors the whole lifecycle for terminal use and quick testing.

I work on the CLI, so the terminal commands below are exactly what I run when I'm testing a notetaker against a live meeting.

Two ways to run a notetaker: grant-scoped or standalone

Before any code, there's one architectural choice worth understanding, because it changes the endpoint you call.

A grant-scoped notetaker is tied to a connected account and lives under /v3/grants/{grant_id}/notetakers. Use it when the bot acts on behalf of a specific user — it can read that user's calendar and join their meetings as them.

A standalone notetaker has no grant at all and lives under /v3/notetakers. You hand it a raw meeting link and it joins, no connected account required. This is the one to reach for when you just have a URL and want a recording — a public webinar, a meeting on an account you haven't connected, or a system that deals in links rather than users.

Same request body, same lifecycle, same media output; the only difference is whether there's a grant_id in the path. See the Notetaker overview for how both models fit together.

Before you begin

You need a Nylas API key. If you're using a grant-scoped notetaker you also need a connected account; for standalone, the API key alone is enough. The CLI gets you started:

nylas init        # create an account, generate an API key
nylas auth login  # only needed for grant-scoped notetakers

The supported meeting providers are Zoom, Google Meet, and Microsoft Teams. Any meeting link from those three works as the target.

Send a notetaker into a meeting

Creating a notetaker is one call. The only required field is the meeting link; everything else has a sensible default. The CLI joins immediately if you don't pass a time:

# Join right now
nylas notetaker create --meeting-link "https://zoom.us/j/123456789"

# Join at a specific time, with a custom display name
nylas notetaker create \
  --meeting-link "https://meet.google.com/abc-defg-hij" \
  --join-time "2026-06-23 14:00" \
  --bot-name "Acme Notetaker"

The --bot-name flag sets what the other participants see in the attendee list, which matters more than it sounds — a bot labeled "Acme Notetaker" reads as intentional, while a generic name makes people wonder who joined. The --join-time flag accepts an absolute time, a relative offset like 30m, or natural phrasing like tomorrow 9am.

Over HTTP, the request body fields are meeting_link (required), join_time, name, and meeting_settings:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/notetakers" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "meeting_link": "https://meet.google.com/abc-defg-hij",
    "name": "Acme Notetaker",
    "meeting_settings": {
      "video_recording": true,
      "audio_recording": true,
      "transcription": true
    }
  }'

For a standalone notetaker, drop the grant from the path and POST the same body to /v3/notetakers. The meeting_settings object controls what gets captured — video_recording, audio_recording, and transcription toggles. They aren't fully independent, though: if transcription is true, both video_recording and audio_recording must also be true, because the transcript is generated from the recording. So "transcript only, no recording" isn't a valid combination — you can record audio-only, but a transcript always implies a recording exists.

There's also a transcription_settings object with an expected_languages array. It's a language declaration, not translation: the hints help the speech recognizer pick between the languages you expect in the meeting, and Notetaker never translates the transcript or forces it into one language. The full request body is in the invite notetaker reference, and the CLI flags are at notetaker create.

Follow the lifecycle

A notetaker moves through states, and your app usually waits for it to finish before pulling media. The CLI's --state filter accepts friendly names — scheduled (created, waiting to join), connecting, attending (in the meeting, recording), complete (done, media ready), cancelled, and failed. The raw API state field is more granular: a notetaker object surfaces values like waiting_for_entry, processing, and available (the API's equivalent of the CLI's "complete"). The list endpoint's state query filter uses its own enum (for example media_available), so don't assume the filter value and the object's state string are spelled identically. List notetakers and filter by state to find the ones worth acting on:

# All notetakers (20 by default)
nylas notetaker list

# Only the finished ones, ready for media
nylas notetaker list --state complete

The --state filter is how you build a polling loop: ask for complete notetakers, process their media, move on. The CLI returns 20 by default and the notetaker list command documents the rest. To inspect a single notetaker's current state and metadata, use nylas notetaker show <notetaker-id>. In production, rather than polling, you'd subscribe to notetaker webhooks so Nylas tells you when a session reaches complete.

Pull the recording and transcript

Once a notetaker is complete, its media is ready. The media endpoint returns URLs for the recording (the video or audio file) and the transcript (the text). One thing to watch: these URLs expire, so download promptly rather than storing the URL and fetching it days later.

nylas notetaker media <notetaker-id>

Over HTTP, it's a GET against the notetaker's media path:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/notetakers/<NOTETAKER_ID>/media" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

The response gives you the download links; pull the bytes to your own storage immediately if you need them long-term. From there the transcript is plain text you can hand to an LLM for a summary, action items, or a searchable index. The get notetaker media reference and the notetaker media command cover the details.

Leave, cancel, or delete — they're different

This is the distinction that catches people, because the three sound interchangeable and aren't:

Leave tells an active notetaker to exit the meeting now. It stops the recording, triggers media generation, and keeps the notetaker record and its media. Use it to cleanly end a live recording early.
Cancel stops a scheduled notetaker before it ever joins. There's nothing to record, so there's no media. The API exposes this as a dedicated cancel endpoint.
Delete permanently removes the notetaker and all its media. If the notetaker is still scheduled or active, delete cancels it first, and any recording or transcript you haven't already downloaded is lost. In the CLI, cancel and rm are aliases of delete.

From the CLI:

# End a live recording but keep the media
nylas notetaker leave <notetaker-id>

# Remove a notetaker and its media
nylas notetaker delete <notetaker-id>

Reaching for delete when you meant leave permanently throws away the recording you just made, so it's worth getting right. The notetaker delete command and the API's separate leave and cancel endpoints keep these operations distinct on purpose.

Capabilities and notes

Dimension	Value	Notes
Providers	Zoom, Google Meet, Microsoft Teams	Any meeting link from these three
Models	Grant-scoped and standalone	`/v3/grants/{id}/notetakers` vs `/v3/notetakers`
Capture toggles	video, audio, transcription	`meeting_settings` flags; transcription requires both recordings on
Media URLs	Expiring	Download promptly; store your own copy
Lifecycle	scheduled → connecting → attending → complete	Simplified CLI states; the API exposes more granular values

The standalone model is the feature I'd point a new integration at first. Not needing a connected account to record a meeting removes the entire OAuth step for the common case where you already have a link, and you can always move to grant-scoped notetakers later when the bot needs to act as a specific user.

Wrapping up

The value here is that the genuinely hard part — a bot that reliably joins three different meeting platforms and comes back with clean media — is the part you don't write. You make one call with a meeting link, wait for complete, and pull a recording and transcript. The summary layer on top is a solved problem; getting a trustworthy transcript out of a live meeting was the bottleneck, and that's what the API removes. The CLI mirrors the full lifecycle, so you can record a real meeting and inspect the transcript from your terminal before committing any of it to code.

Where to go next:

Notetaker overview — grant-scoped and standalone models, lifecycle, and webhooks
Invite a notetaker — the full create request body
Notetaker API reference — media, leave, cancel, and list endpoints
Nylas CLI command reference — every nylas notetaker subcommand

Written by Qasim Muhammad and Pouya Sanooei.

Stop polling: real-time email and calendar webhooks with Nylas

Qasim — Sun, 21 Jun 2026 21:22:34 +0000

If your integration polls Nylas every minute to check for new email, you're doing too much work and still getting stale data. Polling is a tax: you burn rate limit on requests that mostly return nothing, and a message that arrives at 12:00:05 doesn't reach your app until the next poll. Webhooks flip that around. Nylas pushes a notification to your endpoint the moment something happens — a message arrives, an event changes, a contact is created — and your app reacts in real time.

This post walks the webhook surface from both sides: the HTTP API that registers and manages webhooks, and the Nylas CLI, which has genuinely useful tooling for the part everyone gets stuck on — verifying signatures and testing webhooks against local code. I work on the CLI, so the terminal commands below are the ones I run when I'm wiring up a webhook receiver.

Triggers and destinations

A webhook has two halves: the trigger types it listens for and the destination URL it pushes to. Trigger types are dotted event names like message.created, event.updated, and contact.created, grouped into categories — grant, message, thread, event, contact, calendar, folder, and notetaker. You subscribe one destination to as many triggers as you want.

The CLI lists every available trigger so you don't have to guess the names:

# All trigger types
nylas webhook triggers

# Only message-related triggers
nylas webhook triggers --category message

Webhooks are application-scoped, not grant-scoped: one webhook registered on your application receives notifications for every connected account, identified by the grant_id in each payload. See the notifications overview for the full event model.

Before you begin

You need a Nylas API key — webhook management is admin-level, so it uses the application's API key rather than a grant. You also need an HTTPS endpoint reachable from the public internet to receive the notifications. The CLI gets the key set up:

nylas init  # create an account, generate an API key

For local development you won't have a public HTTPS URL yet, which is exactly the problem the CLI's local server solves — more on that below.

Create a webhook

Registering a webhook takes a destination URL and at least one trigger. The CLI maps these to --url and --triggers:

nylas webhook create \
  --url https://yourapp.example.com/webhooks/nylas \
  --triggers message.created,event.created,contact.created \
  --description "Production receiver" \
  --notify admin@example.com

The --notify addresses get an email if the webhook starts failing, which is the kind of thing you want to know before your users do. Over HTTP, the request body fields are webhook_url, trigger_types, description, and notification_email_addresses:

curl --request POST \
  --url "https://api.us.nylas.com/v3/webhooks" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "webhook_url": "https://yourapp.example.com/webhooks/nylas",
    "trigger_types": ["message.created", "event.created"],
    "description": "Production receiver",
    "notification_email_addresses": ["admin@example.com"]
  }'

Note the field name is webhook_url, not callback_url. The CLI flags are documented at webhook create.

The challenge handshake

Here's the first thing that trips people up. When you register a webhook (or reactivate one), Nylas immediately sends a GET request to your URL with a challenge query parameter, and your endpoint must echo the exact value back in a 200 OK within 10 seconds. If it doesn't, the webhook never activates.

# What Nylas sends to verify your endpoint
curl -X GET 'https://yourapp.example.com/webhooks/nylas?challenge=bc609b38-c81f-47fb-a275-1d9bd61a968b'

Your handler has to return that challenge string and nothing else — no quotation marks, no JSON wrapper, just the raw value. This GET-with-challenge step is separate from the actual event notifications, which arrive as POST requests, so your endpoint needs to handle both methods. The notifications overview documents the full handshake.

Verify every webhook signature

This is the part you cannot skip. Your webhook URL is public, so anyone who finds it can POST fake events at it. Nylas signs every notification so you can prove it's genuine: each request carries an x-nylas-signature header containing a hex-encoded HMAC-SHA256 signature of the raw request body, signed with your endpoint's auto-generated webhook_secret.

The critical detail is raw: you compute the HMAC over the exact bytes Nylas sent, before any JSON re-parsing or reformatting. Pretty-print the body first and verification fails. The CLI's verify command implements this correctly, which makes it a good oracle when you're debugging your own implementation:

nylas webhook verify \
  --payload-file ./raw-body.json \
  --secret "<WEBHOOK_SECRET>" \
  --signature "<x-nylas-signature header value>"

If your own code and the CLI disagree on a payload, your code is mangling the body before hashing — almost always the bug. The webhook verify command documents the flags. One more wrinkle: if you accept compressed payloads, compute the signature over the compressed bytes before decompressing, or it won't match.

Develop locally with a tunnel

The chicken-and-egg problem with webhooks is that you can't receive them on localhost, but you don't want to deploy to production just to test a handler. The CLI's server command solves this: it runs a local receiver and can expose it through a Cloudflare tunnel so real Nylas events reach your machine.

# Local receiver behind a cloudflared tunnel, verifying signatures
nylas webhook server --tunnel cloudflared --secret "<WEBHOOK_SECRET>"

With --tunnel set, --secret is required so the server verifies the HMAC signature on every incoming event — you don't want to process traffic from anyone who happens to hit the public tunnel URL. If you'd rather run loopback-only and drive it with local tooling, --no-tunnel skips the tunnel and listens on localhost. The webhook server command covers the options, and there's a full walkthrough in receive webhooks with the CLI.

You can also test without a live event at all. nylas webhook test payload prints a mock payload for any trigger type so you can see the exact shape your handler will receive, and nylas webhook test send posts a test event to a URL.

Rotate the secret when it leaks

If your webhook_secret is ever exposed — committed to a repo, logged, leaked — rotate it. Rotating changes the signing key for future deliveries, so update your receiver with the new value before you resume trusting traffic:

nylas webhook rotate-secret <webhook-id>

The webhook rotate-secret command prints the new secret. Treat the secret like any other credential: out of source control, in your secrets manager, never logged.

Acknowledge fast, or get retried

Your endpoint must respond with 200 OK to each notification. If it doesn't, Nylas marks the webhook failing and retries: it attempts delivery two more times for three total, backing off exponentially, with the final attempt landing 10–20 minutes after the first. After three failures it skips that notification type and keeps sending the others.

Retries depend on the status code you return. Temporary signals like 429 Too Many Requests (respect the Retry-After header) get retried; permanent ones like authentication or invalid-request errors don't, because retrying won't fix them. The practical rule: acknowledge the event with 200 OK immediately, then do the real processing asynchronously. If you run your handler's slow work before responding, you risk blowing past the timeout and triggering retries for events you actually received — which shows up as duplicate processing. Queue the payload, return 200, and work it off the queue.

What to know

Dimension	Value	Notes
Scope	Application-level	One webhook covers every connected grant
Endpoint	HTTPS, public	`localhost` works only via a tunnel
Challenge	Echo within 10 seconds	Return the raw `challenge` value, nothing else
Signature	HMAC-SHA256, hex-encoded	`x-nylas-signature` header, signed over the raw body
Trigger categories	grant, message, thread, event, contact, calendar, folder, notetaker	Subscribe one destination to many

The two things people get wrong are both above: failing the challenge handshake (so the webhook never activates) and verifying the signature against a reformatted body (so every event looks forged). Get those two right and the rest is just handling POST requests.

Wrapping up

Webhooks turn a polling loop that's always slightly behind into an event stream that's immediate, and they cost you far less rate limit while being more current. The setup has two real gotchas — the challenge echo and raw-body signature verification — but the CLI gives you a correct reference for both, plus a tunnel that lets you test against real events from your laptop. Build the receiver once, verify signatures on every request, and you've replaced a brittle poller with a push pipeline.

Where to go next:

Notifications overview — triggers, the challenge handshake, and signatures
Receive webhooks with the CLI — the local-tunnel development workflow
Notifications reference — every webhook payload schema
Nylas CLI command reference — every nylas webhook subcommand

Written by Qasim Muhammad and Pouya Sanooei.

One calendar API for Google, Microsoft, and beyond: Nylas Calendar

Qasim — Sun, 21 Jun 2026 21:21:49 +0000

Scheduling features look simple until you build them. Google Calendar speaks its own REST API with events.insert; Microsoft 365 wants Graph and POST /me/calendar/events; Apple and a long tail of providers expect CalDAV. The moment your app needs to read a user's events, drop a meeting on their calendar, or check whether three people are free at 2pm, you're staring down three integrations that disagree on field names, time formats, and recurrence rules.

The Nylas Calendar API gives you one interface over all of them. Connect a user's account once, get a grant_id, and read calendars, manage events, send RSVPs, and compute free/busy with the same request shape whether the backing provider is Google or Microsoft. This post walks the calendar surface from both sides: the HTTP API your backend calls, and the Nylas CLI for testing the same operations in a terminal.

I work on the CLI, so the terminal snippets below are the commands I actually run when I'm poking at a calendar.

Calendars, events, and the calendar_id

A connected account has one or more calendars, and every event belongs to exactly one of them. Most operations take a calendar_id, and the special value primary resolves to the account's default calendar — so you don't need to look up an ID to act on the main calendar. One exception: iCloud doesn't support primary, so for iCloud accounts you pass a real calendar ID from nylas calendar list.

An event carries a title, a when object holding its start and end times, a list of participants, an optional location, and flags like busy. That schema is identical across providers, which is the whole point: you read a Google event and a Microsoft event into the same struct. See the Calendar API overview for how calendars, events, and availability fit together.

Before you begin

You need a Nylas API key and a connected account with calendar scopes. The CLI gets you there in two commands:

nylas init        # create an account, generate an API key
nylas auth login  # connect an account over OAuth, store the grant

After login the CLI uses that grant as your default, so the nylas calendar commands below run without an explicit ID. For the production OAuth flow and the calendar scopes Google and Microsoft require, see the authentication docs.

List calendars and events

Start by seeing what calendars the account has. The CLI lists them in one command:

nylas calendar list

Each row includes the calendar ID you'll pass to event operations. To list events, point at a calendar and a time window. The CLI defaults to the primary calendar and a short look-ahead:

# Upcoming events on the primary calendar
nylas calendar events list

# Next 14 days, capped at 50 results
nylas calendar events list --days 14 --limit 50

The same read over HTTP is a GET against the events collection, and calendar_id is a required query parameter. Pass start and end as Unix timestamps to bound the window:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary&start=1718841600&end=1719446400" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

The GET /events reference documents the full filter set — by calendar, time range, attendee, and more. The CLI equivalents are at calendar events list.

Create an event with participants

Creating an event is a single POST. The only strictly required pieces are the calendar_id query parameter and a when object in the body — title and participants are optional, though you'll almost always set them. The CLI's events create takes start and end times in YYYY-MM-DD HH:MM form (or a bare YYYY-MM-DD for an all-day event):

nylas calendar events create \
  --title "Design review" \
  --start "2026-06-23 14:00" \
  --end "2026-06-23 15:00" \
  --participant alice@example.com \
  --participant bob@example.com \
  --location "Zoom"

Over HTTP, the when object has a few shapes; the one used here is a timespan that takes start_time and end_time as Unix timestamps (the others are a single time, a date, and a datespan). Each participant is an object with an email:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Design review",
    "when": { "start_time": 1718901000, "end_time": 1718904600 },
    "participants": [
      { "email": "alice@example.com" },
      { "email": "bob@example.com" }
    ],
    "location": "Zoom"
  }'

When you add participants, the provider sends them invitations and they show up as normal calendar invites in Gmail, Outlook, or Apple Calendar. One field worth knowing is conferencing: set it and Nylas can auto-create a video link (Google Meet, Teams, or Zoom depending on the provider) so you don't have to mint one yourself. The full request body — busy, recurrence, conferencing, metadata — is in the create event reference, and the CLI flags are at calendar events create.

RSVP to invitations

When the connected account is invited to an event, you can respond programmatically. The RSVP status is one of exactly three values — yes, no, or maybe — and Nylas sends it to the event organizer as an email update, the same notification you'd trigger by clicking the button in a mail client.

From the CLI:

nylas calendar events rsvp <event-id> yes --comment "See you there"

Over HTTP, it's a POST to the event's send-rsvp endpoint with a status:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events/<EVENT_ID>/send-rsvp?calendar_id=primary" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "status": "maybe" }'

There's a provider quirk worth flagging here, straight from the API docs: due to a Microsoft Graph limitation, declining ("no") might not update the event status properly on Microsoft accounts — the event stays on the calendar with the no-RSVP status rather than being removed. If your app relies on RSVP state for Microsoft users, test that path explicitly. The send RSVP reference and the calendar events rsvp command document the rest.

Compute availability across calendars

This is the operation that's genuinely painful to build yourself, because it means reading several people's free/busy data from potentially different providers and intersecting it. The Calendar API does the intersection for you. POST /availability takes a list of participants, a time range, and a meeting duration, and returns only the slots when everyone is free.

The endpoint is POST /v3/calendars/availability, and the four required fields are participants, start_time, end_time, and duration_minutes:

curl --request POST \
  --url "https://api.us.nylas.com/v3/calendars/availability" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "start_time": 1718841600,
    "end_time": 1719446400,
    "duration_minutes": 30,
    "participants": [
      { "email": "alice@example.com" },
      { "email": "bob@example.com" }
    ]
  }'

The response is the set of 30-minute windows where all participants are free across the whole range. The CLI exposes the same computation through calendar availability check:

nylas calendar availability check \
  --emails alice@example.com,bob@example.com \
  --start "tomorrow 9am" \
  --end "tomorrow 5pm"

This single endpoint replaces the read-everyone, normalize-timezones, intersect-the-gaps logic you'd otherwise write by hand. The availability reference covers group availability, round-robin, and open-hours constraints.

Find the best time, not just any time

Free/busy tells you when people can meet. It doesn't tell you when they should. A slot at 7am for someone in Berlin and 10pm for someone in Tokyo is technically "free" but a terrible choice. The CLI's find-time command layers a scoring model on top of availability to rank candidate slots.

nylas calendar find-time \
  --participants alice@example.com,bob@example.com \
  --duration 1h \
  --days 7

It scores each candidate out of 100 points across five factors: working hours (40 points — is everyone inside 9-to-5?), time quality (25 points — morning versus late afternoon), cultural norms (15 points — avoid Friday afternoons and the lunch hour), weekday preference (10 points — mid-week beats Monday), and holiday avoidance (10 points). You can override the working window with --working-start and --working-end and pass per-participant timezones with --timezones. Full flags are at calendar find-time.

Recurring events and limits

Recurring events use the standard iCalendar RRULE format in the event's recurrence field, so a weekly standup is one event with a recurrence rule rather than 52 separate events. The CLI groups recurring-event operations under nylas calendar recurring.

Dimension	Value	Notes
Providers	Google Calendar, Microsoft 365, and more	One event schema across all
RSVP statuses	`yes`, `no`, `maybe`	Microsoft Graph may not apply a "no" cleanly
Default calendar	`calendar_id=primary`	Resolves to the account's main calendar
Time format	Unix timestamps	The `when` object holds `start_time` / `end_time`
Recurrence	iCalendar `RRULE`	One event carries the whole series

The provider differences that survive the abstraction are narrow: the Microsoft RSVP quirk above, and the fact that auto-conferencing creates a Meet link on Google and a Teams link on Microsoft. Everything else — reading events, creating them, computing availability — is one code path.

Wrapping up

Calendar work is where provider fragmentation hurts most, because availability and invitations genuinely require reading and writing across accounts. Doing it once through one schema, instead of once per provider, is the difference between a feature you ship this week and one you maintain forever. The CLI mirrors every operation, so you can prove out a scheduling flow in the terminal before writing a line of backend code.

Where to go next:

Calendar API overview — calendars, events, and availability concepts
Create an event and send RSVP — endpoint references
Availability API — free/busy and group scheduling
Nylas CLI command reference — every nylas calendar subcommand

Written by Qasim Muhammad and Pouya Sanooei.

Read and send email from one API across every provider: Nylas Email

Qasim — Sun, 21 Jun 2026 21:21:19 +0000

Every email provider speaks a different dialect. Gmail has labels and the Gmail API; Microsoft 365 has folders and Graph; Yahoo and iCloud want IMAP with app passwords; Exchange wants EWS. Build email into your product the obvious way and you end up maintaining four or five integrations that drift apart over time, each with its own auth, its own pagination, and its own quirks.

The Nylas Email API collapses that into one interface. You connect a user's mailbox once, get a grant_id, and from then on every message, thread, folder, and attachment comes back in the same shape no matter who hosts the mailbox. This post is a working tour of that surface from two angles: the HTTP API for your backend, and the Nylas CLI for the terminal, scripts, and quick experiments.

I work on the CLI, so the terminal examples below are the exact commands I reach for.

I'll cover the operations you actually reach for day to day — list, read, search, send, reply, and draft — and call out the provider differences worth knowing.

The grant: one connection, every provider

A grant is an authenticated connection to a single user's mailbox. You create it once through an OAuth flow (or Bring Your Own Auth), and Nylas hands you a grant_id that you pass on every request. That ID is the only provider-specific thing you deal with — the rest of the API is identical across Gmail, Microsoft 365, Exchange, Yahoo, iCloud, and IMAP.

Because the grant abstracts the provider, code you write against one mailbox works unchanged against all of them. A GET /messages against a Gmail grant and the same call against an iCloud grant return the same JSON fields. See the Email API overview for the full concept map of messages, threads, folders, and attachments.

Before you begin

You need a Nylas API key and at least one connected account. The fastest setup is the CLI:

nylas init        # creates an account and generates an API key
nylas auth login  # connect a mailbox over OAuth and store its grant

After nylas auth login, the CLI stores the grant as your default account, so every nylas email command below runs against it without you passing an ID. List what's connected anytime with nylas auth list. For the full authentication flow your app uses in production — OAuth scopes, redirect URIs, hosted auth — see the authentication docs.

List and read messages

Reading mail is the first thing most integrations do. The CLI lists your inbox in one command and defaults to the 10 most recent messages from INBOX only:

# 10 most recent inbox messages
nylas email list

# Only unread, from a specific sender
nylas email list --unread --from boss@company.com

# Everything across all folders, paginated automatically
nylas email list --all --max 500 --all-folders

The --all flag walks pagination for you and --max caps the total, which matters because a busy mailbox can hold hundreds of thousands of messages. Full flag reference lives at email list.

The same operation over HTTP is a GET against the grant's messages collection. The default page size is 50 and the maximum is 200; pass the next_cursor value from each response back as the page_token query parameter to fetch the next page:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?limit=5&unread=true" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

To open a single message and mark it read in one step:

nylas email read <message-id> --mark-read

The GET /messages reference lists every query parameter — sender, recipient, subject, unread state, starred, thread, and received-date ranges — so you can filter server-side instead of pulling everything and filtering in your app.

Search your mailbox

Filtering by exact fields covers a lot, but sometimes you need a free-text query. The CLI's search runs a query string against the provider's own search engine and layers structured filters on top:

# Free-text subject and body search
nylas email search "project update"

# Any subject from one sender, with attachments, in a date window
nylas email search "*" --from "hr@company.com" --has-attachment \
  --after 2024-01-01 --before 2024-12-31

Using * as the query with a --from filter is the idiom for "every message from this sender regardless of content." The email search command documents the --in, --to, --subject, and --starred filters. Search returns 20 results by default, and only auto-paginates across multiple pages once you raise --limit above 200.

One thing worth knowing: search semantics are the provider's, not Nylas's. Gmail's search is more forgiving and operator-rich than a bare IMAP search, so the same query can return slightly different relevance across providers. For deterministic results, prefer the structured filters on GET /messages over free-text search.

Send email

Sending is one request, and the recipient sees a normal message from the connected mailbox — sent through the user's own provider, landing in their real Sent folder. From the CLI:

nylas email send \
  --to user@example.com \
  --subject "Hello from Nylas" \
  --body "This went out through the connected mailbox."

The same call over HTTP hits POST /messages/send. The request body accepts to, cc, bcc, subject, body, from, reply_to, attachments, and more:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "Q3 report",
    "body": "<p>Attached is the report.</p>",
    "to": [{ "email": "finance@example.com", "name": "Finance" }],
    "cc": [{ "email": "lead@example.com" }]
  }'

A few capabilities that turn a basic send into a production one:

Scheduled send. Pass a send_at Unix timestamp in the API, or use the CLI's human-friendly --schedule flag: nylas email send --to a@b.com --subject Hi --body "later" --schedule "tomorrow 9am". Manage queued sends with nylas email scheduled list.
Open and link tracking. Set tracking_options in the request, or --track-opens and --track-links on the CLI, to record when recipients open mail or click links. See message tracking for how the pixel and link-rewrite work.
Idempotent send. Retrying a failed send risks sending twice. Nylas supports an idempotency key so a retried request is de-duplicated server-side — see idempotent send.

The CLI's email send command also supports GPG signing and encryption and hosted templates, which are handy for transactional mail that needs consistent branding.

Reply and keep the thread intact

A reply is not just a send with Re: in the subject. To make mail clients group the reply with the original conversation, you have to set the in-reply-to relationship. The API field is reply_to_message_id; set it to the message you're answering and Nylas wires up the threading headers.

The CLI's reply command does this for you. It fetches the original to populate the recipient and subject, preserves threading through reply_to_message_id, and replies only to the original sender unless you add --all:

# Reply to the sender, in-thread
nylas email reply <message-id> --body "Sounds good, thanks!"

# Reply to everyone on the thread
nylas email reply <message-id> --all --body "Looping everyone in."

This is the biggest correctness trap in email integrations: send a "reply" without the threading header and it shows up as a brand-new conversation, which looks broken to the recipient. Always thread your replies. For how threads behave across providers — Gmail groups by conversation, others by header chain — see email threading explained.

Compose drafts before sending

When a human (or an approval step) reviews mail before it goes out, draft first and send later. Drafts persist server-side in the user's mailbox, so they sync to the provider's Drafts folder and show up in the user's normal mail client too:

nylas email drafts create --to user@example.com --subject "WIP" --body "Draft body"
nylas email drafts list
nylas email drafts send <draft-id>

The Drafts API mirrors this — create, update, list, and send — and the CLI commands are documented at email drafts create and email drafts send. Drafting is also the right pattern for an AI agent that proposes replies: generate the draft, route it through human approval, then send the approved draft by ID.

Handle attachments

Attachments ride on the message object as metadata; you download the bytes separately by attachment ID. Nylas accepts up to 25 MB inline through multipart on send, or up to 150 MB for Microsoft grants through the attachment-uploads flow. From the CLI:

nylas email attachments list <message-id>
nylas email attachments download <attachment-id> <message-id> --output ./file.pdf

The size ceiling is the one provider difference you can't ignore here: a 40 MB attachment that sails through a Microsoft grant will be rejected on a provider capped at 25 MB. Check the limit before you build a feature around large files. See attachments for the upload-session flow.

Limits and provider notes

Dimension	Value	Notes
Default page size	50 messages	Maximum 200 per page; use `page_token` to paginate
Inline attachment size	25 MB	Up to 150 MB for Microsoft grants via upload sessions
Providers	Gmail, Microsoft 365, Exchange, Yahoo, iCloud, IMAP	One schema across all of them
Folders vs labels	Provider-specific	Gmail models folders as labels, so a message can be in several at once

These are the defaults you'll hit first; rate limits and quotas vary by provider and plan. Gmail in particular enforces its own per-user sending and API quotas underneath Nylas — see Gmail API quotas before you scale outbound volume.

Wrapping up

The win with the Email API is that you write the integration once. List, search, send, reply, and draft are the same five calls whether the mailbox is Gmail or IMAP, and the CLI gives you the same operations in the terminal for testing and automation before you commit them to code. The provider differences that remain — search relevance, attachment ceilings, folders-as-labels — are few enough to enumerate, which is the whole point.

Where to go next:

Email API overview — the full concept map and capabilities
Send a message and list messages — endpoint references
Nylas CLI command reference — every nylas email subcommand
Email threading explained — keep replies in the right conversation

Written by Qasim Muhammad and Pouya Sanooei.

Give your AI agent its own inbox

Qasim — Sun, 21 Jun 2026 19:10:48 +0000

Qasim

Jun 21

Give your AI agent its own inbox: Nylas Agent Accounts via API and CLI

#ai #email #api #devtools

6 min read

Give your AI agent its own inbox: Nylas Agent Accounts via API and CLI

Qasim — Sun, 21 Jun 2026 18:41:28 +0000

Most "AI email" demos point a model at a human's inbox over OAuth. That's fine until you want the agent to be a participant — to have its own address that people reply to, that calendars invite, and that builds its own sender reputation. Pointing at someone's personal inbox doesn't give you that.

Nylas Agent Accounts take the other approach: a real name@yourdomain.com mailbox and calendar that the agent owns end to end. It sends, receives, hosts events, and RSVPs — and to anyone on the other side it's indistinguishable from a human-operated account. It went GA in June 2026.

The part I like as an SRE: it's not a new API surface. An Agent Account is just another Nylas grant. It gets a grant_id that works with every endpoint you already use — Messages, Drafts, Threads, Folders, Attachments, Calendars, Events, Webhooks. Nothing new to learn on the data plane.

This walkthrough provisions one two ways (CLI and raw API), then sends, receives, RSVPs, and adds guardrails.

What you get

When you create an Agent Account, Nylas provisions a real mailbox on a domain you've registered (or a Nylas *.nylas.email trial domain). Each account comes with:

An email address that sends and receives like any other mailbox
Six system folders (inbox, sent, drafts, trash, junk, archive), plus any custom ones you create
A primary calendar that hosts events and RSVPs over standard iCalendar/ICS
A grant_id for all the existing Nylas endpoints

Before you begin

You need two things:

A Nylas API key. The fastest path is the CLI — nylas init creates an account and generates a key in one command.
A domain. Either a Nylas-provided *.nylas.email trial subdomain (good for testing in minutes) or your own custom domain with MX + TXT records. Register it under Organization Settings → Domains.

Why your own domain? It's what makes the agent a real first-class sender instead of a shared relay address — people reply to it, calendars invite it, and its mail authenticates as coming from you. A new domain builds sender reputation over roughly four weeks of gradual sending, so run one domain per customer or use case to keep reputations isolated.

Create an Agent Account

Option A — the CLI (fastest)

After nylas init, provisioning is one command:

nylas agent account create test@your-application.nylas.email

The CLI prints the new grant ID alongside connector and status details. A few companion commands:

# List every agent account
nylas agent account list

# Confirm the connector is ready
nylas agent status

# Show one account
nylas agent account get test@your-application.nylas.email

# See how accounts, workspaces, policies, rules, and lists fit together
nylas agent overview

That last one — nylas agent overview — renders a tree per account and flags dangling references to deleted policies/rules. It's the command I'd reach for first when something looks misconfigured.

Option B — the API

Under the hood the CLI calls POST /v3/connect/custom with "provider": "nylas" — the same Bring Your Own Auth endpoint used for other providers, minus the refresh token. Just the email on a registered domain:

curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "nylas",
    "name": "Test Agent",
    "settings": {
      "email": "test@your-application.nylas.email"
    }
  }'

The response contains a grant_id — save it, you'll use it everywhere. The top-level name sets the display name recipients see on outbound mail (Test Agent <test@your-application.nylas.email>). Omit it and the account sends with no display name.

Receive mail

Two ways, same as any grant.

Poll the messages endpoint:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?limit=5" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

Or subscribe to a webhook so Nylas calls you the moment mail arrives. From the CLI:

nylas webhook create \
  --url https://yourapp.example.com/webhooks/nylas \
  --triggers message.created

Inbound mail fires the standard message.created webhook — identical in shape to message.created for any other grant, so a handler you already have just works. On top of that, Agent Accounts emit deliverability webhooks like message.delivered, message.bounced, and message.complaint for tracking outbound mail.

Send mail

Same /messages/send endpoint you'd use for a connected grant:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "Hello from my Agent Account",
    "body": "This message was sent by a Nylas Agent Account.",
    "to": [{ "email": "you@yourdomain.com", "name": "You" }]
  }'

The recipient sees a normal message from the agent's address — no "sent via" branding, no relay footer.

Use the calendar

Every Agent Account ships with a primary calendar, reachable through the same Events endpoints:

GET /v3/grants/{grant_id}/events — list events
POST /v3/grants/{grant_id}/events — create an event and invite others
POST /v3/grants/{grant_id}/events/{id}/send-rsvp — accept or decline an invitation

Invitations travel over standard iCalendar/ICS, so Google Calendar, Microsoft 365, and Apple Calendar all treat the agent as a normal participant. This is what lets a scheduling agent propose slots and have participants accept them as ordinary invites.

Guardrail it: policies, rules, and lists

Provisioning gives you a working mailbox. The interesting operational part is constraining what it can do. Three application-scoped resources handle that:

Policies bundle limits (send quota, storage, retention, attachment caps) and spam settings. One policy governs many accounts.
Rules match inbound or outbound mail on sender/recipient fields and run actions like block, mark_as_spam, assign_to_folder, archive, or trash.
Lists are typed collections of domains, TLDs, or addresses that rules reference via the in_list operator.

They attach through workspaces, not individual grants: a workspace carries one policy_id and an array of rule_ids, and every account in it inherits both. Each application has a default workspace, so configuring it governs all your unassigned accounts at once.

Inspect them from the CLI:

nylas agent policy list
nylas agent rule list
nylas agent list list

And create each piece from the CLI:

# A typed list of domains you can reference from a rule's in_list condition
nylas agent list create --name "Blocked domains" --type domain --item spam.com

# An outbound rule that archives the sent copy of mail to a recipient domain
nylas agent rule create \
  --name "Archive outbound mail" \
  --trigger outbound \
  --condition recipient.domain,is,example.com \
  --action archive

# A policy you can attach to a workspace
nylas agent policy create --name "Strict Policy"

Swap --action archive for --action block and the rule rejects the message instead — before it ever reaches the mailbox (inbound) or the provider (outbound). That's handy for data-loss prevention, keeping test domains out of production, or stopping an agent from emailing the wrong people. Inbound and outbound rules are isolated: inbound rules never run on sends, and outbound rules never re-evaluate the stored sent copy.

Policies are optional. Skip them and the account runs at your billing plan's maximum limits and delivers every inbound message to the inbox.

Known limits (free plan)

Dimension	Default	Notes
Send rate	200 messages/account/day	Paid plans have no daily cap by default
Storage	3 GB/org	Higher on paid plans
Retention	30 days inbox, 7 days spam	Configurable via policy
Domains	Unlimited	One application can manage accounts across any number of domains

Wrapping up

The thing that makes Agent Accounts click is that there's no second system. You provision an identity with one CLI command or one API call, and from that point it's the same Messages, Events, and Webhooks surface you'd use for a connected Gmail or Microsoft grant — now owned by your agent instead of borrowed from a user.

If you want to go deeper:

Agent Accounts quickstart — end to end in under 5 minutes
What are Agent Accounts — the full concept guide
Policies, Rules, and Lists — the guardrail model in detail
Supported endpoints — everything that works against an Agent Account grant

Written by Qasim Muhammad and Pouya Sanooei.