DEV Community: Qasim

Route Nylas notifications to Google Pub/Sub

Qasim — Thu, 23 Jul 2026 11:53:46 +0000

An HTTP webhook endpoint has to be a public URL that's always up and fast enough to absorb a burst. When a sync kicks off and a few thousand message.created events fire in a minute, a slow handler backs up, times out, and starts dropping deliveries. You can engineer around that with a queue in front of your endpoint, or you can skip the endpoint entirely and have Nylas deliver notifications straight into a Google Cloud Pub/Sub topic, where the queue is the delivery mechanism.

This post covers Pub/Sub notification channels from two angles: the HTTP API your backend calls, and the nylas CLI for creating and managing a channel from the terminal. I work on the CLI, so the terminal commands below are the ones I reach for when I'm wiring up a channel.

What a Pub/Sub channel is

A Pub/Sub notification channel tells Nylas to publish your notifications to a Google Cloud Pub/Sub topic instead of (or alongside) posting them to an HTTP URL. You own the topic; the channel is the stored configuration that lets the service connect to it and push events in. Your own services then consume those events from a subscription on that topic, at whatever pace they can handle.

This is a different Pub/Sub from the one some Google auth apps use to receive mail changes from Google. Here, the flow goes the other way: Nylas is the publisher, your topic is the destination, and your consumers read from it. The notification payloads are the same events you'd get over HTTP, so message.created, event.updated, and the rest arrive in the topic with the shape you already know, just delivered through Google's infrastructure rather than a request to your server.

Why Pub/Sub instead of an HTTP endpoint

The reason to reach for this is delivery guarantees. Pub/Sub is a durable, event-driven queue, so a burst of notifications buffers in the topic instead of hammering your endpoint, and your consumers drain it individually or in batches during high volume. If a consumer is down, the messages wait rather than being lost, which is the property an HTTP webhook can't give you on its own.

It also opens up patterns an endpoint makes awkward. You can route different triggers to different topics, segmenting high-volume notifications away from low-volume ones, and you can attach a dead-letter topic to catch events your consumers fail to process so they don't pile up and add latency. You don't have to go all in either: Pub/Sub can fully replace your webhook setup, or run alongside it, with high-volume subscriptions on Pub/Sub and quieter ones still on HTTP. It's the right tool when volume, latency, or deliverability are real concerns.

Set up the topic first

The channel points at a topic you create, so that comes first. In the Google Cloud console, open the Pub/Sub page, create a topic, and add a default subscription so there's something to consume from. If you already have a Google Cloud project for an auth app, you can put the notification topic in that same project rather than standing up a new one.

The one configuration that matters is permission: the topic has to allow Nylas to publish to it. You grant that on the topic in Google Cloud, and once it's in place, notifications start flowing into the topic once the channel is active, within a couple of minutes for a freshly authenticated grant. Keep the topic's full path handy, the projects/<project>/topics/<topic> string, because that's what you pass when you create the channel.

Create the channel

With the topic ready, creating the channel from the CLI is one command. nylas webhook pubsub create takes the topic path and the triggers you want delivered to it, plus optional notification emails for channel health alerts:

nylas webhook pubsub create \
  --topic "projects/my-project/topics/nylas-email" \
  --triggers message.created,message.updated \
  --notify ops@example.com

The same channel over the API is a POST /v3/channels/pubsub with the topic and trigger_types:

curl --request POST \
  --url "https://api.us.nylas.com/v3/channels/pubsub" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "topic": "projects/my-project/topics/nylas-email",
    "trigger_types": ["message.created", "message.updated"]
  }'

Once the channel exists, Nylas starts publishing the subscribed triggers to that topic, and your consumers pick them up from the topic's subscription. The --triggers you choose work exactly like webhook trigger types; a channel is just a different destination for the same events.

Consume the notifications

Creating the channel is only half of it; your services still have to read from the topic. You attach a subscription to the topic and consume it either by pulling messages on your own schedule or by having Pub/Sub push them to an endpoint, and you acknowledge each message once you've processed it so it isn't redelivered. The subscription is where backpressure lives: if a consumer slows down, unacknowledged messages wait there instead of disappearing.

Plan for at-least-once delivery. Pub/Sub can hand you the same message more than once, so your handler should be idempotent, keyed on the notification's ID, which is the same discipline a well-built webhook handler already follows. The payoff is that a consumer can crash, restart, and resume from the subscription without losing the events that arrived while it was down, which is the whole reason to put a queue between Nylas and your processing.

Split triggers across topics

A single channel subscribes a topic to any number of triggers, which lets you segment notifications by routing different events to different topics. A common split is one topic for all the email notifications and a separate one for calendar events and event changes, so a high-volume email sync doesn't crowd out the calendar updates a different consumer cares about.

This segmentation is where Pub/Sub pulls ahead of a single webhook URL. With one endpoint, every trigger lands in the same place and you fan out in your own code; with channels, you push that routing down to the infrastructure, and each topic gets its own subscription, its own consumers, and its own scaling. A noisy trigger on one topic has no effect on the consumers reading a quieter one, because they're draining different queues entirely.

Catch failures with a dead-letter topic

A queue only helps if undeliverable messages don't clog it, which is what a dead-letter topic is for. Nylas recommends creating a second Pub/Sub topic per channel to serve as a dead-letter queue: when your consumer can't process a notification, Pub/Sub moves it there after the configured retries instead of letting it back up your subscription and add latency. Your primary subscription stays healthy, and the failures collect somewhere you can inspect them.

The value is that you can replay them. Once you've fixed whatever caused the ingestion failure, a bad deploy, a schema mismatch, a downstream outage, you reprocess the dead-letter queue and recover the events you would otherwise have lost. Configuring the dead-letter topic is a Google Cloud setting on the subscription, not something you do in Nylas, but pairing one with every channel is the practice that makes the deliverability guarantee real rather than theoretical.

Manage and limit your channels

Channels are managed through the same surfaces you created them with. nylas webhook pubsub list shows the channels on your application, show prints one, update changes its triggers or settings, and delete removes it. The API mirrors these: GET /v3/channels/pubsub lists the channels, and GET, PUT, and DELETE on /v3/channels/pubsub/{id} act on one.

nylas webhook pubsub list
nylas webhook pubsub show <channel-id>

There's a ceiling to plan around: each Nylas application can have up to five Pub/Sub channels. That's usually plenty when each channel can subscribe to multiple triggers, but it does mean you architect around topics-per-concern rather than a channel per trigger. If five genuinely isn't enough for your segmentation, that's a conversation with support rather than a limit you can raise yourself.

The AWS equivalent: SNS channels

If your infrastructure lives on AWS rather than Google Cloud, the same idea exists for Amazon SNS. A POST /v3/channels/sns channel publishes notifications to an SNS topic, which you then fan out to SQS queues, Lambda functions, or HTTP subscribers using the AWS tooling you already run. SNS takes a little more setup than Pub/Sub, an IAM role Nylas assumes to publish, which you pass as a role_arn, but once that's in place the model is the same: a durable topic the service publishes into, on the other cloud.

The one practical difference for this post is tooling: the dedicated nylas webhook pubsub commands cover Google Pub/Sub, while SNS channels are managed through the API. If you're on AWS, you create and manage the SNS channel over the API, with POST and GET on /v3/channels/sns and GET/PUT/DELETE on /v3/channels/sns/{id}, rather than a CLI subcommand, but the notifications and triggers behave the same way once they're flowing.

When a channel beats a webhook

Not every integration needs this. A plain HTTP webhook is the simplest path, and for low, steady volume it's the right one: one endpoint, verify the signature, done. Reach for a Pub/Sub channel when one of three things is true. Your notification volume spikes hard enough to overwhelm an endpoint. You need a deliverability guarantee that survives your consumer being down. Or your processing is already cloud-native, and reading from a queue fits your architecture better than receiving HTTP requests.

The honest framing is that channels trade setup for resilience. You stand up a topic, a subscription, and permissions, which is more work than pointing at a URL, and in return you get buffering and recovery you'd otherwise build yourself. For a side project, that's overkill. For a system that can't miss a message.created, it's the difference between a durable queue and a dropped event.

Things to keep in mind

A short list of practices keeps a Pub/Sub channel reliable.

Grant Nylas publish permission on the topic. The channel can't deliver until the topic allows it to publish; this is the step that's easy to forget.
Pair every channel with a dead-letter topic. It's what turns "the queue buffers" into a real recovery path for events your consumers can't process.
Segment by topic, not by channel. With a five-channel cap, route concerns to separate topics and let each channel carry multiple triggers.
Run Pub/Sub alongside webhooks if it fits. High-volume subscriptions on Pub/Sub, low-volume ones on HTTP, is a valid split.
The trigger types are the same. A channel changes where events go, not which events you get, so your trigger choices carry over from webhooks unchanged.

Wrapping up

Pub/Sub channels move notification delivery off your own endpoint and into a durable Google Cloud topic, which buffers bursts, supports batching, and gives you a dead-letter path to recover failures. Create one with nylas webhook pubsub create or POST /v3/channels/pubsub, point it at a topic you've granted Nylas permission to publish to, and consume from the subscription at your own pace. SNS offers the same model on AWS through the API, and either way the events are the familiar webhook triggers, just delivered into a queue that buffers bursts instead of dropping them under load.

Where to go next:

Pub/Sub notification channels — the full setup, including topic and dead-letter configuration
SNS notification channels — the Amazon SNS equivalent
Create a Pub/Sub channel — the endpoint reference
Nylas CLI webhook commands — nylas webhook pubsub create, list, and update

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/webhook-reliability-for-agents.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Automate appointment reminders with the Nylas API

Qasim — Thu, 23 Jul 2026 11:53:36 +0000

You booked a meeting on a customer's calendar, and you want them to get a reminder email the day before so they actually show up. The obvious build is a cron job that wakes up every few minutes, scans for appointments coming up in 24 hours, and fires an email. That's a polling loop you have to run, scale, and debug. There's a cleaner way that uses three Nylas features together: you read the appointment from the calendar, schedule the reminder email for exactly 24 hours before it, and let a template carry the copy. No loop, no worker watching the clock.

This post is a worked use case rather than a feature tour. It pulls together the Calendar, scheduled send, and templates APIs from two angles: the HTTP API for your backend and the nylas CLI for the terminal. I work on the CLI, so the terminal commands below are the ones I reach for when I'm prototyping the flow.

The shape of the solution

The reminder flow is three steps, each handled by a different piece. The calendar tells you when the appointment is. Scheduled send fires the email at a time you compute from that, with nothing running in between. And a template holds the reminder copy so it's editable without a deploy. Wire them together and an appointment booked today produces a reminder that goes out automatically tomorrow.

This same need shows up everywhere a booking exists: a clinic confirming appointments, a sales team reminding prospects about a demo, a service business trying to cut no-shows. The domain changes the copy, not the mechanism, so the implementation below is the same whether you're reminding patients or prospects.

The key insight is that you don't poll. Instead of a worker that repeatedly asks "is anything due soon?", you compute the send time once, when the appointment is created or found, and hand it to scheduled send. The reminder then sits queued until its moment arrives. That inverts the usual reminder architecture: the work happens at scheduling time, not at delivery time, so there's no always-on loop to operate.

Step 1: find the appointments

You need the appointments and their start times, which come from the Events API. A GET /v3/grants/{grant_id}/events call with a calendar_id and a start/end window returns the events in that range, each with a when object carrying the start_time as a Unix timestamp. That timestamp is what you base the reminder on.

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

From the terminal, nylas calendar events list shows the upcoming events on a calendar so you can eyeball what you're working with. There are two ways to drive this in production: pull events on a schedule for a rolling window, or react to the event.created webhook so the reminder is scheduled the instant a booking happens. The webhook path is the one I prefer, since it means a reminder exists the moment the appointment does, with no scan at all.

Two query parameters matter for reminders specifically. Pass expand_recurring=true so a weekly standing meeting yields each instance with its own start_time, rather than a single recurrence rule you'd have to expand yourself. And set show_cancelled=false so you never schedule a reminder for a meeting that's already off the calendar.

Step 2: compute the reminder time

This step is plain arithmetic, and it's where the "24 hours before" lives. The event's start_time is a Unix timestamp in seconds, so a reminder one day ahead is start_time - 86400, and one hour ahead is start_time - 3600. You compute that target once and pass it to the send as send_at.

const reminderAt = event.when.start_time - 24 * 60 * 60; // 24h before

There's one real constraint to respect here. A Nylas-stored scheduled send accepts a send_at up to 30 days in the future, so for an appointment booked more than a month out, the reminder time, the appointment minus a day, still falls outside that 30-day window. The clean pattern for far-future bookings is a thin daily job that schedules tomorrow's reminders, which keeps every send_at comfortably inside the 30-day ceiling, while last-minute bookings schedule their reminder right away.

Step 3: schedule the templated reminder

Now you send the reminder, dated into the future and filled from a template. You create a reminder template once with {{name}} and {{time}} placeholders, then each send references it by ID and supplies the variables, while send_at carries the time you computed. The message waits in the queue and goes out on its own at the reminder time.

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 '{
    "to": [{ "email": "customer@example.com" }],
    "template": {
      "id": "<REMINDER_TEMPLATE_ID>",
      "variables": { "name": "Alex", "time": "tomorrow at 10am" }
    },
    "send_at": 1744714800
  }'

The whole flow collapses into a single CLI command, because nylas email send carries both the schedule and the template. You pass --schedule with the reminder time, --template-id with your reminder template, and --template-data with the variables, and the templated reminder is queued in one line:

nylas email send \
  --to customer@example.com \
  --template-id <REMINDER_TEMPLATE_ID> \
  --template-data '{ "name": "Alex", "time": "tomorrow at 10am" }' \
  --schedule "2025-04-14 10:00"

The response includes a schedule_id. Store it against the appointment, because that's your handle if the meeting changes.

Because the reminder sends from the connected mailbox, the customer sees a normal email from the business they booked with, not a generic no-reply address. That matters for a reminder specifically: it lands in the same thread as the original confirmation, looks like it came from a person, and is far more likely to be read than a transactional blast from a noreply domain.

Put it in a webhook handler

Here's the create path as a single handler. When event.created fires, you compute the reminder time, schedule the templated send through a small helper that wraps POST /messages/send, and store the returned schedule_id against the event so you can manage it later:

app.post("/webhooks/nylas", async (req, res) => {
  res.sendStatus(200); // acknowledge fast
  const evt = req.body.data.object;
  // Only timed events: all-day events carry when.start_date, not start_time.
  if (evt.object !== "event" || !evt.when.start_time) return;

  const now = Math.floor(Date.now() / 1000);
  const reminderAt = evt.when.start_time - 24 * 60 * 60;

  // Too far out for the 30-day window: let a daily job pick it up later.
  if (reminderAt - now > 30 * 24 * 60 * 60) return;
  // Already due (e.g. a last-minute booking): send now by omitting send_at.
  const sendAt = reminderAt <= now ? null : reminderAt;

  const scheduleId = await scheduleReminder({
    to: attendeeEmail(evt),
    templateId: REMINDER_TEMPLATE_ID,
    variables: { name: attendeeName(evt) },
    sendAt, // null = send immediately
  });
  await saveReminder(evt.id, scheduleId); // for later cancel/reschedule
});

That's the whole create path with its guards in place: skip all-day events, skip bookings too far out for the daily job to handle, send immediately when the reminder is already due, and otherwise schedule it and store the schedule_id. Everything else, the reschedule and cancel logic below, hangs off the mapping you save on that last line.

Handle reschedules and cancellations

Appointments move, and a reminder for a meeting that was cancelled or rescheduled is worse than none. This is where storing the schedule_id pays off. When the event.updated or event.deleted webhook fires for an appointment, you act on the reminder you queued for it.

For a cancellation, you cancel the scheduled send with a DELETE against its schedule_id, as long as you're more than 10 seconds before the send time. For a reschedule, you cancel the old reminder and schedule a new one for the new start_time - 86400. The webhook gives you the changed event, your stored mapping gives you the schedule_id to cancel, and the new time gives you the next reminder. That closed loop, schedule on create, re-schedule on change, cancel on delete, is what makes the reminders track reality instead of drifting from it.

One edge is worth handling explicitly: if a meeting is rescheduled to within the next 24 hours, the new reminder time lands in the past or only moments from now. There, you skip scheduling and send the reminder immediately. A quick check on the computed time, send now if it's already due or too soon to queue, covers the last-minute reschedule cleanly.

Don't send two reminders

A reminder system's worst failure is sending the same person two reminders, and there are two ways it happens. Webhooks can be redelivered, so the same event.created may fire twice, and a reschedule you handle by cancel-and-recreate can race with itself. Both are solved by keying your reminder record on the event ID: before scheduling, check whether a reminder already exists for that event, and if it does, update it instead of adding a second.

The mapping you store, event ID to schedule_id, is the dedup key. On event.created, schedule only if there's no reminder for that event yet. On event.updated, look up the existing schedule_id, cancel it, and schedule the replacement, all keyed on the same event ID. That single record per appointment is what guarantees one reminder per meeting no matter how many times the webhooks fire, which at any real volume they will.

The same pattern, other reminders

Once the three pieces click together, the same shape covers a family of timed messages, not just a 24-hour reminder. The only thing that changes is the offset you apply to the event time and the template you attach. A few that drop straight in:

A prep email a week out. Offset start_time - 7 * 86400 with a template that asks the customer to gather documents before the meeting.
A morning-of nudge. Offset to the morning of the appointment with a short "see you today" template.
A post-meeting follow-up. A positive offset, start_time + 3600, with a template that sends a recap or a feedback link an hour after the meeting ends.

Each is the same compute-the-time, schedule-with-a-template move, so a single helper that takes an event, an offset, and a template ID generates any of them. That's the payoff of building the reminder out of composable pieces rather than a bespoke cron job: a new reminder type is a new offset and a new template, not new infrastructure.

Things to keep in mind

A short list of details makes this flow reliable in production.

Schedule on the webhook, not a poll. React to event.created so a reminder exists the moment the appointment does, with no scanning loop to run.
Store the schedule_id with the appointment. It's the only handle for cancelling or rescheduling the reminder when the meeting changes.
Mind the 30-day scheduled-send ceiling. When the computed reminder time is more than 30 days out, a thin daily job that queues tomorrow's reminders keeps every send_at inside the window.
Respect the 10-second cancel cutoff. A reminder can't be reliably cancelled in the final seconds before it sends, so gate any last-moment changes.
Keep the copy in a template. Editing the reminder wording is a template update, not a deploy, and one template serves every appointment.
Dedup on the event ID. Key your reminder record on the event so a redelivered webhook updates the existing reminder instead of queuing a second.

Wrapping up

An appointment reminder doesn't need a cron job; it needs three Nylas calls wired together. Read the appointment's start_time from the Events API, subtract your offset to get the reminder time, and schedule a templated email for that moment with send_at. Store the schedule_id so you can cancel or re-schedule when the meeting moves, and the same pattern, with a different offset and template, gives you prep emails, morning-of nudges, and post-meeting follow-ups for free.

Where to go next:

Using the Events API — reading and filtering calendar events
Schedule messages to send in the future — the send_at field and cancellation
Templates and workflows — reusable copy with variables
Event webhooks — react to bookings and changes

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/appointment-scheduling-api-confirmations-reminders.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Find meeting times with the Nylas availability API

Qasim — Thu, 23 Jul 2026 11:53:26 +0000

Scheduling a meeting is the same annoying problem every time: find a slot when everyone involved is actually free. Do it by hand and you're cross-referencing three calendars in different time zones. Do it in code and you have two tools to reach for, and picking the wrong one means writing slot-finding logic the API would have done for you. This post builds the "find a time" feature with the Calendar API and shows the CLI commands that answer the same question from the terminal.

It's a worked use case rather than an endpoint tour, covering free/busy and the availability endpoint from two angles: the HTTP API your backend calls and the nylas CLI for quick checks. I work on the CLI, so the commands below are the ones I reach for when I just want to see who's free.

Free/busy versus availability: pick the right one

The Calendar API gives you two endpoints for this, and the difference between them decides how much code you write. Free/busy returns the raw busy blocks on each person's calendar, the times they're not free, and leaves it to you to invert that into open slots. Availability does the inversion for you: you give it a meeting duration and a window, and it returns candidate time slots, each tagged with which participants are free then. Ask it to require the whole group, and it returns only the slots that work for everyone.

The rule of thumb is straightforward. If you're rendering a "this person is busy here" overlay, or you need the actual busy intervals for your own logic, use free/busy. If you're answering "when can these five people meet for 30 minutes," use availability and skip the slot math entirely. Most "schedule a meeting" features want availability, because the hard part, intersecting several busy calendars and carving out duration-sized gaps, is exactly what it does. Reaching for free/busy and rebuilding that logic by hand is the common mistake.

Get raw busy blocks with free/busy

Free/busy is a POST /v3/grants/{grant_id}/calendars/free-busy with a start_time, an end_time, and a list of emails. Both times are Unix timestamps. The response comes back as one entry per email, each carrying a time_slots array of that person's busy intervals within the window, so you see exactly when each calendar is blocked.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/calendars/free-busy" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "start_time": 1682467200,
    "end_time": 1682550000,
    "emails": ["alice@example.com", "bob@example.com"]
  }'

One behavior to code defensively around: this endpoint always returns 200 OK, even when the lookup fails for one of the addresses, in which case that entry's time_slots comes back as null rather than as an error status. So check each entry before you trust it, instead of assuming a 200 means every calendar resolved. The busy intervals are the input to your own slot-finding if you go this route, which is the work the next endpoint saves you.

Check free/busy from the CLI

The terminal equivalent is nylas calendar availability check, which shows the busy slots for one or more people in a time range. Pass --emails with a comma-separated list, and bound the window with --start and --end, or with --duration as a span like 8h or 7d from the start. With no emails it checks your own default account, which is the quick "am I free?" lookup.

# Busy slots for two people, tomorrow 9am to 5pm
nylas calendar availability check \
  --emails alice@example.com,bob@example.com \
  --start "tomorrow 9am" --end "tomorrow 5pm"

The command accepts human dates like "tomorrow 9am" and parses them for you, which is far less fiddly than computing Unix timestamps by hand for a quick check. It's the fast way to eyeball a couple of calendars before you build anything, and the freebusy alias works too if that's the word your fingers reach for. Add --json when you want to pipe the busy blocks into another tool rather than read them.

Get ready-made slots with availability

Availability is the endpoint that does the slot math. A POST /v3/calendars/availability takes a participants list, a start_time and end_time window, and a duration_minutes for the meeting length, and returns a time_slots array of open windows. Each returned slot carries the emails that are free during it, plus its own start_time and end_time, so you can drop the results straight into a picker and see exactly who each slot works for.

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

The interval_minutes field controls how the window is sampled: the API generates a candidate slot every interval and returns the open ones, so an interval of 30 gives you slots on the half-hour. Whether a slot needs everyone free or just some of the group depends on the availability_method covered below, and each slot's emails reports who it works for. Add round_to to snap slot starts to a clean boundary like :00 and :15. The four required fields are participants, start_time, end_time, and duration_minutes; everything else tunes the output. This is the endpoint to default to for a scheduling feature, because the returned slots are the answer, not the raw material for one.

Find slots across participants from the CLI

nylas calendar availability find is the terminal version, and it's built for exactly the "when can these people meet" question. You pass --participants with the email list and --duration in minutes, and it searches for slots when everyone is free. Bound the search with --start and --end, and set the granularity with --interval.

# 30-minute slots for two people, tomorrow 9am to 5pm
nylas calendar availability find \
  --participants alice@example.com,bob@example.com \
  --duration 30 --start "tomorrow 9am" --end "tomorrow 5pm" --interval 15

The defaults are sensible for a quick look: duration is 30 minutes, the interval is 15, and the window runs from the next hour to seven days out if you don't set an end. That means nylas calendar availability find --participants alice@example.com with nothing else gives you a week of half-hour openings on the spot. It's the command I use to sanity-check that a real participant set produces the slots I expect before wiring the same call into an app.

Constrain to working hours with open_hours

A meeting at 3am is technically free but useless, so availability lets you constrain each participant to their working hours. Every entry in the participants list takes an open_hours array describing the days and times that person is bookable: days as numbers where 0 is Sunday, a timezone, and a start and end like "9:00" and "17:00". The API only proposes slots inside those hours, so a participant in Toronto and one in Berlin each get evaluated against their own local day.

That per-participant timezone handling is the detail that makes cross-timezone scheduling actually work. You're not converting anything by hand; each person's open_hours carries its own timezone, and the returned slots are the genuine overlap of everyone's local working day. You can also set a default_open_hours on the availability_rules to apply one schedule to participants who don't specify their own, which keeps the request small when most people share a working day.

Choose how slots are scored with availability_method

When you're booking against a group, how the slots get chosen matters, and availability_method on the availability_rules controls it. It takes three values. The default, max-availability, returns slots that work across the participants and is the right pick for an ordinary group meeting. collective requires every participant to be free for a slot to count, which is what you want when attendance is mandatory for all.

The third, max-fairness, is for round-robin booking: when any one of a pool of people can take the meeting, it distributes bookings evenly across the pool rather than always picking the same person. That's the mechanism behind "talk to one of our reps" scheduling, where you don't care who takes it but you do care that the load spreads. Pair it with a buffer of before and after minutes on the rules to keep back-to-back meetings from touching, and the availability response already accounts for the gap. Picking the method to match the booking model is what separates a real scheduler from a naive free-slot list.

Cross-provider behavior and gotchas

A few provider details decide whether a request behaves the way you expect. Free/busy isn't supported for iCloud, and all the email addresses in a single free/busy request have to use the same provider, so you can't mix a Google and a Microsoft address in one call. The address limits differ too: a single free/busy request takes up to 50 emails for Google and up to 20 for Microsoft Graph, so a large group may need to be split across calls.

There are quieter limits worth knowing. Microsoft caps its availability calculation at 1,000 entries per time slot per address, and the free/busy response leaves out all-day room resource bookings on both Google and Microsoft, so a room that's blocked all day can still look free in the raw data. The grant making the request also has to have permission to see the target calendars' free/busy, which the provider controls, so a permission gap shows up as an error entry with a null time_slots rather than as an outright failure. None of these are blockers, but each is the kind of thing that turns into a confusing bug if you learn it in production instead of up front.

Where availability lookups pay off

The same two endpoints sit under a whole category of scheduling features, and which one you pick follows the pattern above. A few that map straight on:

A booking page. Show a visitor the open slots on a host's calendar, the classic "pick a time" widget, which is availability with one participant and the host's open_hours.
Internal meeting scheduling. Find a slot for a group before creating the event, using collective so everyone's required, then create the event at the chosen slot.
Round-robin assignment. Spread inbound meetings across a team with max-fairness, so the next sales call or support session lands on whoever's most due for one.
Interview panels. Intersect several interviewers' calendars within working hours to find a panel slot, which is availability with multiple participants and buffers.

Each is the same call with different rules, not a different integration. The slot-finding is solved; your job is choosing the method and the constraints that match the booking model.

Things to keep in mind

A short list of details keeps an availability feature correct.

Default to availability, not free/busy. Availability returns the free slots directly; reaching for free/busy means rebuilding slot intersection by hand.
Free/busy always returns 200. Check each entry, since a failed lookup for one address comes back as a null time_slots rather than an error.
Set open_hours per participant. It carries its own timezone, so cross-timezone overlap is computed for you instead of by hand.
Match availability_method to the model. collective for mandatory attendance, max-fairness for round-robin, max-availability for an ordinary group.
Mind the provider limits. Free/busy excludes iCloud, needs one provider per request, and caps emails at 50 for Google and 20 for Microsoft.
Add buffers for real schedules. A buffer before and after keeps proposed slots from butting against existing meetings.

Wrapping up

Finding a meeting time comes down to choosing the right endpoint. Free/busy hands you raw busy blocks to process yourself, and availability hands you the open slots directly, which is what most scheduling features actually want. Send participants, a window, and a duration_minutes to the availability endpoint, constrain each person with open_hours carrying their own timezone, and pick an availability_method that fits whether attendance is mandatory or round-robin. From the terminal, nylas calendar availability check shows busy blocks and availability find shows open slots, so you can confirm a real participant set before you build.

Where to go next:

Get availability — the endpoint, with participants, open_hours, and availability_rules
Get free/busy schedule — raw busy blocks and provider limits
Group availability and booking — round-robin and max-fairness in depth
Using the Events API — create the event once you've picked a slot

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/availability-api-for-bookable-times-in-app.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Track email opens and clicks with the Nylas API

Qasim — Thu, 23 Jul 2026 11:53:16 +0000

You sent an important email and now you're staring at the thread wondering: did they even open it? Did they click the link you sent? For a sales follow-up, a newsletter, or a transactional message you need to land, that silence is a problem. Email tracking answers the question by telling you when a recipient opens a message, clicks a link inside it, or replies to the thread. This post wires that up with the Email API and shows the CLI flags that turn it on from the terminal.

It's a worked use case rather than an endpoint tour, covering the tracking_options you set on a send and the tracking webhooks you receive, from two angles: the HTTP API your backend calls and the nylas CLI for sending a tracked message fast. I work on the CLI, so the commands below are the ones I reach for when I want to see tracking fire end to end.

Three things you can track

Tracking comes in three flavors, and you choose which ones you want per message. Open tracking tells you when a recipient first opens the message. Link tracking tells you when they click a link inside it, and which link. Reply tracking tells you when someone replies to the thread. Each is a separate boolean you flip on at send time, so a message can carry any combination of the three.

The reason they're separate is that they answer different questions and have different reliability. An open is the lightest signal and the easiest to miss, since it depends on the recipient's email client loading an image. A click is a stronger signal of real intent, because someone deliberately acted. A reply is the strongest of all, an explicit response. Most teams turn on opens and links together, because opens alone undercount and the two together give a fuller picture of engagement than either by itself.

Enable tracking when you send

You turn tracking on by adding a tracking_options object to a POST /v3/grants/{grant_id}/messages/send request. It has three boolean fields, opens, links, and thread_replies, each defaulting to false, plus an optional label string. Set the ones you want to true, and the message goes out instrumented for exactly those events. One prerequisite: tracking needs a production application, since a sandbox (trial) account rejects the request with "Tracking options are not allowed for trial accounts."

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 '{
    "to": [{ "email": "prospect@example.com" }],
    "subject": "Following up",
    "body": "<p>Hi, just checking in. <a href=\"https://example.com/demo\">Book a demo</a>.</p>",
    "tracking_options": {
      "opens": true,
      "links": true,
      "thread_replies": true,
      "label": "demo-follow-up"
    }
  }'

Notice the body is HTML with a real anchor tag, which matters for the next sections. The label is a free-text description, up to 2,048 characters, that rides along with the tracking data so you can tell later why a message was tracked or which campaign it belonged to. The same tracking_options object works when you create a draft, so a message reviewed before sending can carry tracking too.

Send a tracked message from the CLI

The CLI exposes the same three toggles as flags on nylas email send. Pass --track-opens to instrument opens, --track-links for clicks, and --track-label to attach a grouping label. There's no separate reply flag, so for thread reply tracking you reach for the API's thread_replies field, but opens and links, the two most teams use, are one flag each.

nylas email send \
  --to prospect@example.com \
  --subject "Following up" \
  --body "<p>Hi, just checking in. <a href='https://example.com/demo'>Book a demo</a>.</p>" \
  --track-opens --track-links --track-label "demo-follow-up"

This is the fastest way to confirm tracking works before you build it into an app: send yourself a tracked message, open it, click the link, and watch the events arrive. The nylas email tracking-info command prints a reference of the tracking features and the webhook payloads they produce, which is handy when you're setting up the listener and want the shapes in front of you.

Receive the events through webhooks

Tracking is delivered asynchronously, so the events come to you as webhooks rather than in the send response. You subscribe to three triggers that map one-to-one onto the options: message.opened fires on an open, message.link_clicked on a click, and thread.replied on a reply. Each POST to your endpoint carries the message_id and the details of what happened.

app.post("/webhooks/nylas", async (req, res) => {
  res.sendStatus(200); // acknowledge fast
  const { type, data } = req.body;
  const obj = data.object; // tracking payload nests under data.object
  if (type === "message.opened") {
    await recordOpen(obj.message_id, obj.recents);
  } else if (type === "message.link_clicked") {
    // recents = each individual click; link_data = aggregate [{ url, count }]
    await recordClicks(obj.message_id, obj.recents, obj.link_data);
  } else if (type === "thread.replied") {
    await recordReply(obj);
  }
});

The tracking fields sit under data.object, not directly on data, so reach for data.object.message_id and friends. An open event's recents array carries each open with a timestamp, the recipient's ip, and user_agent. A click event carries both a recents array of individual clicks and a link_data array listing each tracked url with a running count, so you see not just that a link was clicked but which one and how often. One indexing quirk to know: the event count starts at 1, while the opened_id and click_id indices start at 0, so don't conflate the two when you store them.

How open tracking actually works

Open tracking is a transparent one-pixel image. When you enable it, Nylas inserts that pixel into the message's HTML, and when the recipient's email client renders the message, it requests the image from the tracking server, which records the open. That mechanism has two consequences worth designing around, because they decide how much you can trust an open.

First, it needs HTML and a client that loads remote images. Ad blockers, corporate proxies, and content delivery networks can all intercept the pixel request, so an open that never registers doesn't mean the message wasn't read. Open rates run lower than reality for this reason, especially since some clients pre-fetch or block images by default. Second, repeated loads are deduplicated: if the pixel is fetched several times within one minute, only the first counts as an open, so a client that reloads doesn't inflate your numbers. The practical takeaway is to treat opens as a floor, not a precise count, and to pair them with link tracking for a signal that doesn't depend on image loading.

How link tracking actually works

Link tracking works by rewriting links, and the detail that trips people up is that it's all-or-nothing per message. When you enable it, the service rewrites every valid HTML link in the body to route through a tracking redirect, then forwards the click to the real destination. You can't track only some links and leave others alone; enabling link tracking instruments all of them.

For a link to be rewritten, it has to be a properly formed HTML anchor with a valid URI, like <a href="https://example.com">demo</a>. A bare www.example.com with no anchor tag won't be tracked, because there's nothing to rewrite. There's also a security carve-out: links carrying embedded login credentials are deliberately left alone, since rewriting them would break the destination's authentication. A private Google Form URL, for instance, contains credentials, so it's skipped, the link still works when clicked but produces no tracking event. Knowing these rules up front saves you from debugging a "missing" click that was never trackable to begin with.

Track replies, and label what you track

Reply tracking is the third option and the most reliable signal, because a reply is an explicit human action with nothing to block or rewrite. Set thread_replies to true and a thread.replied webhook fires when someone responds on the thread, which is how you detect engagement on a message that asked for one without polling the mailbox for new messages yourself.

The label field is the small piece that makes tracking data usable at scale. It's an optional description, up to 2,048 characters, attached at send time and carried through to the events, so when a message.opened arrives you can tell which campaign or message type it belongs to without a separate lookup. Use it to group a batch, a "march-newsletter" or "trial-day-3" label, and your analytics can bucket events by intent rather than by an opaque message ID. It costs nothing to set and saves a join later.

Don't delete a grant you're still tracking

One lifecycle detail bites people who don't know it. Tracking links and pixels are tied to the grant that sent the message, and if you delete that grant, the tracking stops working: the service can no longer match an incoming open or click to the deleted grant, so you lose tracking events for every message that grant sent, including ones already out in the wild. An expired grant is gentler, you still receive message.opened events on it, but a deleted one is a hard cutoff.

The rule that follows is the same one that applies across the API: re-authenticate an expired grant in place rather than deleting and recreating it. A delete-and-recreate cycle silently breaks tracking on every message the old grant ever sent, which surfaces as analytics that mysteriously go quiet for older sends. If you're running campaigns whose tracking matters for weeks after sending, treat grant deletion as the destructive operation it is for your tracking data.

Where tracking pays off

The same three options sit under a range of features, and which you enable follows the signal you need. A few that map straight on:

Sales follow-up timing. An open or click tells a rep the moment a prospect engaged, so the next touch lands when interest is fresh instead of on a fixed schedule.
Newsletter analytics. Open and click rates across a batch, grouped by label, show which subject lines and links actually performed.
Engagement-driven sequences. A thread.replied event advances or stops an automated sequence, so a reply pauses the follow-ups instead of a customer getting nagged after they already answered.
Delivery confidence. For a transactional message that must land, a registered open is a lightweight signal that it reached a real inbox, though a missed pixel never proves the opposite, so pair it with a click for certainty.

Each is the same tracking_options on a send plus a webhook listener, with the difference being which events you act on and how.

Things to keep in mind

A short list of details keeps tracking honest.

Opens undercount. The pixel depends on image loading, so ad blockers and CDNs suppress some opens; treat the number as a floor and pair it with links.
Link tracking is all-or-nothing. Enabling it rewrites every valid HTML link in the message; you can't instrument only some.
Use real anchor tags. Only properly formed <a href> links with valid URIs get rewritten; bare text URLs and credential-bearing links are skipped.
Events arrive by webhook. Subscribe to message.opened, message.link_clicked, and thread.replied; nothing comes back in the send response.
Label your sends. The optional label, up to 2,048 characters, groups events by campaign so your analytics don't hinge on raw message IDs.
Don't delete grants mid-campaign. Deleting a grant kills tracking for every message it sent; re-authenticate an expired grant instead.

Wrapping up

Email tracking turns a silent send into a measurable one. Add a tracking_options object with opens, links, or thread_replies to a send, or pass --track-opens and --track-links from the CLI, and the events arrive as message.opened, message.link_clicked, and thread.replied webhooks carrying timestamps, IPs, and the clicked URLs. Remember that opens undercount because they rely on a loaded pixel, that link tracking rewrites every valid link or none, and that deleting a grant breaks tracking for everything it sent. Label your sends and lean on clicks and replies for the signals that matter.

Where to go next:

Track messages — the full guide to opens, links, and replies
Send a message — the tracking_options field and other send options
Webhook notifications — subscribing to the tracking triggers
Handling expired grants — why to re-authenticate instead of delete

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/email-open-click-tracking-saas-crm.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Clean quoted replies from email with the Nylas API

Qasim — Mon, 20 Jul 2026 22:27:23 +0000

Open a five-message reply chain and look at how much of it is actually new. One or two sentences at the top, then a wall of quoted history, a signature, a legal disclaimer, and "Best regards." For a human skimming, that noise is just clutter. For code, it's worse: feed that blob to a language model for summarization and you're paying for tokens of quoted text the model has already seen, and showing it as a preview means the same quoted chain on every message. Cleaning email pulls out just the meaningful text, and this post wires it up with the Email API and the CLI.

It's a worked use case rather than an endpoint tour, covering the clean conversation endpoint and the cleaned-message webhook from two angles: the HTTP API your backend calls and the nylas CLI for cleaning a message from the terminal. I work on the CLI, so the commands below are the ones I reach for when I want to see what cleaning actually returns.

Two ways to clean a message

There are two paths, and which you pick depends on whether you have a message in hand or want every incoming message cleaned automatically. The on-demand path is a single endpoint: you pass one or more message IDs and get back the cleaned text, which suits a "summarize this thread" button or a one-off processing job. The automatic path is a webhook, message.created.cleaned, that fires a cleaned version of every new message once you enable the Clean Conversations feature for your application.

The distinction matters for how you build. On-demand cleaning is synchronous and you control when it runs, so it's the natural fit when a user acts on a specific message or you're backfilling a batch. The webhook is push-based and hands you cleaned content the moment mail arrives, which is what you want when every message flows into a pipeline that needs the text stripped before anything downstream touches it. Many apps use both: the webhook for the steady stream, the endpoint for on-demand reprocessing.

Clean a message on demand

The on-demand endpoint is a PUT /v3/grants/{grant_id}/messages/clean with a message_id array of the messages to clean, up to 20 in a single call. The response returns each message with a conversation field holding the cleaned text, the quoted chain and signature removed, alongside the original message data so you keep the metadata.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/clean" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "message_id": ["18df98cadcc8534a"],
    "ignore_links": true,
    "remove_conclusion_phrases": true
  }'

The cleaned result lands in conversation, so that's the field you read, not body, which still carries the original. Batching up to 20 IDs per call is the detail that makes this practical for a job: cleaning a thread or a day's worth of messages is a handful of requests, not one per message. Each cleaned message comes back keyed to its ID, so you can match the output to the input when you send several at once.

The operation is non-destructive, which is worth saying plainly: cleaning returns a parsed copy and never modifies the stored message. The original stays intact in the mailbox and in the body field, so you can clean the same message repeatedly with different options, once with links stripped for a model and again with links kept for display, without any risk of losing the source. That makes it safe to call freely in a pipeline, and safe to reprocess later if you change which options you want, since there's no state to undo. Treat the cleaned conversation as a derived view you can regenerate any time, not a one-way transformation of the message.

Clean a message from the CLI

The terminal command is nylas email clean followed by one or more message IDs, and it does the same parse, returning just the meaningful text with quoted chains, signatures, and conclusion phrases like "Best" and "Regards" removed. By default it strips links, images, tables, and those signature phrases, and the plain-text output has HTML tags removed so it's readable at a glance.

# Clean one message; keep links in the output
nylas email clean <message-id> --keep-links

# JSON output with the raw cleaned HTML in the "conversation" field
nylas email clean <id-1> <id-2> --json

The --keep-* flags, --keep-links, --keep-images, --keep-tables, and --keep-signatures, turn off individual stripping when you want something retained, and --images-as-markdown returns images as Markdown links instead. Like the endpoint, it cleans up to 20 messages in one call, and --json gives you the raw cleaned HTML in the conversation field for piping into a script. This is the fastest way to see what cleaning does to a real message before you wire the endpoint into anything.

What gets stripped, and how to keep it

Cleaning is opinionated by default, and knowing the defaults saves surprises. The endpoint's boolean options, ignore_links, ignore_images, ignore_tables, and remove_conclusion_phrases, all default to true, so out of the box a clean strips links, images, tables, and sign-off phrases along with the quoted history. That's the right default for feeding text to a model, where none of that markup helps, but it's aggressive if you're cleaning for display.

To retain something, set its option to false. If you're cleaning a message to show a readable preview and you want the links live, send ignore_links: false, and the anchor tags survive. The mapping to the CLI is the --keep-* flags, which flip the same switches from the terminal. The thing to internalize is that the defaults remove more than just the quoted chain, so when a cleaned result is missing something you expected, the fix is usually a false on one of these options rather than anything more involved.

One honest caveat: cleaning is heuristic. It's very good at the common signature and quote patterns, but an unusual layout can leave a stray fragment or trim a line you wanted, so spot-check the output on real mail before you trust it in a pipeline. It's reliable enough to build on, just not so perfect that you should skip eyeballing a sample first.

Get Markdown out for a language model

Since the most common reason to clean a message is to feed it to a model, the API can hand you Markdown directly. Setting images_as_markdown to true, which is itself the default, converts images to Markdown image syntax, and the beta html_as_markdown option converts the whole message to Markdown rather than returning HTML or plain text. One constraint ties them together: html_as_markdown can't be true while images_as_markdown is false, since converting the document to Markdown but leaving images as raw HTML would be inconsistent.

Markdown is the format most language models handle best, so converting at the cleaning step means the text is model-ready without a second pass through a converter of your own. The plain-text path is still there when you want it, the CLI strips HTML tags from its default output, but for a retrieval or summarization pipeline, asking for Markdown at clean time keeps the formatting cues a model can actually use, like headings and lists, while dropping the HTML scaffolding it can't.

Clean every message automatically with a webhook

When you want cleaning to happen to every message without calling the endpoint each time, enable Clean Conversations for your application and subscribe to the message.created.cleaned webhook. It fires for each new synced message and delivers the cleaned content in the message body as Markdown, so your pipeline receives stripped text the moment mail lands, with no extra call on your side.

Two behaviors are worth knowing before you rely on it. First, subscribing to message.created.cleaned does not suppress the regular message.created notification, so if you subscribe to both you get two separate webhooks per new message, the raw one and the cleaned one. Subscribe only to the cleaned trigger if the cleaned text is all your pipeline needs. Second, each cleaned notification carries a cleaning_status field, and when it comes back as failed, the body holds the original uncleaned HTML rather than cleaned text, with a cleaning_error describing what went wrong. So branch on cleaning_status before you assume the body is clean.

app.post("/webhooks/nylas", async (req, res) => {
  res.sendStatus(200); // acknowledge fast
  const { type, data } = req.body;
  if (type !== "message.created.cleaned") return;
  const msg = data.object;
  if (msg.cleaning_status !== "success") return; // body is raw HTML on failure
  await indexForRetrieval(msg.id, msg.body); // cleaned markdown
});

Where cleaning pays off

The same cleaning step sits under a range of features, and the reason is always the same: downstream code wants the new message, not the thread's whole history. A few that map straight on:

Feeding email to an LLM. Summarization, classification, and retrieval all work better and cost less on cleaned text, since the quoted chain is repeated context the model doesn't need and you'd otherwise pay to process.
Readable previews. A message list that shows the actual new content instead of "On Tuesday, X wrote:" reads far better, and cleaning with links kept gives you that.
Reply extraction. Pulling just the latest reply from a long back-and-forth, for a support tool or a CRM note, is exactly what removing the quoted chain does.
Search indexing. Indexing cleaned bodies keeps your search index free of duplicated quoted text, so a query doesn't match the same sentence echoed across ten replies.

Each is the same clean call with different options, the difference being whether you keep links and images for display or strip everything for a model.

Things to keep in mind

A short list of details keeps cleaning predictable.

Read the conversation field. The on-demand endpoint returns cleaned text in conversation, while body still holds the original message.
Defaults strip aggressively. ignore_links, ignore_images, ignore_tables, and remove_conclusion_phrases all default to true; set one to false or use a --keep-* flag to retain it.
Twenty messages per call. Both the endpoint and the CLI clean up to 20 IDs at once, so batch a thread rather than looping one at a time.
The cleaned webhook doesn't replace message.created. Subscribe to both and you get two notifications per message; subscribe only to .cleaned if that's all you need.
Check cleaning_status. On a failed status the webhook body is the original uncleaned HTML, so branch on it before treating the body as clean.
Ask for Markdown for models. html_as_markdown returns model-ready Markdown, and it can't be true when images_as_markdown is false.

Wrapping up

Cleaning turns a noisy reply chain into just the text that matters. Call PUT /v3/grants/{grant_id}/messages/clean with up to 20 message IDs, or run nylas email clean, and read the cleaned result from the conversation field, remembering the defaults strip links, images, tables, and sign-off phrases unless you keep them. For a steady stream, enable Clean Conversations and take the message.created.cleaned webhook, branching on cleaning_status and knowing it arrives alongside the raw message.created, not instead of it. Ask for Markdown when the destination is a language model, and you've got message text that's ready to summarize, index, or display.

Where to go next:

Clean conversation — the full guide to cleaning options
Clean messages — the endpoint reference and all options
Parse messages — the Clean Conversations feature and the cleaned webhook
Webhook notifications — subscribing to message triggers

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/email-body-parsing-api-for-python-agents.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Connect a mailbox with Nylas hosted OAuth

Qasim — Mon, 20 Jul 2026 22:27:12 +0000

Before your app can read a single email or calendar event, the user has to give it permission. That permission is an OAuth handshake with their provider, Google, Microsoft, or another, and getting it right means redirect URIs, scopes, token exchange, and refresh tokens. Hosted OAuth hands that whole dance to Nylas: you send the user to a hosted authorization URL, they approve access at their provider, and you get back a grant you can use to call the email, calendar, and contacts APIs. This post walks the flow with the API and shows the CLI command that does it in one step.

It's a worked use case rather than an endpoint tour, covering the hosted OAuth flow from two angles: the HTTP endpoints your backend calls and the nylas CLI for connecting an account from the terminal. I work on the CLI, so the commands below are the ones I reach for when I want a grant to test against fast.

What a grant is, and the two-step flow

The thing you're after is a grant: a stored connection to one user's account that the API uses to act on their behalf. Every email you read, event you create, or contact you fetch is scoped to a grant_id, so connecting an account means producing one. Hosted OAuth produces it in two steps, and understanding the split is most of the battle.

First, you send the user to a hosted authorization URL, where they sign in to their provider and approve the access your app is asking for. The provider sends them back to your app with a temporary authorization code. Second, your backend exchanges that code for a grant by calling a token endpoint. The code is short-lived and single-use, a one-time proof that the user approved; the grant it becomes is the durable handle you keep. That two-step shape, redirect for consent, then exchange on the server, is standard OAuth 2.0, and Nylas runs the provider-specific parts of it for you.

Step 1: send the user to the authorization URL

The flow starts at /v3/connect/auth, which you build into a URL and redirect the user to. The required query parameters are client_id (your Nylas application's ID), redirect_uri (where the provider sends the user back, and it must match a URI registered on your application), and response_type=code to ask for the authorization code flow. A provider parameter preselects a supported provider such as Google or Microsoft, and login_hint prefills the user's email.

https://api.us.nylas.com/v3/connect/auth?client_id=<NYLAS_CLIENT_ID>&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&provider=google&login_hint=user@example.com

You don't fetch this URL server-side; you redirect the user's browser to it, because they need to see and approve the provider's consent screen. A couple of optional parameters matter for real apps: state carries an opaque value you generate and check when the user returns, which is your defense against cross-site request forgery on the callback, and access_type=offline asks for a refresh token so your access survives past the first hour. Set state on every real integration, not just as a nicety.

Step 2: exchange the code for a grant

When the user approves, the provider redirects them to your redirect_uri with a ?code= query parameter. Your backend then exchanges that code at POST /v3/connect/token for the grant. The request needs client_id, client_secret (your Nylas API key), redirect_uri matching the one from step one, grant_type: authorization_code, and the code itself.

curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/token" \
  --header "Content-Type: application/json" \
  --data '{
    "client_id": "<NYLAS_CLIENT_ID>",
    "client_secret": "<NYLAS_API_KEY>",
    "redirect_uri": "https://yourapp.com/callback",
    "grant_type": "authorization_code",
    "code": "<CODE_FROM_CALLBACK>"
  }'

The response carries the grant_id and the connected email, plus an access_token and, if you asked for offline access, a refresh_token. The grant_id is the one you store: it's the handle for every subsequent call. This exchange has to happen on your server, never in the browser, because it carries your API key in client_secret. Putting that key in client-side code would hand anyone who views source the keys to your whole application, so the token exchange is a backend-only step by design.

Connect an account from the CLI

Running both steps by hand is the right model for a production app, but for testing you want a grant now, and the CLI does the entire handshake in one command. For a browser-based provider, nylas auth login opens your browser to the consent screen, captures the redirect, exchanges the code, and stores the resulting grant locally, all from a single command.

# Connect a Google account (the default)
nylas auth login

# Connect a Microsoft account instead
nylas auth login --provider microsoft

The --provider flag picks the provider, defaulting to google, and the OAuth providers, google, microsoft, and ews, open a browser, while the credential providers prompt you in the terminal instead. Once you're connected, nylas auth status shows the active grant, nylas auth list shows every account you've connected, and nylas auth switch flips between them. This is the fastest path from nothing to a working grant you can run real email and calendar commands against, without standing up a callback server first.

OAuth providers versus credential providers

Not every provider authenticates the same way. Google, Microsoft, Yahoo, and Zoom have a true OAuth consent screen, so the redirect flow above sends the user to their provider to approve access, and the authorization URL's provider parameter accepts each of them. iCloud, generic IMAP, and on-premises Exchange (EWS) have no such consent screen, and authenticate with credentials instead: iCloud with an Apple app-specific password the user generates in their account settings, IMAP with direct server credentials, and EWS with Exchange login details.

For those credential-based providers, you create the grant from the credentials you collect, commonly through the custom bring-your-own endpoint, /v3/connect/custom, which also handles bulk and IMAP provisioning. Whichever way an account connects, the same grant_id comes out, so once it's done, the rest of your code doesn't care which method produced it, the email and calendar calls are identical across providers.

One caveat if you connect test accounts with the CLI: nylas auth login covers the email providers, Google, Microsoft, Yahoo, iCloud, IMAP, and EWS, and labels them by interaction style rather than by protocol, opening a browser for Google, Microsoft, and EWS and prompting in the terminal for iCloud, Yahoo, and IMAP. That grouping is a CLI convenience, not a statement about each provider's auth mechanism, so don't read the CLI's browser-or-prompt labels as the provider's protocol.

Keep access alive with refresh tokens

An access token is short-lived, an hour for the short-lived variety, so an integration that needs to keep working past that first hour relies on the refresh token you get when you request offline access. That's why access_type=offline on the authorization URL matters: without it, you get access that expires and can't be renewed without sending the user through consent again. With it, your backend can mint a fresh access token whenever the old one expires.

Refreshing is the same token endpoint with a different grant_type. You call POST /v3/connect/token with grant_type: refresh_token, your client_id, the refresh_token you stored, and your API key in client_secret, and you get a new access token back. The practical rule is to request offline access up front for any integration meant to run unattended, and to refresh on demand when a call comes back unauthorized, rather than sending the user back through the consent screen, which should be a last resort reserved for a grant that's genuinely been revoked.

Manage and inspect grants

Once accounts are connected, you'll want to see and manage them. From the CLI, nylas auth whoami shows the current user, nylas auth scopes prints the OAuth scopes a grant was granted, and nylas auth show prints detailed grant information, which is the first place to look when a call fails with a permissions error. To disconnect, nylas auth revoke permanently revokes a grant on the server, while nylas auth remove just drops it from your local config and leaves the grant intact on the server.

That distinction between revoke and remove is worth holding onto, because they're not the same operation. Revoking ends the connection for real and the user would have to reconnect; removing only forgets it locally. When you're cleaning up test accounts, removing keeps the grant usable from elsewhere, while revoking is the destructive one. Over the API, ending a connection for good is a DELETE /v3/grants/{grant_id}, which removes the grant itself, so your app can give users a clean "disconnect my account" action that actually ends the access. Don't confuse that with /v3/connect/revoke, which revokes an access token but leaves the grant in place, so the user can re-authenticate to the same grant_id.

Where hosted OAuth fits

The same connect flow sits at the front of every Nylas integration, and the variations are mostly about who's connecting and how. A few common shapes:

A SaaS connecting its users' mailboxes. Each user runs the redirect flow once, you store their grant_id against their account, and every feature you build reads from that grant.
A single backend account. An internal tool that sends from one company mailbox connects that one account, often via the CLI, and uses the resulting grant for everything.
An agent with its own inbox. A Nylas Agent Account gets its own grant, so an automated agent reads and sends mail from an address it owns, the same grant model with no human at the keyboard.
Multi-provider support. Because the grant is provider-agnostic once created, supporting Google and Microsoft users is the same code path after the connect step diverges on provider.

Each starts with producing a grant, and from there the email, calendar, and contacts APIs are identical regardless of how the account was connected.

Things to keep in mind

A short list of details keeps the connect flow secure and reliable.

Exchange the code server-side. The token call carries your API key as client_secret; never run it in the browser, or you leak the key.
Set state on the authorization URL. It's your CSRF defense on the callback; generate it, pass it, and verify it when the user returns.
Request access_type=offline for lasting access. Without a refresh token, your access expires in about an hour and can't be renewed without re-consent.
The grant_id is the durable handle. Store it against your user; the authorization code is single-use and short-lived, the grant is what persists.
Revoke and remove differ. Revoking ends the connection on the server; removing only forgets it locally, leaving the grant usable.
Match the redirect_uri exactly. It must be registered on your application and identical in both steps, or the exchange fails.

Wrapping up

Connecting a mailbox is a two-step OAuth flow that Nylas runs for you. Redirect the user to /v3/connect/auth with your client_id, redirect_uri, and response_type=code, let them approve at their provider, then exchange the returned code at POST /v3/connect/token on your backend to get a grant_id. Store that grant, request offline access so it survives past an hour, and protect the callback with state. For testing, nylas auth login collapses the whole handshake into one command. However the account connects, OAuth or credentials, Google or Microsoft, the grant that comes out is the single handle every other API call needs.

Where to go next:

Authentication — the full hosted OAuth guide
Hosted OAuth with an access token — the token exchange and PKCE in depth
Grant lifecycle best practices — refreshing and re-authenticating grants
Nylas CLI auth commands — nylas auth login, status, and revoke

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/oauth-mailbox-integration-api-gmail-outlook.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Search a mailbox with the Nylas Email API

Qasim — Mon, 20 Jul 2026 22:27:02 +0000

Sooner or later your app needs to find specific messages: every email from one sender, everything with "invoice" in the subject, unread mail from last week, or a complex query only Gmail's search box can express. Nylas gives you two ways to do this, and they trade off against each other. Standard query parameters are normalized across providers, so largely one code path searches Gmail and Outlook alike, give or take a few provider-specific constraints. The search_query_native parameter lets you pass the provider's own query language for power searches the standard set doesn't cover. This post walks both with the Email API and shows the CLI for the portable one.

It's a worked use case rather than an endpoint tour, covering searching messages from two angles: the HTTP API your backend calls and the nylas CLI for searching from the terminal. I work on the CLI, so the commands below are the ones I reach for when I just need to find a message.

Two ways to search

The split is between portable and provider-specific. Standard query parameters, things like from, subject, unread, and date filters, are normalized by Nylas, so the same request returns matching messages whether the account is Google, Microsoft, or IMAP. You write the search once and it works across providers, which is the whole point of an abstraction layer over many of them, though a couple of providers add constraints covered later.

The search_query_native parameter goes the other direction. It takes a URL-encoded query string in the provider's own search language, Gmail's operators or Microsoft Graph's $filter syntax, and runs it directly against that provider. You give up portability, since a Gmail query string means nothing to Outlook, in exchange for the full expressive power of the provider's native search. The rule of thumb: reach for standard parameters first, and drop to search_query_native only when you need a query the standard set can't express.

Search with standard parameters

The portable path is the standard query parameters on a GET /v3/grants/{grant_id}/messages request. You combine from, to, subject, unread, starred, has_attachment, the received_after/received_before date range, and in for a folder, and Nylas returns the messages matching all of them. These are normalized across providers, so this is the search to build on for anything that has to work across your users' providers, give or take the provider-specific constraints noted below.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?from=boss@example.com&unread=true&received_after=1704067200" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

Each parameter narrows the result, and they combine with AND, so the request above returns unread messages from one sender after a given date. One folder gotcha to know up front: the in parameter takes a folder ID, not a name. Passing in=inbox as a keyword returns a 400 error, because Nylas doesn't resolve folder keywords; you look up the folder's ID first and pass that. It's the single most common surprise with standard search.

Search from the CLI

The terminal command nylas email search runs the same standard-parameter search and is the fastest way to find a message without writing a request. You pass a query string for the subject and add flags that map to the parameters above: --from, --to, --subject, --in for a folder, --after and --before for dates, and --unread, --starred, or --has-attachment to narrow further.

# Unread mail from one sender, with an attachment
nylas email search "*" --from "hr@example.com" --has-attachment --unread

# Anything matching "invoice" in a date range
nylas email search "invoice" --after 2024-01-01 --before 2024-12-31

The * query is the "any subject" wildcard, which you use when you're filtering by sender or attachment rather than text, and the date flags take a friendly YYYY-MM-DD format instead of the Unix timestamps the raw API wants. The command defaults to 20 results and auto-paginates past 200 if you raise --limit, so a broad search won't quietly stop at the first page. It's the portable search, so it behaves consistently across providers, whichever one the active grant connects to, subject to the constraints noted below.

Run a Gmail power query with search_query_native

When the standard parameters can't express what you want, and Gmail's search can, you pass a Gmail query string through search_query_native. Gmail supports operators like older_than:, has:attachment, label:, and boolean OR that the standard set doesn't surface. You write the query in Gmail's syntax, URL-encode it, and put it in the parameter.

# Gmail query: subject:foo OR subject:bar  (URL-encoded)
curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?search_query_native=subject%3Afoo%20OR%20subject%3Abar" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

The decoded query there is subject:foo OR subject:bar, and the encoding turns the colon into %3A and the spaces into %20. This runs against Gmail's own index, so any operator Gmail's web search accepts works here, which is a lot of expressive power you'd otherwise have to approximate with several standard requests. The catch is that it's Gmail-only: the same string sent to an Outlook account is meaningless, so you branch on the provider before choosing a native query.

Run a Microsoft Graph query with search_query_native

Microsoft accounts take the same parameter with Graph's query syntax instead. Microsoft Graph uses $filter expressions, so a query for messages from a specific address is $filter=from/emailAddress/address eq 'leyah@example.com', URL-encoded into the parameter. The mechanism is identical to the Gmail case, only the query language changes.

# Graph $filter: from address eq leyah@example.com  (URL-encoded)
curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?search_query_native=%24filter%3Dfrom%2FemailAddress%2Faddress%20eq%20%27leyah%40example.com%27" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

That decodes to $filter=from/emailAddress/address eq 'leyah@example.com', with $ becoming %24 and the quotes and slashes encoded too. Because Graph's $filter and Gmail's operators are entirely different languages, a real multi-provider app keeps a native query per provider and picks the right one based on the connected account, falling back to standard parameters for any provider it doesn't have a native query for. Nylas also supports native queries for EWS and IMAP, each in that provider's own search syntax.

The companion-parameter limits

Native queries come with a restriction that trips people up. When you include search_query_native in a messages request, you can only pair it with a limited set of standard parameters, and on Google and Microsoft that set is just in, limit, and page_token. Add any other standard parameter alongside a native query on those providers and the request errors, because the native query is meant to carry the filtering itself.

The thread endpoint is even stricter: with search_query_native on a threads request, only in, limit, and page_token are allowed on every provider except EWS, and any other parameter returns an error. The practical consequence is that you don't mix the two styles. Either you express the whole search in standard parameters, or you express it in the native query and let in, limit, and page_token handle only paging and folder scope. Deciding which style owns a given search up front avoids the error entirely.

Microsoft Graph adds a separate rule even within standard parameters: two groups of them are mutually exclusive on Graph accounts. One group is the broad category filters, thread_id, unread, and starred; the other is the envelope fields, subject, to, cc, bcc, and any_email. Use a parameter from one group and you can't combine it with one from the other, so you can't, for example, filter starred threads that are also to a specific address in a single Graph request. It's a Microsoft-only constraint, so portable standard search still works elsewhere, but it's worth knowing before a two-filter Graph query fails.

On-premises Exchange (EWS) has its own caveats. Standard search there only works if an administrator has enabled mailbox search indexing and the server supports the AQS parser, its date filters resolve to same-day granularity rather than an exact timestamp, and the accuracy of to, from, cc, bcc, and any_email depends on how fast the server has indexed recent mail, so a message that just arrived may not match until the next index refresh. None of this affects Gmail or Microsoft Graph, but it's the reason "portable" means normalized, not literally identical, behavior.

When native search isn't available

Native search leans on the provider's own search engine, and not every provider offers one the same way. Some IMAP providers don't support the IMAP SEARCH operator at all, and a search_query_native request against one of those returns a 400 error rather than results. The documented fallback is to use the standard query parameters for those providers, which Nylas implements without depending on the provider's native search.

This is the deeper reason to treat standard parameters as the default and native queries as the enhancement. Standard search is the reliable floor that works across providers, including the IMAP servers with no usable SEARCH, while native queries are the opt-in upgrade for the providers that support them well, Gmail and Microsoft chief among them. Building the standard path first means search works for nearly every connected account, and the native path becomes a provider-specific refinement layered on top rather than a hard dependency.

Where mailbox search fits

The same two approaches sit under a range of features, and which you pick follows whether the search has to be portable. A few that map straight on:

A user-facing search box. Map your UI's filters to standard parameters so one implementation searches across your connected providers, Gmail and Outlook users alike.
Power search for one provider. Expose Gmail operators or Graph $filter to power users on those providers via search_query_native, with standard search as the fallback elsewhere.
Finding a specific message in a flow. A support tool or agent locating "the invoice from this sender last month" is a standard-parameter search with from and a date range.
Bulk processing by criteria. Selecting every message matching a query for export or analysis is a paged search, native or standard depending on how precise the criteria need to be.

Each is the same search call with different parameters, the difference being whether you want one portable query or a provider's full power.

Things to keep in mind

A short list of details keeps mailbox search predictable.

in takes a folder ID, not a name. Passing in=inbox returns a 400; look up the folder ID and pass that.
Standard parameters are portable; native queries aren't. Build standard search first so it works across providers, then add native queries where they help.
URL-encode the native query. A Gmail or Graph query string must be URL-encoded before it goes in search_query_native.
Don't mix styles. With a native query, Google and Microsoft allow only in, limit, and page_token alongside; other parameters error.
Native search can be unavailable. Some IMAP providers lack SEARCH and return a 400; fall back to standard parameters there.
Combine standard parameters with AND. Each one narrows the result, so stack from, unread, and a date range for a precise match.

Wrapping up

Searching a mailbox is a choice between portable and provider-specific. Standard query parameters, from, subject, unread, dates, and a folder ID in in, are normalized across providers, so one search works across them, and nylas email search runs them from the terminal. When you need a query the standard set can't express, search_query_native carries the provider's own language, a Gmail operator string or a Microsoft Graph $filter, URL-encoded and provider-specific. Lead with standard search for portability, drop to native queries for power where the provider supports them, and remember the folder-ID rule and the companion-parameter limits.

Where to go next:

Searching with Nylas — standard parameters and search_query_native in depth
List messages — every query parameter for message search
List threads — the same search on threads
Nylas CLI email commands — nylas email search and its filters

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/mailbox-search-api-for-ai-answer-retrieval.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Record and transcribe meetings with Nylas Notetaker

Qasim — Mon, 20 Jul 2026 22:26:51 +0000

Building meeting recording yourself is a project: a bot that joins Zoom or Google Meet, captures the audio and video, runs it through transcription, then summarizes the result and pulls out action items. That's a media pipeline, a transcription service, and a bot framework before you've shipped anything. Nylas Notetaker collapses all of it into an API call. You send a bot to a meeting link, and it joins, records, transcribes, and hands you back the recording, transcript, summary, and action items. This post drives the whole flow with the API and the CLI.

It's a worked use case rather than an endpoint tour, covering Notetaker from two angles: the HTTP API your backend calls and the nylas CLI for sending a bot from the terminal. I work on the CLI, so the commands below are the ones I reach for when I want to record a call right now.

What Notetaker does

A Notetaker is a bot that joins a video meeting on your behalf and captures it. It works with the three meeting providers most teams use, Zoom, Google Meet, and Microsoft Teams, and from a single meeting link it can record video, record audio, generate a transcript, write a summary, and extract a list of action items. You don't run any of that infrastructure; you make a request with the meeting link and collect the results when the bot is done.

The model is refreshingly simple: a bot is a resource you create, track, and then pull media from. You create it pointed at a meeting, it moves through a series of states as it joins and records, and when it finishes you fetch the recording and transcript. Everything else, the joining, the capture, the transcription, the AI summary, happens on the Nylas side, so your integration is three or four API calls rather than a streaming-media stack.

Send a bot to a meeting

You create a Notetaker with a POST /v3/grants/{grant_id}/notetakers request, and the only required field is meeting_link, the invitation URL the bot joins. By default it joins immediately, or you can set join_time to a Unix timestamp to schedule the join for later, and a name field sets the bot's display name in the meeting, defaulting to "Nylas Notetaker."

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://zoom.us/j/123456789",
    "name": "Meeting Recorder"
  }'

One thing to know about scheduling: if you pass a join_time in the past, the request returns an error rather than joining late, so for an immediate join just omit the field instead of sending the current time. The display name matters more than it seems, because it's what other participants see in the attendee list, so name it something that signals what it is rather than leaving the default. The response gives you the Notetaker's ID, which is the handle for everything that follows.

Create a bot from the CLI

The terminal command is nylas notetaker create, and it takes the same inputs as flags. Pass --meeting-link with the URL, optionally --join-time to schedule it, and --bot-name to set the display name. The join time accepts friendly values like tomorrow 9am or 30m, which is easier than computing a Unix timestamp for a quick test.

# Join a Google Meet immediately
nylas notetaker create --meeting-link "https://meet.google.com/abc-defg-hij"

# Schedule a bot to join a Zoom call later, with a custom name
nylas notetaker create --meeting-link "https://zoom.us/j/123" \
  --join-time "2024-01-15 14:00" --bot-name "Standup Recorder"

This is the fastest way to see Notetaker work: drop a real meeting link in, run the command, and watch the bot appear in your call within a few seconds. It's genuinely useful on its own, too, sending a recorder to a call you're about to join without opening a dashboard, but it's also how I sanity-check that a meeting link is valid before wiring the same call into an application.

Configure what the bot captures

The meeting_settings object controls what the bot does in the meeting, and every capability defaults to on. You get booleans for video_recording, audio_recording, transcription, summary, and action_items, so you can turn off what you don't need, an audio-only recording with no AI summary, say. The dependencies stack, though, and they're the thing to get right: transcription requires both video_recording and audio_recording to be true, and summary and action_items in turn require transcription (and therefore the recordings) to be true. In other words the AI features build on the full recording, so you can keep a plain recording and drop the AI layer, but you can't get a transcript without recording the call.

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://zoom.us/j/123456789",
    "meeting_settings": {
      "transcription": true,
      "summary": true,
      "action_items": true,
      "leave_after_silence_seconds": 600
    }
  }'

Two settings are worth calling out. The action_items_settings.custom_instructions field lets you steer the AI with a prompt like "Only return the five most important action items," so the list matches how your team works rather than a generic extraction. And leave_after_silence_seconds, which defaults to 300 and accepts 10 to 3,600, tells the bot to leave once the call goes quiet for that long, which cleanly ends a recording when everyone's talking has stopped but nobody hung up the call.

Track the bot through its states

A Notetaker moves through a defined lifecycle from creation to finished media, and watching where it is tells you when the recording is ready. It starts scheduled or connecting as it joins, may sit in a waiting room before it's admitted, becomes attending once it's in and recording, and after the meeting ends it processes the captured media and then makes it available to fetch. The failure cases exist too, so handle a bot that couldn't get into the meeting or whose media processing errored, along with the cleanup state for media that's been removed.

You track progress one of two ways: poll the Notetaker with a GET on its ID and read its state, or filter the list endpoint with the state query parameter to find, say, every bot currently attending. One wrinkle worth knowing is that the exact state tokens differ slightly between the list filter and the object the GET returns, so don't hardcode a single spelling against both; key off the documented values for whichever call you make. The signal you ultimately wait for is the media being ready, which the next section covers, because that's when the recording and transcript become downloadable. From the CLI, nylas notetaker list --state attending and nylas notetaker show <id> give you the same view.

Get the recording and transcript

You fetch a Notetaker's output from the GET /v3/grants/{grant_id}/notetakers/{notetaker_id}/media endpoint, which returns the recording and transcript as downloadable files, each with a name, a size in bytes, and a URL. The endpoint only returns files once the media is ready: while it's still processing you get a 404, and once it's deleted past the retention window you get a 410. Two separate clocks apply here, and conflating them is a common mistake. Each download URL is a pre-authenticated link valid for 60 minutes from when it's generated; after that it expires, and you call the media endpoint again to mint a fresh one. The files themselves carry expires_at and ttl fields that mark the file's retention period, up to 14 days, after which Nylas permanently deletes the file.

nylas notetaker media <notetaker-id>

Because both the URLs and the files are short-lived, the right pattern is to download as soon as the media is ready and pull the files into your own storage, rather than relying on the 14-day retention. From there, the transcript feeds search or a model, and the recording goes wherever you keep meeting archives. If you need to end a live recording before the meeting naturally wraps, nylas notetaker leave <id> instructs the bot to leave, which stops the recording and triggers media generation while keeping the Notetaker record, distinct from nylas notetaker delete, which cancels a scheduled or active bot and removes it.

Standalone bots, no grant required

Here's the feature that makes Notetaker unusually flexible: it has a standalone mode. The grant-scoped endpoints above attach a bot to a connected account, but the /v3/notetakers endpoints let you send a bot to a meeting without any grant at all. That means a user who has never authenticated with your application, never connected a calendar or mailbox, can still have a Notetaker join their meeting.

This matters for products where meeting capture is the whole feature and account connection would be friction. A "paste a meeting link, get a transcript" tool doesn't need the user's Google account; it needs a bot in the meeting, and standalone Notetakers give you exactly that. The standalone endpoints mirror the grant-scoped ones, create, list, get, media, leave, and cancel, so the flow is identical apart from dropping the grant from the path. You choose per use case: grant-scoped when the bot belongs to a connected user, standalone when anyone should be able to record a call.

Where Notetaker fits

The same create-track-fetch flow sits under a range of meeting features, and the difference is mostly what you do with the transcript. A few that map straight on:

Automated meeting notes. Send a bot to every meeting on a calendar and store the summary and action items, so notes write themselves.
A paste-a-link transcription tool. A standalone bot turns any meeting URL into a transcript with no account connection, the whole product in one endpoint.
Sales call analysis. Capture the transcript of each call and feed it to a model for coaching, objection tracking, or CRM notes.
Searchable meeting archive. Store transcripts in your own index so a team can search what was said across every recorded call.

Each is the same handful of calls, create the bot, wait for the media to be ready, fetch it, with the value living in what you do with the output.

Things to keep in mind

A short list of details keeps Notetaker predictable.

Only meeting_link is required. Omit join_time to join immediately; a past join_time returns an error.
AI features need the recording. summary and action_items require video_recording, audio_recording, and transcription all set to true.
Wait until the media is ready. The media endpoint returns a 404 while still processing and the files once they're ready; poll the Notetaker or filter the list by state to know when.
Two media clocks. Download URLs expire after 60 minutes (re-call the media endpoint to regenerate), while expires_at/ttl mark the file's retention of up to 14 days; download promptly rather than storing a stale link.
leave and delete differ. leave ends a live recording and keeps the media; delete cancels the bot and removes it.
Standalone needs no grant. Use /v3/notetakers when the user hasn't connected an account and you just need a bot in the meeting.

Wrapping up

Notetaker turns meeting capture into a few API calls. Create a bot with a meeting_link (and optional join_time, name, and meeting_settings), or run nylas notetaker create, and it joins your Zoom, Google Meet, or Teams call to record and transcribe. Track it until its media is ready, then fetch the recording and transcript from the media endpoint, mindful that the download URLs expire after 60 minutes and the files after a 14-day retention window. Tune what it captures with meeting_settings, including a custom prompt for action items, and reach for standalone bots when there's no connected account to attach to. The infrastructure, joining, recording, transcription, and AI summary, is handled, so what's left is deciding what to do with the output.

Where to go next:

Notetaker — the full guide to bots, settings, and media
Notetaker API reference — create, list, media, leave, and cancel endpoints
Standalone Notetaker — the no-grant endpoints
Nylas CLI notetaker commands — nylas notetaker create, list, and media

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/notetaker-api-for-zoom-google-meet-teams.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Send and download email attachments with Nylas

Qasim — Mon, 20 Jul 2026 22:26:38 +0000

Attaching a file to an email you send through an API is one of those tasks that looks trivial until you hit the first limit. Base64-encode a PDF into a JSON request and a 4MB file fails, because the cap is on the whole request, not the file. Inline a logo and it shows up as a separate attachment instead of in the body, because you didn't wire up the content ID. And pulling an attachment back out of a received message needs the message context, not just the attachment ID. This post covers sending attachments with the Email API and downloading them with the CLI, with the limits that actually bite.

It's a worked use case rather than an endpoint tour, covering attachments from two angles: the HTTP API your backend calls to send and the nylas CLI for inspecting and downloading what you receive. I work on the CLI, so the commands below are the ones I reach for when I need a file out of a message.

Two ways to attach a file when sending

There are two schemas for putting a file on an outbound message, and they're split by size. The JSON schema base64-encodes the file into an attachments array on a normal POST /messages/send request, which is the simple path. The multipart/form schema breaks the request into parts, each with its own MIME type, and carries the file as binary rather than base64. You pick based on how big the file is.

The size limits are the deciding factor and the first thing to get straight. The JSON method is capped at a 3MB total request payload, and the multipart method raises that to 25MB including the body content. So a small PDF or image goes in JSON without a second thought, and anything heading toward a few megabytes belongs in multipart. Beyond 25MB there's a separate flow covered later, but for everyday attachments the choice is JSON for small, multipart for large.

The 3MB limit is on the whole request

The single most common attachment bug is a file that's comfortably under 3MB failing to send anyway, and it comes down to what the limit measures. The 3MB cap on the JSON method is the entire HTTP request, not just the attachment content, so your message body, headers, recipient list, and every other attachment all count toward it. A 2.9MB file plus a long HTML body can push the request over the line.

Base64 makes this tighter than it looks. Encoding a binary file as base64 inflates it by roughly a third, so a 2.2MB file becomes about 3MB of encoded text before you've added anything else. The practical rule is to treat the JSON method as comfortable up to around 2MB of actual file content and switch to multipart well before the raw file approaches 3MB. If you're seeing sends rejected for size on files that seem small enough, the base64 inflation is almost always why.

Send a file with the JSON method

For a small file, you add an attachments array to the send request, where each entry carries the base64 content, a content_type, and a filename. The rest of the message, to, subject, body, is exactly as you'd send without an attachment, so adding a file is one more field rather than a different request shape.

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 '{
    "to": [{ "email": "client@example.com" }],
    "subject": "Your invoice",
    "body": "<p>Invoice attached.</p>",
    "attachments": [{
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "content": "<BASE64_ENCODED_FILE>"
    }]
  }'

The content field is the file read and base64-encoded, which your language's standard library does in a line. Each attachment is its own object in the array, so a message can carry several, as long as the whole request stays under 3MB. For anything larger, the same attachments data moves into a multipart request instead, where the file rides as binary and the ceiling jumps to 25MB.

Embed an inline image with content_id

An inline image, a logo in a signature or a chart in the body, isn't a separate attachment at the bottom of the message; it's rendered in the HTML where you place it. The mechanism is content_id. You give the attachment a content_id, then reference it in the body's HTML with a cid: URL, and the image renders at that spot instead of hanging off the message as a downloadable file.

# In the attachment object:  "content_id": "logo123"
# In the body HTML:          <img src="cid:logo123">

The link is the matching identifier: the cid:logo123 in the <img> tag points at the attachment whose content_id is logo123. Get that pairing right and the image appears in the message body; get it wrong, or omit the content_id, and the same file shows up as a separate attachment instead. This is exactly how a branded signature with a logo works, and it's the piece people miss when an inline image stubbornly attaches itself to the bottom of the email.

Files over 25MB: the large attachments flow

When a file is too big even for multipart, there's a separate path, with a provider caveat. For Microsoft grants, Nylas supports attachments up to 150MB through a beta large attachments flow: you upload the file once, then reference its returned ID in your send request rather than inlining the bytes. It decouples the upload from the send, so a big file doesn't have to fit inside a single message request.

The constraint to know is that this flow is Microsoft-only. If you're sending from a Microsoft (Outlook or Exchange Online) grant and your file is between 25MB and 150MB, this is the path; for other providers, 25MB via multipart is the ceiling. There's also a provider-storage wrinkle worth knowing: Google and Microsoft both have cloud-drive services, and a file shared from Google Drive or OneDrive usually appears as a link in the message body rather than as an attachment on the message object, so a "missing" attachment is sometimes a drive link instead.

Download an attachment from a received message

Pulling an attachment out of a message you received uses GET /v3/grants/{grant_id}/attachments/{attachment_id}/download, and the detail that trips people up is that message_id is a required query parameter. An attachment isn't a free-floating object; it belongs to the message it arrived on, so you pass both the attachment's ID and the message's ID to fetch it. The same message_id requirement applies to the metadata endpoint that returns an attachment's content_type, size, and filename.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachments/<ATTACHMENT_ID>/download?message_id=<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --output invoice.pdf

The reason for the message scope is that the same physical file can appear on more than one message, and the attachment ID alone doesn't pin down which one you mean. So you carry the message_id from when you listed the message's attachments through to the download call. Forget it and the request fails for a missing required parameter, which is the single most common attachment-download error.

Inspect and download attachments from the CLI

The CLI handles the receive side, and it's the fast way to get a file out of a message without writing a request. nylas email attachments list <message-id> shows every attachment on a message with its ID, and nylas email attachments download <attachment-id> <message-id> pulls one down, saving it under its original filename or to a path you set with --output. There's also nylas email attachments show <attachment-id> <message-id> for the metadata.

# List attachments on a message, then download one
nylas email attachments list <message-id>
nylas email attachments download <attachment-id> <message-id> --output ./invoice.pdf

Notice the CLI mirrors the API's message scoping: download and show take both the attachment ID and the message ID, while list takes just the message ID, for the same reason the download endpoint requires message_id. One thing the CLI deliberately doesn't do is send attachments, there's no attachment flag on nylas email send, because attaching files is a structured-payload job that belongs in the API's JSON or multipart request. So the split is clean: send attachments with the API, and list, inspect, and download received ones from the terminal.

Where attachments work fits

The same send-and-receive handling sits under a range of features, and the size limits shape which path each takes. A few that map straight on:

Sending generated documents. Invoices, receipts, and reports rendered to PDF go out on the JSON method while they're small, moving to multipart as they grow.
Branded email with inline images. A logo or header image embedded via content_id and a cid: reference renders in the body, not as a clutter attachment.
Processing inbound files. A workflow that receives documents downloads each attachment with its message_id and feeds it to parsing, storage, or a model.
Large file delivery on Microsoft. Contracts or media up to 150MB go through the large attachments flow on Microsoft grants rather than failing the 25MB multipart ceiling.

Each is the same handful of primitives, an attachments array or multipart part to send, the download endpoint to receive, with the file size choosing the path.

Things to keep in mind

A short list of details keeps attachments predictable.

The 3MB JSON limit is the whole request. Body, headers, and every attachment count, and base64 inflates a file by about a third, so switch to multipart well before the raw file nears 3MB.
Multipart raises the ceiling to 25MB. Use it for anything beyond a small file; it carries the file as binary instead of base64.
Inline images need content_id plus cid:. Match the body's cid: reference to the attachment's content_id, or the image attaches instead of embedding.
Downloads require message_id. An attachment is scoped to its message; pass both IDs to the download and metadata endpoints.
Over 25MB is Microsoft-only. The large attachments flow reaches 150MB on Microsoft grants; other providers cap at 25MB.
The CLI receives, not sends. nylas email attachments lists and downloads; nylas email send has no attachment flag, so sending files is the API's job.

Wrapping up

Attachments come down to size and scope. To send, base64 a small file into the attachments array under the 3MB whole-request limit, or move to multipart for up to 25MB, and embed inline images by matching a content_id to a cid: reference in the body. To receive, download from GET /v3/grants/{grant_id}/attachments/{attachment_id}/download with the required message_id, or run nylas email attachments download from the terminal. Remember that base64 inflation makes the 3MB limit tighter than it reads, that inline images live or die by the content ID, and that files past 25MB need the Microsoft-only large attachments flow.

Where to go next:

Working with attachments — JSON and multipart schemas in depth
Send large attachments — the Microsoft 150MB flow
Send a message — the attachments field and send options
Nylas CLI email commands — nylas email attachments list, show, and download

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/send-email-with-attachments-api-agent.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Build a support triage agent that owns its own inbox

Qasim — Sun, 19 Jul 2026 01:08:05 +0000

Most "AI support bot" demos bolt an LLM onto a shared Gmail or hang a webhook off a helpdesk and call it a day. That works right up until you want the agent to actually be a participant in the conversation — to receive mail at a real address, decide what to do with it, and reply as itself instead of as a script poking at someone else's mailbox.

So let's not do that. Let's give support@yourcompany.com its own first-class identity: an Agent Account that receives every inbound email, classifies it with a model, routes and filters it with server-side rules, and replies in the right thread — once, never twice. No shared inbox, no scraping a human's account, no helpdesk middleman.

I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for when I'm setting one of these up. Every step gets the two-angle tour: the raw curl call and the nylas command that does the same thing.

What you actually get

An Agent Account is, underneath, just a Nylas grant with a grant_id. That's the whole trick, and it's worth sitting with for a second: there's nothing new to learn on the data plane. Every grant-scoped endpoint you already know — Messages, Drafts, Threads, Folders, Attachments, Contacts, Calendars, Events — works against this grant exactly the way it works against a Gmail or Microsoft grant you obtained through OAuth. The provider happens to be nylas instead of google, and that's the only difference your application code sees.

Concretely, the account ships with:

A real, send-and-receive mailbox on a domain you control (or a *.nylas.email trial subdomain).
Six reserved system folders out of the box — inbox, sent, drafts, trash, junk, and archive.
Standard webhook triggers: you subscribe once at the application level (POST /v3/webhooks), and message.created then fires on inbound mail. A subscription isn't scoped to one grant — each event's payload carries a grant_id, so you filter for your Agent Account's events on the way in. Agent Accounts also emit deliverability triggers: message.delivered, message.bounced, message.complaint, and message.rejected.
No OAuth dance and no refresh token to babysit. You create it with one API call.

The part I like as an SRE: because it's a normal grant, it slots into whatever observability, retry, and webhook plumbing you already built for human accounts. You're not maintaining a special-case code path.

Before you begin

Two things:

An API key. All requests authenticate with Authorization: Bearer <NYLAS_API_KEY>, and the key identifies your application. Examples here hit https://api.us.nylas.com.
A verified domain. Agent Accounts live on a domain — either a custom one you register and publish DNS records for, or a Nylas trial subdomain like yourapp.nylas.email. New domains warm up over roughly four weeks, so if you're going to production, register the real one early. The full DNS walkthrough is in the provisioning docs.

If you've run nylas init already, the CLI is pointed at your application and you're ready.

Provision support@

You create the account with a single POST /v3/connect/custom using "provider": "nylas" and the email address in settings.email. The optional top-level name becomes the default From display name on everything the account sends.

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": "Acme Support",
    "settings": {
      "email": "support@yourcompany.com"
    }
  }'

The response hands you back data.id. Save it — that's the grant_id you'll use on every subsequent call.

From the CLI it's one line:

nylas agent account create support@yourcompany.com --name "Acme Support"

That provisions the grant and prints its id, status, and connector details. If the underlying nylas connector doesn't exist on your application yet, the CLI creates it first — you don't have to think about it. The API also auto-creates a default workspace and a default policy for the account, which matters in a minute when we get to filtering.

One honest gotcha worth flagging now: there is no --workspace flag on agent account create. Workspaces (which carry your policies and rules) get attached separately. We'll do that below.

If you want a human to be able to peek at the inbox over IMAP later, pass --app-password at creation time (18–40 ASCII chars, mixed case and a digit). Skip it and protocol access stays off, which for a fully automated agent is usually what you want.

Receive every inbound message

The whole agent runs off one webhook. Inbound mail to support@ fires the standard message.created notification — the same shape you'd get for any other grant.

curl --request POST \
  --url "https://api.us.nylas.com/v3/webhooks" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "trigger_types": ["message.created"],
    "webhook_url": "https://support-agent.yourcompany.com/webhooks/nylas",
    "description": "Support triage agent"
  }'

Same thing from the terminal:

nylas webhook create \
  --url https://support-agent.yourcompany.com/webhooks/nylas \
  --triggers message.created \
  --description "Support triage agent"

A message.created payload looks roughly like this — note that it carries summary fields, not the full body:

{
  "type": "message.created",
  "data": {
    "object": {
      "id": "msg-abc123",
      "grant_id": "b1c2d3e4-5678-4abc-9def-0123456789ab",
      "thread_id": "thread-xyz789",
      "subject": "Can't log in after password reset",
      "from": [{ "name": "Dana Reed", "email": "dana@customer.example" }],
      "snippet": "I reset my password an hour ago and now...",
      "date": 1742932766
    }
  }
}

Your handler should return 200 immediately, verify the X-Nylas-Signature header, and then do its work asynchronously. The first thing it does is skip messages the agent itself sent — because message.created fires for outbound mail too, and an agent that replies to its own replies is a special kind of broken:

app.post("/webhooks/nylas", async (req, res) => {
  res.status(200).end();

  const event = req.body;
  if (event.type !== "message.created") return;

  const msg = event.data.object;
  if (msg.grant_id !== SUPPORT_GRANT_ID) return;
  if (msg.from?.[0]?.email === "support@yourcompany.com") return; // skip our own sends

  await triage(msg);
});

Because the webhook only carries the snippet, you'll fetch the full message before you hand anything to the model:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/msg-abc123" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

nylas email read msg-abc123

There's a hard edge here: if the body is larger than ~1 MB, the webhook type becomes message.created.truncated and the body is omitted — so don't rely on the payload ever carrying the full text.

Classify it with an LLM

Triage is a classification problem, and classification is exactly what models are good at. Pull the full message, then feed the model the three fields that actually decide intent: subject, sender, and body. Ask for a category back.

This part is deliberately provider-agnostic — any chat-completions-style API works, and the prompt is the whole design:

async function triage(msg) {
  const full = await getFullMessage(msg.grant_id, msg.id); // GET .../messages/{id}

  const category = await llm.classify({
    instruction:
      "Classify this support email into exactly one of: " +
      "billing, bug_report, how_to, account_access, feedback, spam. " +
      "Reply with only the category.",
    subject: full.subject,
    from: full.from[0].email,
    body: full.body,
  });

  await route(full, category); // -> assign folder, draft reply, or escalate
}

Keep the label set small and closed. A model asked to pick from six categories is reliable; a model asked to "summarize the customer's needs" is a liability you'll be debugging at 2 a.m. The category is what drives everything downstream — which folder it lands in, whether the agent auto-replies, and whether a human gets pulled in.

Route and filter with policies, rules, and lists

Here's the move a lot of "AI inbox" builds miss: not every message should reach your application at all. Nylas Agent Accounts give you three server-side primitives that filter and sort mail before your webhook ever fires, so the LLM only spends tokens on things worth classifying.

Policies bundle limits (send quotas, storage, retention) and spam detection. One policy can govern 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 — so non-engineers can update an allowlist or blocklist without a deploy.

They form a chain: lists hold values, rules reference lists and describe conditions plus actions, policies bundle limits, and a workspace carries one policy_id and an array of rule_ids. Every Agent Account in the workspace inherits both. You don't attach anything to an individual grant.

Start by blocking a known-bad sender at the SMTP layer, so it never hits the mailbox:

curl --request POST \
  --url "https://api.us.nylas.com/v3/rules" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Block spam-domain.com",
    "priority": 1,
    "trigger": "inbound",
    "match": {
      "conditions": [
        { "field": "from.domain", "operator": "is", "value": "spam-domain.com" }
      ]
    },
    "actions": [{ "type": "block" }]
  }'

The CLI builds the same rule and attaches it to the default workspace in one shot:

nylas agent rule create \
  --name "Block spam-domain.com" \
  --trigger inbound \
  --priority 1 \
  --condition from.domain,is,spam-domain.com \
  --action block

For the allowlist/blocklist pattern, create a list and reference it from a rule. API first:

curl --request POST \
  --url "https://api.us.nylas.com/v3/lists" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Blocked domains", "type": "domain" }'

That call returns the list id. Seed it with items in a second call — list items are their own sub-resource:

curl --request POST \
  --url "https://api.us.nylas.com/v3/lists/<LIST_ID>/items" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "items": ["spam.com"] }'

Then the rule that matches against it with in_list:

curl --request POST \
  --url "https://api.us.nylas.com/v3/rules" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Block anything on our blocklist",
    "trigger": "inbound",
    "match": {
      "conditions": [
        { "field": "from.domain", "operator": "in_list", "value": ["<LIST_ID>"] }
      ]
    },
    "actions": [{ "type": "block" }]
  }'

The CLI collapses the list creation and seeding into one command, and the rule reference into another:

nylas agent list create --name "Blocked domains" --type domain --item spam.com
nylas agent rule create \
  --name "Block anything on our blocklist" \
  --trigger inbound \
  --condition from.domain,in_list,<LIST_ID> \
  --action block

Routing is the same shape with a different action. Push automated notifications into their own folder so the agent doesn't waste a classification on them — assign_to_folder paired with mark_as_read. The curl form:

curl --request POST \
  --url "https://api.us.nylas.com/v3/rules" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Route notifications to a folder",
    "trigger": "inbound",
    "match": {
      "conditions": [
        { "field": "from.domain", "operator": "is", "value": "noreply.example.com" }
      ]
    },
    "actions": [
      { "type": "assign_to_folder", "value": "<FOLDER_ID>" },
      { "type": "mark_as_read" }
    ]
  }'

And the CLI equivalent, which creates the rule and attaches it to the default workspace:

nylas agent rule create \
  --name "Route notifications to a folder" \
  --trigger inbound \
  --condition from.domain,is,noreply.example.com \
  --action assign_to_folder=<FOLDER_ID> \
  --action mark_as_read

If you created a custom policy and want it on your accounts, attach it to the workspace — that's where the no---workspace-flag detail from earlier resolves. Create the policy, then PATCH the workspace to point at it. The curl form:

# Create the policy
curl --request POST \
  --url "https://api.us.nylas.com/v3/policies" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Support Agent Policy" }'

# Attach it to the workspace (returns the policy id from the call above)
curl --request PATCH \
  --url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "policy_id": "<POLICY_ID>" }'

The CLI collapses both steps:

nylas agent policy create --name "Support Agent Policy"
nylas workspace update <workspace-id> --policy-id <policy-id>

One thing to internalize: inbound and outbound rules are isolated. An inbound rule never runs on a send, and an outbound rule never runs on receipt. So if you also want to, say, star every reply the agent sends, that's an outbound rule matching outbound.type equal to reply — it won't interfere with your inbound triage at all.

Reply in the correct thread

When the agent decides to respond, threading is non-negotiable. The reply has to land inside the customer's existing conversation, not as a fresh disconnected email. Nylas handles this through reply_to_message_id: pass it on the send and Nylas sets the In-Reply-To and References headers for you, so the customer's mail client groups the reply correctly.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "reply_to_message_id": "msg-abc123",
    "to": [{ "email": "dana@customer.example" }],
    "subject": "Re: Can'\''t log in after password reset",
    "body": "Hi Dana — I see the reset went through an hour ago..."
  }'

From the CLI, nylas email reply does the bookkeeping for you. Point it at the message ID and it fetches the original to populate the recipient and subject, then preserves threading via reply_to_message_id automatically:

nylas email reply msg-abc123 --body "Hi Dana — I see the reset went through an hour ago..."

By default the reply goes only to the original sender; add --all if you need to keep the rest of the To/Cc on the thread. This is the command I lean on most when I'm testing an agent by hand — it's the shortest path from "a message landed" to "a threaded reply went out."

Don't reply twice

This is where naive builds fall over in production. Webhooks are delivered at least once — if your endpoint is slow to 200 or there's a network blip, you'll get the same message.created again. Add concurrent workers and two of them can grab the same notification at the same millisecond. Either way: two replies, one angry customer.

The fix is idempotency, and it lives entirely in your own store — not in Nylas. Custom metadata tagging on Agent Account resources isn't supported yet, so you can't stash dedup state on the message or grant; keep it in Redis or Postgres. Track the message IDs you've already processed and refuse to handle one twice, using an atomic check-and-set:

const messageId = event.data.object.id;

// Atomic insert. Returns truthy ONLY when the key was newly inserted:
//   Redis    -> SET messageId 1 NX EX 86400   (truthy if it didn't exist)
//   Postgres -> INSERT ... ON CONFLICT DO NOTHING, then check rowCount === 1
const wasInserted = await db.processedMessages.setIfAbsent(messageId, {
  receivedAt: Date.now(),
});

if (!wasInserted) return; // insert did nothing -> already seen, bail

Watch the polarity here — it's the easiest bug to ship. setIfAbsent succeeds (returns truthy) only the first time it sees a message ID; every redelivery finds the key already present and returns falsy. So you proceed when wasInserted is true and exit when it's false. Invert that test and you'd drop every genuine first message while happily processing the duplicates.

Give the dedup record a TTL of about 24 hours — long enough that a webhook redelivered hours later still gets caught, short enough that the table doesn't grow forever. For the concurrent-worker race, layer a per-thread lock on top, and inside it double-check the thread's latest message: if the most recent message is already from the agent, a prior worker beat you to it and you skip.

Dedup catches redelivered events; locking catches simultaneous ones. You want both. The full pattern, including an outbound rate limit as a backstop against reply storms, is in the prevent-duplicate-replies recipe.

Carry context across the thread

A support thread is rarely one message. The customer replies, you reply, they clarify — and the agent needs the whole exchange to answer the third message sensibly. Because every message in a conversation shares a thread_id, fetching context is one call.

nylas email threads show thread-xyz789

Or the same call over the API:

curl "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads/<THREAD_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

GET /v3/grants/{grant_id}/threads/{thread_id} returns the thread with its message_ids; fetch those for the full transcript, sort by date, and hand the model the running conversation rather than the latest message in isolation. For long threads, summarize the early messages and pass only the last few in full — same answer quality, far fewer tokens. The multi-turn conversations recipe builds the full state machine around this if you need conversations that span days.

Guardrails before you ship

A support agent that emails customers autonomously needs brakes:

Human-in-the-loop for sensitive categories. Route billing and account_access to a draft-and-escalate path instead of auto-sending. The agent prepares the reply; a person approves it.
Cap the conversation. Track a turn count per thread and escalate to a human when it crosses a limit. An unbounded loop is a token sink and a reputation risk.
Outbound rate limit. Even with dedup and locking, a logic bug can cascade. A per-thread send cap (escalate instead of sending after N replies in a few minutes) is the backstop you'll be glad you wrote.
Mind retention and limits. On the free plan, accounts cap at 200 messages/day with a 30-day inbox / 7-day spam retention window. If support volume is higher than that, size your plan and policy accordingly before launch.

What's next

You've now got support@ as a real participant: it receives every email, filters the noise server-side, classifies what's left, replies in-thread, and never doubles up. Where to go from here:

Handle email replies in an agent loop — the reply-detection recipe this builds on.
Policies, Rules, and Lists — every condition, operator, and action for inbound and outbound filtering.
Provisioning Agent Accounts — domains, display names, IMAP access, and multi-tenant patterns.
The CLI command reference lives at cli.nylas.com/docs/commands if you want the full set of nylas agent subcommands.

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/inbound-email-triage-api-for-support-agents.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Add custom metadata to Nylas objects for filtering

Qasim — Sun, 19 Jul 2026 01:07:56 +0000

You're sending a message from your app, and you need to remember which campaign it belonged to, or tie a calendar event back to the order in your own database. The obvious approach is a separate table mapping Nylas IDs to your records, which means a join on every read and a sync to keep current. There's a lighter way: attach your own data directly to the object as metadata, then filter objects by it later. Your campaign ID rides along on the message, and a single query pulls back every message in that campaign. This post covers tagging objects with the API and the CLI.

It's a worked use case rather than an endpoint tour, covering metadata from two angles: the HTTP API your backend calls and the nylas CLI for setting and reading it from the terminal. I work on the CLI, so the commands below are the ones I reach for when I want to tag a send and find it again.

What metadata is and where it lives

Metadata is a field of your own key-value pairs that you attach to a Nylas object, and it's supported on messages, drafts, events, and calendars. The values are strings, you can store up to 50 pairs on a single object, and each value can hold up to 500 characters. That's room for a campaign slug, an external record ID, a workflow status, and whatever else ties the object back to your application, all carried on the object itself rather than in a side table.

The point of metadata is to avoid that side table. Instead of mapping a Nylas message ID to a row in your database and joining on every read, you put your application's data on the message and read it straight back. The object becomes self-describing from your app's point of view, so the campaign a message belongs to or the order an event is for travels with the object through every API call that returns it. For application data that's small and that you want to filter by, this is simpler than maintaining a parallel store.

The five-key rule that decides your schema

This is the single most important thing to understand about metadata, and missing it leads to a tagging scheme that can't be queried. You can store up to 50 key-value pairs, but only five keys, literally named key1 through key5, are indexed and filterable. Any other key you set is stored and returned with the object, but you cannot filter on it. So the keys you plan to query by have to live in key1 through key5.

This shapes how you design your tags. The values you'll search for, the campaign ID, the workflow status, the tenant, go in the five indexed keys, and you decide that mapping up front: key1 is the campaign, key2 is the run, and so on. Everything else, data you want to carry but never filter by, can use descriptive key names and ride along as the other 45 pairs. Get this backwards, putting a filterable concept in a free-form key, and you'll have stored the data but built no way to query it, which usually surfaces later when the filter you need silently returns nothing.

Set metadata when you send

You attach metadata at creation time by adding a metadata object to the request. On a POST /messages/send, the metadata object carries your key-value pairs alongside the rest of the message, and they're stored on the resulting message for later retrieval and filtering.

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 '{
    "to": [{ "email": "lead@example.com" }],
    "subject": "Your trial is ending",
    "body": "<p>A quick nudge.</p>",
    "metadata": { "key1": "q2-trial-nudge", "key2": "run-1183" }
  }'

Here key1 holds the campaign and key2 the run, both indexed so you can filter on either later. The CLI sets the same metadata with a repeatable --metadata flag on nylas email send, written as key=value, so nylas email send --to lead@example.com --metadata key1=q2-trial-nudge --metadata key2=run-1183 tags the message from the terminal. Tag every send in a campaign, not just some, because an untagged message is invisible to the filter that counts the campaign later.

Filter objects by metadata

Reading tagged objects back uses the metadata_pair query parameter, written as metadata_pair=key1:value, which returns only objects whose metadata matches that key and value. On the messages endpoint, GET /v3/grants/{grant_id}/messages?metadata_pair=key1:q2-trial-nudge returns exactly the messages tagged for that campaign, no scan of every message required.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?metadata_pair=key1:q2-trial-nudge" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

The same metadata_pair filter works on the drafts, events, and calendars list endpoints, so the pattern is identical whether you're pulling a campaign's messages or a project's events. From the CLI, nylas email list --metadata key1:q2-trial-nudge does the same filter, and its help is explicit that only key1 through key5 work here, which is the rule from earlier showing up at query time. This is the payoff of tagging: one filtered request replaces fetching everything and matching in your own code.

Update tags after creation, through the API

Setting metadata at creation doesn't lock you in. The message update endpoint, PUT /v3/grants/{grant_id}/messages/{message_id}, accepts a metadata object alongside unread, starred, and folders, so you can change a message's tags after it's sent, through the same partial-PUT call that marks it read or moves it to a folder. Include only the fields you want to change and the rest stay as they were, so re-tagging a sent message is a one-field update rather than a resend.

Events update the same way. Because you change an event with a PUT, its metadata goes along, so you can flip a key1 workflow status from pending to confirmed as the event progresses, which makes metadata useful for tracking state over time rather than just a fixed label. The one place this differs is the CLI: nylas email send --metadata sets tags at send time and the nylas email metadata commands read them back, but the terminal doesn't expose a metadata-update flow, so to change a message's tags after sending you go through the API's message PUT. From the CLI, plan the tags before sending; from code, evolve them whenever you need.

Provider and reserved-key caveats

Two specifics are worth knowing before you lean on metadata heavily. First, metadata_pair filtering isn't universal across providers: on CalDAV-backed calendars, which is how iCloud connects, the filter isn't supported for events, so a query that works against Google and Microsoft events won't behave the same there. If you support iCloud calendars, don't build a feature that depends on filtering their events by metadata, and fall back to listing and matching in your own code for those.

Second, key5 carries a special meaning in one place. Nylas uses key5 to identify the events that count toward the max-fairness round-robin calculation in group availability, so if you run round-robin scheduling, key5 is effectively spoken for on those events, where it holds the group identifier. It's still an ordinary indexed key everywhere else, on messages and on non-group events, but on group-availability events, leave key5 for the value scheduling expects rather than overloading it with your own tag.

Inspect what's tagged from the CLI

When you want to see what metadata is actually on an object, the CLI reads it back. nylas email metadata show <message-id> prints every metadata pair on a message, both the indexed key1 through key5 and any custom-named keys you added, so you can confirm a tag landed the way you intended. There's also nylas email metadata info for a quick reference on how the keys and filtering work.

# See every metadata pair on a message
nylas email metadata show <message-id>

This is the fast way to debug a tagging scheme: send a tagged message, run metadata show, and check that the campaign landed in key1 rather than a free-form key that won't filter. It's saved me more than once from the silent-empty-filter problem, where a tag was stored under the wrong key name and the metadata_pair query came back empty because the value wasn't in one of the indexed five.

Where metadata earns its place

The same tag-and-filter pattern sits under a range of features, and the value is always avoiding a side table. A few that map straight on:

Campaign attribution. Tag every send with a campaign ID in key1, then filter with metadata_pair to pull a campaign's messages for reply-rate or open-rate analysis.
Multi-tenant scoping. Stamp each object with a tenant ID so one connected account can serve many tenants and you filter each tenant's data cleanly.
Workflow status on events. Track an event through states by updating a key1 status, filtering for everything pending or confirmed without a separate status store.
Linking to your own records. Carry your database's primary key for the related record on the object, so a webhook or list result points straight back to your row with no lookup table.

Each replaces a join or a parallel store with a tag that travels on the object and a one-line filter that reads it back.

Things to keep in mind

A short list of details keeps metadata predictable.

Only key1 through key5 filter. You can store 50 pairs, but anything you'll query by must live in one of the five indexed keys; other keys are stored but not filterable.
Fifty pairs, 500 characters each. Values are strings capped at 500 characters, so store IDs and slugs, not document bodies.
Tags update through PUT. Both message metadata (via PUT /v3/grants/{id}/messages/{id}) and event metadata (via the event PUT) can change after creation; the partial PUT touches only the fields you send.
The CLI sets at send, doesn't update. nylas email send --metadata tags at send time with no terminal update flow, so compute the full tag set before sending when you work from the CLI, or use the API PUT to evolve them.
Filter with metadata_pair=key:value. The same parameter works on messages, drafts, events, and calendars.
Tag everything in a cohort. An untagged object is invisible to the filter, so tag every send or event in a group, not just some.

Wrapping up

Metadata lets you carry your own application data on a Nylas object and filter by it, instead of maintaining a side table and joining on every read. Attach up to 50 key-value pairs with a metadata object at send or create time, put anything you'll query by in the indexed key1 through key5, and read it back with metadata_pair=key1:value on the messages, drafts, events, or calendars endpoint. From the terminal, nylas email send --metadata tags and nylas email metadata show inspects. Remember that both message and event tags can be updated through their PUT endpoints, even though the CLI only sets them at send, and that only the five indexed keys are filterable, the rest are along for the ride.

Where to go next:

Metadata reference — the metadata field and metadata_pair filter
Send a message — the metadata field on a send
Track agent reply rates — metadata-tagged campaign attribution end to end
Nylas CLI email commands — nylas email metadata show and info

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/email-metadata-tagging-for-agent-actions.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Create and secure webhooks with the Nylas API

Qasim — Sun, 19 Jul 2026 01:07:44 +0000

A webhook is how your app finds out about new email or calendar changes without asking. Instead of polling for "anything new yet?", you register a URL and Nylas pushes events to it as they happen. But setting one up correctly is more than posting a URL: your endpoint has to answer a challenge before the webhook activates, you get a signing secret exactly once, and you should verify a signature on every delivery so you don't process spoofed events. Get those three wrong and the webhook never turns on or your handler trusts forged data. This post sets up a webhook properly with the API and the CLI.

It's a worked use case rather than an endpoint tour, covering webhooks from two angles: the HTTP API your backend calls and the nylas CLI for creating, testing, and receiving them. I work on the CLI, so the commands below are the ones I reach for when wiring up notifications.

Create a webhook

You register a webhook with a POST /v3/webhooks request, and the two required fields are webhook_url, where Nylas sends notifications, and trigger_types, the array of events you want delivered. An optional description labels it and notification_email_addresses gets alerts about the webhook's health, like when it's failing.

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.com/webhooks/nylas",
    "trigger_types": ["message.created", "event.created"],
    "description": "Production message and event hook"
  }'

Webhook management needs your API key, not a grant, because a webhook belongs to the application rather than one connected account. The trigger_types array is where you choose exactly which events to receive, from message.created to event.updated to grant.expired, so a single webhook can carry several event types or you can split them across webhooks by concern. Choose only the triggers you'll act on, since every subscribed event is a request to your endpoint.

Create and explore from the CLI

The CLI creates the same webhook with nylas webhook create, taking --url and --triggers as the required inputs, plus --description and --notify for the optional fields. Before you create one, nylas webhook triggers lists every available trigger type, which saves guessing at the exact event names.

# See the available triggers, then create a webhook
nylas webhook triggers
nylas webhook create --url https://yourapp.com/webhooks/nylas \
  --triggers message.created,event.created \
  --notify ops@example.com

Webhook management is admin-level, so the CLI uses your API key for these commands, matching the API. From there, nylas webhook list shows your application's webhooks, nylas webhook show <id> prints one, nylas webhook update <id> changes its triggers or URL, and nylas webhook delete <id> removes it. The full lifecycle is on the command line, which makes the CLI handy for managing webhooks across environments without writing a single request.

Answer the challenge before it activates

Here's the step that trips up almost everyone the first time: before a webhook goes live, Nylas verifies your endpoint with a challenge. When you create a webhook or set one to active, it sends a GET request to your URL with a challenge query parameter, and your endpoint has to echo that exact value back in the body of a 200 OK. Until it does, the webhook doesn't activate.

app.get("/webhooks/nylas", (req, res) => {
  res.status(200).send(req.query.challenge); // echo the exact value
});

Two details make or break this. Your endpoint must respond within 10 seconds, and it must return the exact challenge value and nothing else, no JSON wrapper, no quotation marks, just the raw string. A handler that returns {"challenge": "..."} fails verification because that isn't the exact value. So a webhook endpoint needs both a GET route that answers the challenge and a POST route that receives the actual notifications, and forgetting the GET route is the most common reason a brand-new webhook silently never delivers.

The webhook secret you get exactly once

When your endpoint passes the challenge, Nylas generates a webhook_secret and returns it in the create response, and this is the one moment you'll see it. The secret appears in the POST /v3/webhooks response and again only if you rotate it; it is not included when you later GET the webhook. So you store it the instant you create the webhook, because there's no endpoint that hands it back later.

That secret is the signing key for everything that follows, so treat it like any other credential: keep it out of source control, out of logs, and in your secrets manager. The reason it matters is the next section, every notification is signed with this secret, and without it stored you can't verify that an incoming request actually came from Nylas. Losing it isn't fatal, you can rotate to a new one, but it does mean re-storing the replacement everywhere that verifies signatures.

Verify the signature on every notification

This is the security step you don't skip. Every notification carries an X-Nylas-Signature header (or lowercase x-nylas-signature, depending on your stack), which is a hex-encoded HMAC-SHA256 of the exact request body, signed with your webhook_secret. You recompute that HMAC over the raw body with your stored secret and compare, and if it doesn't match, you reject the request as unverified rather than processing it.

const crypto = require("crypto");

function verify(rawBody, signature, secret) {
  if (!/^[0-9a-f]{64}$/i.test(signature || "")) return false; // reject a missing or malformed signature
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest();
  return crypto.timingSafeEqual(expected, Buffer.from(signature, "hex"));
}

The phrase "exact request body" is load-bearing. The signature is computed over the raw bytes Nylas sent, so you have to verify against the unparsed body before any middleware reformats it, since re-serializing the JSON changes the bytes and breaks the comparison. Use a constant-time comparison, as above, rather than ===, so the check doesn't leak timing information. Verifying every notification is what stops an attacker who finds your webhook URL from posting forged events that your handler would otherwise trust.

The compression gotcha

One detail catches people who enable payload compression. Webhooks can gzip their payloads, and when compression is on, the HMAC-SHA256 signature is computed over the compressed bytes, not the decompressed JSON. So you validate the signature against the raw compressed body first, and only decompress after the signature checks out.

Reverse that order, decompress and then verify, and the signature will never match, because you're hashing different bytes than Nylas signed. This is a subtle one because it only bites when compression is enabled, so a webhook that verified fine in development can start failing signatures the moment someone turns on gzip. The rule is simple once you know it: signature first, on the bytes as received, decompression second.

Rotate the secret when you need to

Secrets sometimes need replacing, after a suspected leak, on a schedule, or when an employee with access leaves, and webhooks support rotation without recreating the endpoint. A POST /v3/webhooks/rotate-secret/{id} request issues a new webhook_secret and returns it, the second and only other time you see a secret value, after which notifications are signed with the new one.

nylas webhook rotate-secret <webhook-id> --yes

The CLI does the same with nylas webhook rotate-secret <id>, which requires the --yes flag to confirm the rotation, since it changes the signing key, and then prints the new secret for you to store. Without --yes, the command stops and tells you to re-run with it, a guard against rotating a production secret by accident. The operational care is to update your verification code with the new secret promptly, because once rotated, signatures use the new key immediately, and any handler still checking against the old secret will start rejecting genuine notifications. Rotate during a window where you can deploy the new secret quickly, and treat the printed value with the same care as the original.

Develop locally without deploying

Testing webhooks usually means deploying somewhere public, but the CLI removes that friction with a local receiver. nylas webhook server starts a local HTTP server that receives and prints webhook events, and with --tunnel cloudflared it exposes itself through a cloudflared tunnel so Nylas can reach your laptop directly, no deploy required. When the tunnel is on, you pass --secret so the server verifies the HMAC signature on each event, or --allow-unsigned to explicitly opt out.

# Receive real webhooks on your laptop, verifying signatures
nylas webhook server --tunnel cloudflared --secret <webhook-secret>

This is the fastest way to see real notifications during development, and it handles the challenge handshake and signature verification for you, the exact two things that are fiddly to get right by hand. There's also nylas webhook test send to fire a test event at a webhook URL and nylas webhook verify to check a signature against a payload locally, so you can confirm your verification logic against a known-good example before trusting it in production.

Where webhooks fit

The same create-verify-receive flow sits under every event-driven feature, and the triggers you choose shape what you build. A few that map straight on:

Real-time inbox sync. Subscribe to message.created, message.updated, and message.deleted to keep a local copy current the moment mail changes.
Calendar automation. React to event.created and event.updated to schedule reminders or sync bookings without polling the calendar.
Grant health monitoring. Listen for grant.expired so you can prompt a user to re-authenticate before their integration silently stops working.
Tracking and engagement. Receive message.opened and thread.replied to drive analytics or follow-up sequences off real recipient activity.

Each is the same webhook, verified the same way, with the difference being which triggers you subscribe to and what your handler does with the verified event.

Things to keep in mind

A short list of details keeps a webhook reliable and secure.

Answer the challenge in 10 seconds. Your GET route must echo the exact challenge value, no JSON, no quotes, or the webhook never activates.
Store the secret at creation. The webhook_secret is returned only on create and on rotate, never on a later GET, so save it immediately.
Verify every signature. Recompute the HMAC-SHA256 over the raw body with your secret and compare in constant time; reject anything that doesn't match.
Verify before decompressing. With gzip on, the signature covers the compressed bytes, so check it before you decompress.
Rotate when needed. Use the rotate-secret endpoint after a leak or on a schedule, and deploy the new secret promptly so genuine events keep verifying.
Develop with nylas webhook server --tunnel cloudflared. It receives real events locally and handles the challenge and signature, no deploy required.

Wrapping up

A secure webhook is three things done right. Create it with POST /v3/webhooks (or nylas webhook create) naming your URL and triggers, answer the challenge GET by echoing the exact value within 10 seconds so it activates, and store the webhook_secret from the create response because you only see it once. Then verify the X-Nylas-Signature HMAC on every notification against the raw body, decompressing only after the signature checks out, and rotate the secret when you need to. For development, nylas webhook server --tunnel cloudflared gives you real notifications on your laptop with the handshake and verification handled.

Where to go next:

Webhook notifications — the full guide to triggers, the challenge, and signatures
Receive webhooks with the CLI — the local server and verification
Create a webhook — the endpoint reference
Nylas CLI webhook commands — nylas webhook create, rotate-secret, and server

AI-answer pages for agents

When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com:

Topic runbook: https://cli.nylas.com/ai-answers/webhook-signature-verification-agent.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md