DEV Community: Qasim

Automated list hygiene for agent mail: bounce and complaint webhooks a suppression list

Qasim — Sun, 12 Jul 2026 15:19:51 +0000

Sending to dead or hostile addresses tanks your deliverability. A hard bounce means the mailbox doesn't exist; a complaint means a human hit "this is spam." Mailbox providers watch both rates obsessively, and once yours climb, they stop trusting your domain — your good mail starts landing in spam too. The cruel part is that an autonomous email agent will happily keep hammering a bad address forever unless you stop it, because nothing in a naive send loop ever learns that an address went bad.

Most "AI email" hygiene advice stops at "authenticate your domain and warm it up." That's table stakes. The interesting problem is the feedback loop: the agent sends, some sends fail or get reported, and you need that failure signal to flow back into the agent's behavior automatically. No human in the loop scrubbing CSVs. This post wires deliverability webhooks straight into a suppression List and a block rule, so an address that bounces or complaints once is never mailed again.

I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for. Every step shows both the raw HTTP call and the CLI equivalent, because that's how I actually debug this stuff — curl to see the wire, CLI to do it fast.

What you're building

The whole thing is a four-piece loop:

Deliverability webhooks (message.bounced, message.complaint) tell you which addresses went bad, in real time.
A suppression List of type address holds those bad addresses.
An outbound block rule matches recipient.address in_list <suppression-list> and rejects any send to a suppressed address before it leaves the building.
Your webhook handler does the only custom logic: pull the offending address out of the payload, add it to the list.

The elegant part is that pieces 2 and 3 are pure Nylas config — Policies, Rules, and Lists. Your code never has to maintain a denylist in your own database, never has to remember to check it before sending, and never has to special-case which agent is sending. The block happens at the platform, on the outbound path, for every Agent Account in the workspace. You just keep the list fed.

And the data plane is the same one you already know. An Agent Account is just a grant with a grant_id — it works with every grant-scoped endpoint, including Webhooks. There's nothing new to learn to receive these events; if you've subscribed to message.created before, this is the same mechanism with different trigger types.

Why this beats a denylist in your own database

You could absolutely keep a suppressed_emails table and check it before every send. People do. Here's why I don't:

The check is easy to forget. Every send path in your codebase has to remember to query the table first. Add a new send path, forget the check, and you're mailing bounced addresses again. The block rule can't be forgotten — it runs on the outbound path no matter who calls send.
It's the wrong layer. A block rule rejects the send with HTTP 403 before the message reaches the provider. Your own check rejects it after your code has already built the message. The platform block is strictly earlier and strictly harder to bypass.
Non-engineers can manage it. A List fronted by a rule means someone can add or remove an address without touching code or redeploying. The rule keeps matching the new values immediately.
It's multi-account by default. One suppression list, referenced by one workspace rule, covers every agent in that workspace. No per-tenant denylist plumbing.

The honest tradeoff: you're trusting Nylas to evaluate the rule on every send, and an outbound block returns a 403 your code has to handle like any delivery failure. If you want the suppression logic to live entirely in your own stack for portability reasons, the database approach is fine. For an autonomous agent where the whole point is not writing glue code, the rule wins.

Before you begin

You need:

A provisioned Agent Account (a grant with provider: "nylas") on a verified domain. If you don't have one, see Provisioning Agent Accounts.
Your NYLAS_API_KEY and the API base host. Examples here use https://api.us.nylas.com.
A public HTTPS endpoint to receive webhooks.

New to Nylas? Start at the Agent Accounts overview — it explains the grant model the rest of this assumes.

One thing to get straight up front about scope. Policies, Rules, and Lists are application-scoped and carried by workspaces, not individual grants. You attach a policy_id and rule_ids to a workspace, and every Agent Account in that workspace inherits them. Each application has a default workspace that holds any account you haven't placed in a custom one, so attaching the suppression rule there covers all your unassigned agents at once. The CLI commands below resolve the default workspace from your current default grant automatically.

Subscribe to the deliverability webhooks

This is the one step where the CLI can't help you, and I want to be honest about why. Agent Accounts emit four deliverability webhooks — message.delivered, message.bounced, message.complaint, and message.rejected — and these are the events Nylas itself uses to calculate your bounce and complaint rates. They're real API trigger types. But the CLI's nylas webhook triggers list doesn't include them yet; it still shows the older transactional triggers like message.bounce_detected. So for this subscription, you go through the API directly.

Create a webhook destination subscribed to the two triggers that matter for suppression:

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.bounced", "message.complaint"],
    "webhook_url": "https://yourapp.example.com/webhooks/nylas",
    "notification_email_addresses": ["ops@yourcompany.com"],
    "description": "Agent Account suppression feed"
  }'

You can add message.delivered and message.rejected to the same trigger_types array if you also want to track positive delivery and virus-rejected sends — message.rejected fires specifically when an outbound message is rejected because one or more attachments contained a virus, not as a generic rejection signal. Both are useful for dashboards, but neither drives suppression. For suppression specifically, message.bounced and message.complaint are the two you act on.

CLI note (the honest version): because message.bounced and message.complaint aren't in the CLI's trigger enum, nylas webhook create --triggers message.bounced will reject the value. The CLI is great for the other webhook types — nylas webhook create --url https://yourapp.example.com/webhooks/nylas --triggers message.created works fine — but for the deliverability triggers, subscribe via the curl call above. If you want to confirm what the CLI does expose, run nylas webhook triggers --category message and you'll see the bounced/complaint deliverability triggers are absent.

Build the suppression list

Now the part that is fully CLI-friendly. Create an address-typed List to hold the addresses you'll suppress. The type is immutable, and it determines which rule fields the list can match — an address list matches from.address and recipient.address, which is exactly what we want for outbound suppression.

API:

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

The response hands back the list id you'll need for both adding items and wiring the rule:

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "id": "d1e2f3a4-5678-4abc-9def-0123456789ab",
    "name": "Suppressed addresses",
    "type": "address",
    "items_count": 0,
    "created_at": 1742932766,
    "updated_at": 1742932766
  }
}

CLI:

nylas agent list create --name "Suppressed addresses" --type address

That prints the new list ID. If you want to seed it with known-bad addresses at creation time, pass --item (repeatable):

nylas agent list create --name "Suppressed addresses" --type address \
  --item known-bad@example.com

Add a bad address to the list

When your handler decides an address is dead, it adds it to the list. Up to 1000 items per request; values are lowercased, trimmed, and validated against the list's type, and duplicate additions are silently ignored — which is exactly the behavior you want, because the same address can bounce more than once and you don't want to special-case that.

API:

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": ["jane@example.com"]
  }'

CLI:

nylas agent list add <LIST_ID> jane@example.com

The silent dedupe is the detail I appreciate as an SRE. You don't have to read-before-write or guard against races between two bounce events for the same address arriving at once. Just add; the API sorts it out.

Block sends to suppressed addresses

The list does nothing on its own — it's just data. The rule is what makes it bite. Create an outbound rule that blocks any send where a recipient address is in_list your suppression list. Because block is terminal and evaluated before the message reaches the provider, a suppressed recipient means the send is rejected with 403 and no sent copy is stored.

One subtlety worth knowing: recipient.address matches against any recipient — To, CC, BCC, and the SMTP envelope. So if a single suppressed address is buried in the BCC of a 50-recipient send, the whole send is blocked. For suppression that's usually the right call; you'd rather fail loudly than quietly mail a known-bad address. Just be aware of it when you design batch sends.

API:

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 sends to suppressed addresses",
    "priority": 1,
    "trigger": "outbound",
    "match": {
      "conditions": [
        {
          "field": "recipient.address",
          "operator": "in_list",
          "value": ["<LIST_ID>"]
        }
      ]
    },
    "actions": [
      { "type": "block" }
    ]
  }'

CLI — the --condition flag takes field,operator,value, and for in_list the value is the list ID:

nylas agent rule create \
  --name "Block sends to suppressed addresses" \
  --trigger outbound \
  --priority 1 \
  --condition recipient.address,in_list,<LIST_ID> \
  --action block

The CLI creates the rule through /v3/rules and attaches it to the default workspace for you, resolved from your current default grant — so the CLI path is already activated. The API path is not: a rule created through POST /v3/rules is inert until a workspace references it. That's the next step.

Activate the rule on a workspace

A rule does nothing until a workspace references it. If you created the rule through the API, add its ID to a workspace's rule_ids array to make it run. That array carries inbound and outbound rules together; Nylas filters by trigger at evaluation time, so listing the rule here is what makes it fire for every Agent Account in the workspace.

API:

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 '{
    "rule_ids": ["<RULE_ID>"]
  }'

CLI — the flag is --rules-ids (comma-separated):

nylas workspace update <WORKSPACE_ID> --rules-ids <RULE_ID>

Attach to the default workspace if you don't manage workspaces explicitly — it holds every Agent Account you haven't placed in a custom one, so suppression covers all your unassigned agents at once. One caveat: rule_ids replaces the array, so include any existing rule IDs you want to keep alongside the new one.

I set priority: 1 deliberately. Rules run lowest-number-first, and the first matching block is terminal. You want suppression to be the first thing evaluated on the outbound path, ahead of any routing or archiving rules, so a suppressed send dies immediately and never burns evaluation on rules that no longer matter.

Wire the handler: payload → list

Here's the only code you write. The two payloads carry the offending addresses in slightly different shapes, so handle each trigger type explicitly rather than guessing.

A message.bounced event puts the bounced recipients under data.object.bounce.recipients, each an object with an email field (and sometimes a diagnostic_code):

{
  "type": "message.bounced",
  "data": {
    "grant_id": "<NYLAS_GRANT_ID>",
    "object": {
      "bounce": {
        "type": "MailboxFull",
        "recipients": [
          { "email": "jane@example.com", "diagnostic_code": "smtp; 550 user unknown" }
        ]
      }
    }
  }
}

A message.complaint event puts them under data.object.complaint.complained_recipients, a flat array of address strings:

{
  "type": "message.complaint",
  "data": {
    "grant_id": "<NYLAS_GRANT_ID>",
    "object": {
      "complaint": {
        "type": "abuse",
        "complained_recipients": ["jordan.taylor@example.com"]
      }
    }
  }
}

So the handler logic is: branch on type, pull the addresses out of the right field, and POST them to your list's /items endpoint. In pseudocode:

on webhook (event):
  if event.type == "message.bounced":
    addresses = [r.email for r in event.data.object.bounce.recipients]
  elif event.type == "message.complaint":
    addresses = event.data.object.complaint.complained_recipients
  else:
    return  # ignore everything else

  POST https://api.us.nylas.com/v3/lists/<LIST_ID>/items
       { "items": addresses }

That's the entire feedback loop. From here on, any agent in the workspace that tries to mail one of those addresses gets a 403, and you never have to think about it again.

Guardrails and gotchas

A few things I'd want a teammate to know before shipping this:

Handle the 403 on send. An outbound block returns 403 and stores no sent copy. Treat it exactly like any other permanent delivery failure — there is no retry path that will deliver it. If your agent has retry logic, make sure a 403 short-circuits it instead of looping.
Rule evaluation fails closed. If the in_list lookup hits a transient infrastructure error, Nylas blocks the send rather than letting it through — but it returns 503 (not 403) and inbound SMTP returns a 451 tempfail, so the distinction is retryable-vs-permanent. A 503 means "try again later"; a 403 means "this address is genuinely suppressed." Don't collapse them.
Bounces aren't all permanent. A MailboxFull bounce can be transient — that mailbox might come back tomorrow. If you suppress aggressively on every bounce type, you'll permanently lose recipients who had a full inbox for a day. Consider only suppressing on hard bounces (nonexistent mailbox, 550 user unknown) and treating soft bounces as a back-off signal instead. The diagnostic_code and type fields give you what you need to make that call.
Audit what got blocked. When someone asks "why didn't this send go out," call GET /v3/grants/{grant_id}/rule-evaluations to see exactly which rule matched and why. The records carry the normalized recipient data and the matched rule IDs, so you can prove a block came from suppression and not from something else. This one is API-only — there's no rule-evaluations subcommand under nylas agent, so reach for curl:

  curl --request GET \
    --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/rule-evaluations?limit=50" \
    --header "Authorization: Bearer <NYLAS_API_KEY>"

Verify everything against the help text. The CLI surface moves; before you script nylas agent rule create or nylas agent list add into a pipeline, run the command with --help and confirm the flags. That's the same habit that caught the missing deliverability triggers above.

What's next

Email deliverability for Agent Accounts — the authentication, DMARC, and warm-up work that suppression complements
Policies, Rules, and Lists — the full rule grammar, condition fields, and list types
Agent Account webhook notifications — the complete schemas for the delivery, bounce, complaint, and rejection events
Usage limits — the bounce and complaint thresholds that pause sending, and what a pause looks like to your code
Nylas CLI commands — the full command reference for nylas agent and nylas webhook

Authentication gets you delivered. Suppression keeps you delivered. The two together are the difference between an agent that ages into spam folders and one that stays in the inbox because it learned to stop knocking on doors that don't open.

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/agent-account-bounce-monitoring.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Allowlist and denylist rules for agent email, backed by Lists

Qasim — Sun, 12 Jul 2026 15:19:34 +0000

The usual way to keep an AI email agent from talking to the wrong people is a hardcoded set in your application code:

ALLOWED_DOMAINS = {"yourcompany.com", "customer.example"}

That works, and for a single internal agent it's the right call. But the moment a non-engineer needs to add a customer domain, or you want the same allowlist to govern five different agents, or you want it to apply to mail coming in and not just going out, that set in code becomes a deploy-shaped bottleneck. Every change is a PR, a review, a release.

There's a layer below your code that can carry that policy for you. An Agent Account on Nylas evaluates Rules against every message — inbound on arrival, outbound on send — and those rules can point at Lists, which are typed, editable collections of domains, TLDs, or addresses. Update a list, and every rule that references it picks up the change immediately. No redeploy, no code change, no model in the loop.

This post goes deep on that pattern: Lists fronted by the in_list rule operator, used for allow and block on both directions. If you've already read the basic inbound/outbound filtering post, this is the part that makes the filtering dynamic.

What you actually get

The data plane doesn't change. An Agent Account is just a grant with a grant_id, and everything you already know about Messages, Drafts, Threads, and Folders still applies. Rules and Lists sit one level up, on the control plane — they're application-scoped admin resources with no grant ID in the path. Your API key identifies the application, and the rules apply to every Agent Account in a workspace.

So the mental model is two planes:

Data plane — GET /v3/grants/{grant_id}/messages, nylas email send, the stuff your agent does.
Control plane — POST /v3/lists, POST /v3/rules, the stuff that decides what the agent is allowed to do.

A List holds values. A Rule references a list through the in_list operator and says "if the sender domain is in this list, block it" (or assign it, or archive it). Change the list, and the rule's behavior changes with it. That indirection is the whole point: the what (which domains) lives in a list a human can edit; the how (block vs. route) lives in a rule you set once.

Why this beats a code-side allowlist

A few honest tradeoffs, because a static ALLOWED_DOMAINS set genuinely is simpler when you only have one agent:

Editable without a deploy. Someone updates a list through the API or a CLI command, and the change is live. No PR, no release. This is the reason to reach for it.
One list, many rules. A single "Blocked domains" list can feed an inbound block rule and an outbound block rule. Update it once, both directions follow.
Both directions. A code-side check before your send call only covers outbound. Rules also reject inbound mail at SMTP, before it ever lands in the mailbox or fires a message.created webhook — so your application never even sees it.
Fails closed on infrastructure errors. If a block rule can't evaluate a list lookup because of a transient error, Nylas blocks the message rather than letting it slip through. Inbound gets a 451 tempfail so the sender retries; an API send gets a retryable 503.

The flip side: if your agent legitimately needs to reach arbitrary external recipients — an open-ended sales tool, say — a static allowlist will block valid sends and frustrate the workflow. Lists fit internal and known-customer agents, not cold outreach. For that case, lean on volume caps and human approval instead, which the restrict agent recipients cookbook recipe covers.

Before you begin

You need an Agent Account (a grant created via POST /v3/connect/custom against a registered domain — see Agent Accounts), an API key for the same application, and the host in your examples set to https://api.us.nylas.com. Every API call below carries Authorization: Bearer <NYLAS_API_KEY>.

I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for. Three subcommands cover the whole flow, and each maps to a distinct piece: nylas agent list manages list resources (/v3/lists), nylas agent rule manages rules (/v3/rules), and nylas workspace update attaches a rule to a workspace via its rule_ids. They don't overlap — nylas agent list never touches workspaces, and a created rule does nothing until a workspace references it (more on that below). Where it matters I'll show both the curl and the CLI form. CLI reference lives at cli.nylas.com/docs/commands.

One thing to internalize up front about which fields each direction can match, because it's the most common mistake:

Inbound rules can only match from.* fields — from.address, from.domain, from.tld. You only know who sent it.
Outbound rules can match from.*, recipient.* (recipient.address, recipient.domain, recipient.tld), and outbound.type (compose vs. reply).

That asymmetry drives everything below. You allowlist senders on the way in, and recipients on the way out.

Create a List of domains

A list has a fixed type — domain, tld, or address — set at creation and immutable. The type decides which rule fields it can match: a domain list matches from.domain and recipient.domain, an address list matches the .address fields, and so on. Start with a domain list, since most allow/block decisions are domain-level.

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"
  }'

The response carries the list id you'll reference from rules:

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "id": "d1e2f3a4-5678-4abc-9def-0123456789ab",
    "name": "Blocked domains",
    "type": "domain",
    "items_count": 0,
    "created_at": 1742932766,
    "updated_at": 1742932766
  }
}

Same thing from the CLI, which can seed items at creation time with repeatable --item flags:

nylas agent list create \
  --name "Blocked domains" \
  --type domain \
  --item spam-domain.com \
  --item another-bad-domain.net

The --type is domain, tld, or address, and it's immutable — pick it deliberately. The CLI hint says it plainly: the type "determines which rule fields the list can match in in_list conditions."

Add items to a List

Lists are where the dynamic part lives. Add up to 1000 items per request; values are lowercased, trimmed, and validated against the list's type, so a domain list rejects full email addresses. Duplicate additions are silently ignored, which means you can re-run an add idempotently.

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-domain.com", "another-bad-domain.net"]
  }'

From the CLI, items are positional arguments after the list ID:

nylas agent list add <LIST_ID> spam-domain.com another-bad-domain.net

This is the command you hand to a non-engineer, or wire into an internal admin panel, or call from a webhook handler when an abuse report comes in. It's a single API write that immediately changes the behavior of every rule pointing at the list — no rule edit, no deploy. To pull a domain back out, nylas agent list remove <LIST_ID> spam-domain.com (or DELETE /v3/lists/{list_id}/items).

Block inbound mail with an `in_list` rule

Now wire a rule to the list. For inbound, you can only match on the sender, so this is a denylist of sender domains. The key is "operator": "in_list" with the list ID — note that value is an array of list IDs, not the domains themselves. A single in_list condition can reference up to 10 lists.

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 senders on our blocklist",
    "priority": 1,
    "trigger": "inbound",
    "match": {
      "conditions": [
        {
          "field": "from.domain",
          "operator": "in_list",
          "value": ["<LIST_ID>"]
        }
      ]
    },
    "actions": [
      { "type": "block" }
    ]
  }'

The CLI condition format is field,operator,value. For in_list, the trailing comma-separated values are list IDs — field,in_list,list-id-1,list-id-2 — which maps directly to the array in the JSON above:

nylas agent rule create \
  --name "Block senders on our blocklist" \
  --trigger inbound \
  --priority 1 \
  --condition from.domain,in_list,<LIST_ID> \
  --action block

The block action is terminal — it can't be combined with other actions. For inbound, it rejects the message at SMTP, so it never reaches the mailbox and never fires a message.created webhook. Your application is genuinely insulated from that sender.

A note on priority and rule ordering: rules run lowest priority first (range 0–1000, default 10), and the first matching block wins. Put your specific in_list block ahead of any broad contains rules so the precise check fires first.

Activate the rule on a workspace

Here's the step that trips people up: creating the List and the Rule isn't enough. A rule is inert until a workspace references it. Workspaces carry policies and rules — you don't attach a rule to a grant directly. You add the rule's ID to a workspace's rule_ids array, and from then on it runs for every Agent Account in that workspace. One array carries both inbound and outbound rules; Nylas filters by trigger at evaluation time, so the same array can hold your inbound block and your outbound block side by side.

Attach the rule with PATCH /v3/workspaces/{workspace_id}. Pass the full set of rule IDs you want active — this replaces the array, so include any existing rules you want to keep:

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 '{
    "rule_ids": ["<INBOUND_RULE_ID>"]
  }'

From the CLI, nylas workspace update takes a comma-separated list of rule IDs:

nylas workspace update <WORKSPACE_ID> --rules-ids <INBOUND_RULE_ID>

If you don't know the workspace ID, the default workspace is the one that holds any Agent Account you haven't placed in a custom workspace, so attaching there covers your unassigned accounts. As a convenience, nylas agent rule create resolves the default grant's workspace and attaches the new rule to it for you — but when you create rules over the raw API, or you want a rule to apply to a non-default workspace, this PATCH is the step that actually turns the rule on. Re-run it whenever you add an outbound rule below, listing every rule ID you want active.

Allow vs. block on outbound

Outbound is where the allowlist pattern gets interesting, because you have two ways to express "only talk to approved recipients," and they fail in opposite directions.

The blocklist version — block sends to a list of denied recipient domains — is permissive by default. Anything not on the list goes through. Good for known-bad domains, competitors, test domains that leaked into production:

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 sends to denied recipients",
    "trigger": "outbound",
    "match": {
      "conditions": [
        {
          "field": "recipient.domain",
          "operator": "in_list",
          "value": ["<DENY_LIST_ID>"]
        }
      ]
    },
    "actions": [
      { "type": "block" }
    ]
  }'

nylas agent rule create \
  --name "Block sends to denied recipients" \
  --trigger outbound \
  --condition recipient.domain,in_list,<DENY_LIST_ID> \
  --action block

This rule, like the inbound one, does nothing until it's on a workspace's rule_ids. Re-run the PATCH /v3/workspaces/{workspace_id} (or nylas workspace update <WORKSPACE_ID> --rules-ids <INBOUND_RULE_ID>,<OUTBOUND_RULE_ID>) with both IDs in the array — the same array carries both directions, and Nylas runs each rule only on its matching trigger.

A true allowlist — block any recipient not on the approved list — is stricter and fails closed. Worth being precise about what the rule engine supports here: in_list matches when a value is present in the list, so it expresses "block what's on the denylist" directly. There's no not_in_list operator. For the strict "deny everything except the allowlist" semantics, the durable pattern is to keep the hard fail-closed allowlist in your send wrapper — where an empty or unknown domain is denied by default — and use the Nylas in_list block rule for the dynamic denylist layer on top.

In practice that split works well: the rule is the editable, no-deploy layer a non-engineer can update; the wrapper is the fail-closed gate your code owns. The restrict agent recipients recipe covers the wrapper side. Don't try to make one do both jobs.

One important behavioral detail for outbound: recipient.* matches against any recipient, including CC, BCC, and SMTP envelope recipients. That's exactly what you want for data-loss prevention — a hidden BCC to a denied domain still trips the block. An outbound block returns 403 to your send call and stores no sent copy; treat it like any other non-retryable delivery failure.

Route inbound mail by list instead of blocking

in_list isn't only for blocking. Swap the action and you've got dynamic routing. Keep a list of "VIP customer domains" and auto-star or folder their mail without touching code when a new customer signs:

curl --request POST \
  --url "https://api.us.nylas.com/v3/rules" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Star VIP senders",
    "trigger": "inbound",
    "match": {
      "conditions": [
        {
          "field": "from.domain",
          "operator": "in_list",
          "value": ["<VIP_LIST_ID>"]
        }
      ]
    },
    "actions": [
      { "type": "mark_as_starred" }
    ]
  }'

nylas agent rule create \
  --name "Star VIP senders" \
  --trigger inbound \
  --condition from.domain,in_list,<VIP_LIST_ID> \
  --action mark_as_starred

The non-blocking actions — mark_as_starred, mark_as_read, assign_to_folder, archive, mark_as_spam, trash — all compose with in_list. Sales adds a domain to the VIP list, and the agent's inbox starts starring that customer's mail. Nobody touched a rule.

Guardrails and gotchas

A few things I've watched people trip over:

A rule does nothing until it's on a workspace. The most common "my rule isn't firing" cause is a rule that was created but never added to a workspace's rule_ids. Creating the List and Rule is two-thirds of the job; the PATCH /v3/workspaces/{workspace_id} is what arms it.
rule_ids is a full replacement. The PATCH replaces the array, it doesn't append. List every rule ID you want active each time, or you'll silently detach the ones you left out.
List type must match the field. A domain list only works with from.domain / recipient.domain. Point a from.address condition at a domain list and it won't match. Pick the type to fit the field you'll match.
value is an array of list IDs for in_list, not the values. The domains live in the list; the rule references the list by ID. This catches everyone once.
Inbound can't see recipients. You cannot allowlist recipients on inbound rules — there's no recipient.* on the inbound trigger, because there's only one recipient (the agent) and it's already known. Recipient allow/block is outbound-only.
Up to 10 lists per in_list condition, 500 chars per value, 50 conditions and 20 actions per rule. Generous, but real caps.
Deleting a list cascades. Items go with it, and rules that referenced it via in_list simply stop matching its values. No dangling references, but also no warning — audit before you delete.
Audit what actually fired. When something gets blocked or routed unexpectedly, GET /v3/grants/{grant_id}/rule-evaluations lists every evaluation most-recent-first, with the matched rule IDs and applied actions. It's the fastest answer to "why did this message get blocked?"

What's next

The combination to remember: a List is the editable noun, the in_list operator is the indirection, the trigger decides whether you're filtering senders (inbound) or recipients (outbound), and the workspace rule_ids array is what arms everything. Create the list, create the rule, attach the rule — skip that last step and nothing fires. Once those click, you can hand the who to a non-engineer and keep the how in version control.

Policies, Rules, and Lists for the full schema — every operator, action, and field
Restrict agent recipients for the application-side fail-closed allowlist that pairs with these rules
Agent Accounts to provision a grant against a registered domain
CLI commands for nylas agent list, nylas agent rule, and nylas workspace update reference

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/agent-account-rules-lists-api-cookbook.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Distribute meeting notes from an agent's calendar

Qasim — Sun, 12 Jul 2026 15:18:40 +0000

Notes are useless if they sit in a doc nobody opens. You've seen it: the meeting ends, someone pastes a summary into a shared doc, drops the link in a channel, and three days later the action items are still unassigned because nobody scrolled to the bottom. The information existed. It just never reached the people who needed it, in the place they actually read.

Most "AI meeting notes" demos solve the capture problem and stop there. They join the call, transcribe it, generate a tidy summary — and then hand you a URL. The distribution is left as an exercise for the reader. That's the part I want to fix here, and the interesting move is to make distribution a calendar-triggered job instead of a manual one.

The pattern: when an event on an agent's calendar ends, read the event's participant list, and email a recap to each attendee — sent from the agent's own address so any reply threads straight back into a real mailbox the agent already owns. No shared doc, no "find the link," no human in the loop.

A quick honesty note up front, because it changes the design: this post deliberately does not use Nylas Notetaker. Notetaker isn't supported for Agent Accounts. So the agent doesn't get the notes from Nylas — the notes are your application data (whatever your own pipeline produced: an LLM summary, structured action items, a CRM export). Nylas's job here is narrow and reliable: tell you who was in the meeting, and put the email in their inbox from an address that can receive replies. That's it. We lean on two primitives — Events and Send — and nothing else.

What you get

The participant list, straight from the event. No scraping the invite email. The event object already carries participants[], each with an email and an RSVP status.
A real sender identity. The recap comes from notes-bot@yourcompany.com (the agent), not a no-reply relay. Someone hits Reply, asks a question, and it lands in a mailbox the agent reads.
A trigger tied to the meeting, not to a human remembering. When the event's end time passes, the recap goes out.
Nothing new on the data plane. An Agent Account is just a grant with a grant_id. Every endpoint below is the ordinary grant-scoped Events and Messages API you'd use for any connected account. There's nothing agent-specific to learn — the agent is a grant.

Why this beats pasting a link in a channel

Channels are lossy. The recap competes with forty other messages, gets collapsed, and is unsearchable to anyone who joined the project late. Email to the exact attendee list is addressed, durable, and — because it comes from the agent's real address — conversational. The recipient can reply with "wait, who owns item 2?" and that question reaches the agent.

It also sidesteps a permission headache. You're not trying to inject the agent into someone's human inbox or borrow a person's credentials to send "as" them. The agent is a participant with its own mailbox. It reads its own calendar, it sends from its own address. Clean trust boundary.

Before you begin

You need an Agent Account, which is a grant created on a registered domain. Two ways to make one.

The API call is POST /v3/connect/custom with "provider": "nylas" and a settings.email on a domain you've registered (a custom domain, or a *.nylas.email trial subdomain). The optional top-level name sets the display name. No refresh token, because there's no external provider to authenticate against.

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": "Notes Bot",
    "settings": { "email": "notes-bot@yourcompany.com" }
  }'

I work on the CLI, so the terminal commands below are the exact ones I reach for. The CLI equivalent is one line:

nylas agent account create notes-bot@yourcompany.com --name "Notes Bot"

The API auto-creates a default workspace and policy for the account. There's no --workspace flag on create — if you want to attach a custom policy later, you do it separately with nylas workspace update <workspace-id> --policy-id <policy-id>. The response gives you a grant_id. That's the only identifier the rest of this flow needs.

Verify the CLI is wired to your project by listing the agent grants — these are just grants with provider: nylas, so the API form is a filtered GET /v3/grants:

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

nylas agent account list

Read the event and its participants

When you want to send a recap, you start from the event. Two situations:

You already know the event ID (you created it, or stored it when the agent scheduled the meeting). Fetch it directly.
You're sweeping the calendar for meetings that just ended. List events and filter.

Fetch one event by ID

GET /v3/grants/{grant_id}/events/{event_id} returns the event, including its when block and participants[]. The calendar_id query parameter is required — use primary for the agent's primary calendar.

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

The CLI verb is show (aliased to get/read). It takes the event ID and an optional grant ID, plus -c/--calendar:

nylas calendar events show <EVENT_ID> <GRANT_ID> --calendar primary --json

The piece you care about in the response is the participant array and the end time:

{
  "data": {
    "id": "<EVENT_ID>",
    "title": "Q1 planning",
    "when": {
      "object": "timespan",
      "start_time": 1744387200,
      "end_time": 1744390800
    },
    "participants": [
      { "email": "alice@example.com", "status": "yes" },
      { "email": "bob@example.com", "status": "yes" },
      { "email": "carol@example.com", "status": "noreply" }
    ]
  }
}

That's your distribution list, already deduplicated and already RSVP-aware. You can choose to skip the noreply and no participants if you only want to recap to people who actually showed up — status is right there on each entry. (One caveat worth stating: for Microsoft Graph events a participant's email can be missing, so guard for it before you build the to list.)

List events to find the ones that ended

If you're polling, list the calendar and look at each event's when.end_time.

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

nylas calendar events list <GRANT_ID> --calendar primary --days 1 --limit 50 --json

--days 1 keeps the window tight to recent meetings, and --limit auto-paginates past 200 if you need it. Each event in the list carries the same when and participants fields as the single-event fetch.

How you actually detect "the meeting ended"

This is the part people hand-wave, so let me be precise about it: there is no "event ended" webhook. Agent Account calendars emit event.created, event.updated, and event.deleted — those fire when an event is created, changed, or removed, not when its end time passes. The clock running out is not a state change, so nothing fires for it.

So the trigger is yours, and it's a comparison, not a notification: you compare the event's when.end_time (a Unix timestamp) to the current time, in your own scheduler. Two honest ways to do it:

Poll. Run a job every few minutes that lists recent events (the events list call above) and pick the ones where end_time < now and you haven't already recapped. Cheap, dead simple, and good enough for most calendars.
Schedule off the event lifecycle. Subscribe to event.created/event.updated at the app level, and when one arrives, read its end_time and enqueue a one-shot job for that timestamp (a delayed task, a cron entry, a setTimeout in a durable queue — whatever your stack uses). The webhook isn't the "ended" signal; it's just your cue to schedule the check. If the event later moves, event.updated fires and you reschedule.

Either way, you own the "it's over now" decision. Don't tell yourself Nylas pushes it to you — it doesn't, and a design that assumes a phantom webhook will silently never send.

Whichever you pick, keep a dedup record (the event ID plus its end_time) so a re-run or a retried job doesn't email everyone twice. If the meeting time changed and you already sent a recap for the old slot, that's a product decision: usually you don't re-send.

One more accuracy note on webhooks generally, since you'll likely subscribe to event.*: webhooks are application-scoped, not grant-scoped. You subscribe once at the app level with POST /v3/webhooks, and events for every grant arrive at that one endpoint, each payload carrying a grant_id you filter on. So you're not registering a webhook per agent — one subscription covers the whole fleet, and you route on grant_id.

The subscription itself is one call:

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": ["event.created", "event.updated"],
    "webhook_url": "https://your-server.com/webhooks/nylas",
    "description": "Recap scheduler triggers"
  }'

nylas webhook create --url https://your-server.com/webhooks/nylas --triggers event.created,event.updated

Email the recap from the agent's address

Now the payload. Remember: the notes are your data. Nylas didn't generate them — your summarization step did. You bring the summary and actionItems; Nylas delivers them.

Build the body however you like (HTML reads best across clients), set the recipient list from the participants you read earlier, and send with POST /v3/grants/{grant_id}/messages/send. The message goes out from the agent's own mailbox, which is the whole point — a reply comes back to an address the agent owns.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "Recap: Q1 planning - summary & action items",
    "body": "<html><body><p>Hi everyone,</p><h2>Summary</h2><p>We locked the Q1 roadmap and split ownership for the first sprint.</p><h2>Action items</h2><ul><li>Alice: finalize the API spec by Friday</li><li>Bob: book the design review</li></ul></body></html>",
    "to": [
      { "email": "alice@example.com" },
      { "email": "bob@example.com" }
    ]
  }'

The CLI sends the same message. --to accepts a repeatable list, so you fan it out to every participant:

nylas email send <GRANT_ID> \
  --to alice@example.com \
  --to bob@example.com \
  --subject "Recap: Q1 planning - summary & action items" \
  --body "<html><body><p>Hi everyone,</p><h2>Summary</h2><p>We locked the Q1 roadmap...</p></body></html>"

A design choice worth thinking about: one email to everyone, or one email per person?

One email, everyone on the to line is simplest and makes the thread a group conversation — a reply goes to the whole list. Good for a team that wants to discuss the action items together.
One email per participant lets you personalize ("Carol, your two items are...") and keeps replies private, but it's N sends instead of one. If you go this way, loop the events send/messages/send call per recipient.

Either way, because the sender is the agent's real address, replies thread back to the agent. That's the property you don't get from a no-reply relay or a "view in browser" link. If you want to read those replies, that's the ordinary thread API — GET /v3/grants/{grant_id}/threads/{thread_id} returns the thread and its messages:

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

nylas email threads show <THREAD_ID> <GRANT_ID>

And the agent answers by sending with reply_to_message_id set to the message it's replying to, which keeps everything in the same thread:

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 '{
    "reply_to_message_id": "<MESSAGE_ID>",
    "body": "Good question — Bob owns item 2.",
    "to": [ { "email": "alice@example.com" } ]
  }'

nylas email reply <MESSAGE_ID> <GRANT_ID> --body "Good question — Bob owns item 2."

Putting the trigger and the send together

The loop, end to end, is small:

Your scheduler wakes up (poll) or a scheduled job fires (lifecycle-driven).
Read the event: nylas calendar events show <EVENT_ID> <GRANT_ID> --calendar primary --json (or the GET curl).
Check when.end_time < now and that you haven't recapped this event yet.
Build the to list from participants[], dropping entries without an email and (optionally) anyone whose status is no.
Attach your summary and action items.
Send from the agent: nylas email send <GRANT_ID> --to ... --subject ... --body ... (or the messages/send curl).
Record the event ID as recapped.

No Notetaker, no shared doc, no human remembering to follow up. The meeting's own end time is the trigger, and the agent's own mailbox is the sender.

Guardrails and gotchas

The trigger is yours — own it. There's no event-ended webhook. If your poll job dies, recaps silently stop. Alert on "events that ended more than 15 minutes ago with no recap sent" so a stuck scheduler is visible, not invisible.
Dedup hard. Both poll and scheduled-job designs can fire twice (a retry, an overlapping cron, an event.updated that reschedules). Key your "already sent" record on event ID, and decide your policy if end_time changed after you sent.
Sends count against the account's daily quota. On the free plan that's 200 messages per account per day. One email per participant burns through that faster than one group email — for a busy agent recapping large meetings, the per-recipient pattern adds up. Pick the fan-out strategy with the quota in mind.
Guard for missing participant emails. For Microsoft Graph events the email field can be absent on a participant. Filter those out before building to, or the send fails.
A new domain warms over ~4 weeks. If you spin up a fresh sending domain for the agent, deliverability ramps up gradually — early recaps may be more likely to land in spam until the domain is warm. A *.nylas.email trial subdomain is fine for testing the flow before you commit a custom domain.
The notes are your responsibility, not Nylas's. Worth repeating because it's the design's load-bearing assumption: Notetaker is unsupported for Agent Accounts, so nothing in this pipeline gives you a transcript or summary. You generate that content. Nylas tells you the attendees and delivers the mail.

What's next

How Agent Account calendars work — the full picture of an agent hosting, receiving, and RSVPing to events, all on the same grant-scoped Events API.
Agent Accounts overview — what a grant-as-agent is and what it can do across Messages, Calendars, and Webhooks.
Automate meeting follow-up emails — the connected-account version of this flow, which does use Notetaker to generate the notes. A useful contrast: same distribution idea, different capture source.
Nylas CLI commands — every nylas agent, nylas calendar events, and nylas email subcommand used above.

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/meeting-summary-delivery-by-email-agent.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Warm a sending domain when you provision a new agent tenant

Qasim — Sun, 12 Jul 2026 15:18:27 +0000

Most "give every tenant its own AI agent" walkthroughs end at the moment the grant exists. You register a domain, create the agent account, fire off a "welcome, I'm your assistant" email, and call the onboarding done. That's fine right up until the first batch of those emails lands in spam — because a brand-new tenant domain has zero sending reputation, and a cold blast of mail from an unknown domain is exactly the shape mailbox providers are trained to filter.

I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for when I'm scripting tenant provisioning. The interesting part of this post isn't deliverability in the abstract — there's already a good general post on that. The angle here is narrower and more operational: treating domain warm-up as a step in your provisioning pipeline. When you onboard a new tenant and spin up its agent on a fresh domain, the warm-up ramp isn't an afterthought you run later — it's part of standing the tenant up. So this is a two-angle tour (curl + CLI) through the whole sequence: register and verify the domain, provision the agent, enforce a daily send cap that matches the ramp, send the first warm-up batch, and watch the bounce/complaint signals so you can back off if reputation dips.

What you're actually provisioning

An Agent Account is just a grant. That's the whole spine of this post. Once it exists, it has a grant_id and works with every grant-scoped endpoint you already know — Messages, Drafts, Threads, Folders, Contacts, Calendars, Events, Webhooks. There's nothing new to learn on the data plane. You send mail with POST /v3/grants/{grant_id}/messages/send, the same call you'd use for a connected Gmail grant.

The difference is on the reputation plane. A connected Google or Microsoft grant inherits the provider's established sending reputation. An Agent Account sends from a domain you own, through Nylas-managed infrastructure, so its inbox placement is yours to build from nothing. That's the catch the demos skip: provisioning the grant is instant, but earning the right to send at volume is a four-week process.

So the provisioning checklist for a new tenant on a new domain looks like this:

Register and verify the domain (DKIM, SPF, ownership, MX).
Provision the tenant's Agent Account on that domain.
Attach a policy that caps daily sends to this week's ramp number.
Send a small warm-up batch to engaged recipients.
Subscribe to deliverability webhooks and watch for bounces/complaints.

Steps 1–4 you do once at onboarding. Step 3 you revisit weekly as the ramp climbs. Let's walk it.

Step 1: Register and verify the tenant's domain

Authentication is the foundation. Nothing else matters if recipient servers can't confirm the mail is really from you. For Agent Accounts that comes down to records you publish during domain setup: DKIM adds a cryptographic signature proving the message wasn't altered and came from your domain, and SPF authorizes Nylas to send on your behalf. Both are verified before a custom domain can host accounts — so by the time an Agent Account exists, its domain is already DKIM- and SPF-authenticated. Nylas also tracks DMARC and ARC, but it doesn't enforce them, which means DMARC is the one layer you add yourself (more on that in the guardrails section).

Honest note on the tooling here: there is no nylas domain command. I checked — the CLI doesn't manage domains. Domain registration runs through the Nylas Dashboard at dashboard-v3.nylas.com/organization/domains, or through the Manage Domains API. And that API isn't a plain Authorization: Bearer call — it uses Nylas Service Account authentication, which signs each request with four custom headers. So the curl below is real, but you'll be computing a signature, not pasting an API key:

# Register the tenant's domain (Manage Domains API — Service Account auth)
curl -X POST "https://api.us.nylas.com/v3/admin/domains" \
  -H "Content-Type: application/json" \
  -H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
  -H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
  -H "X-Nylas-Nonce: <NONCE>" \
  -H "X-Nylas-Timestamp: 1742932766" \
  -d '{
    "name": "Acme tenant 4821 mail",
    "domain_address": "mail.tenant4821.example.com"
  }'

Then you fetch the DNS records to publish and trigger verification:

# Get the records to publish for a verification type (ownership, dkim, spf, feedback, mx)
curl -X POST "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>/info" \
  -H "Content-Type: application/json" \
  -H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
  -H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
  -H "X-Nylas-Nonce: <NONCE>" \
  -H "X-Nylas-Timestamp: 1742932766" \
  -d '{ "type": "dkim" }'

# After you add the records at your DNS provider, trigger the check for that type
curl -X POST "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>/verify" \
  -H "Content-Type: application/json" \
  -H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
  -H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
  -H "X-Nylas-Nonce: <NONCE>" \
  -H "X-Nylas-Timestamp: 1742932766" \
  -d '{ "type": "dkim" }'

Both /info and /verify take a required type in the body — one of ownership, mx, spf, dkim, or feedback — so you run the pair once per record type. For Agent Accounts you verify all five (ownership, dkim, spf, feedback, and mx); that mx record is the extra one Agent Accounts need beyond what Transactional Send requires. There is no CLI for this flow — domain registration and verification are Dashboard-or-API only, so the curl above (Service Account auth) is the programmatic path; I'm not inventing a nylas domain command because none exists. Configure the DNS records before the first /verify call to dodge DNS-caching delays. If verification fails with correct records, give it up to 24 hours (usually it's minutes, depending on TTL).

If you'd rather skip DNS entirely while you build the pipeline, you can provision the agent on a free *.nylas.email trial subdomain — but a real per-tenant domain is the point of this exercise, so I'll assume a custom one.

Step 2: Provision the tenant's Agent Account

With the domain verified, the grant is one call. Create it with POST /v3/connect/custom, provider: "nylas", and settings.email on the verified domain. No refresh token, no OAuth round-trip:

# Provision the tenant's agent — API
curl -X POST "https://api.us.nylas.com/v3/connect/custom" \
  -H "Authorization: Bearer <NYLAS_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "nylas",
    "name": "Acme Support Agent",
    "settings": {
      "email": "support@mail.tenant4821.example.com"
    }
  }'

The optional top-level name sets the agent's display name. The response carries the grant_id — that's your handle for everything downstream.

The CLI collapses this to one command. It always uses provider=nylas, auto-creates the Nylas connector the first time if it doesn't exist, and the API auto-creates a default workspace and policy for the account:

# Provision the tenant's agent — CLI
nylas agent account create support@mail.tenant4821.example.com \
  --name "Acme Support Agent"

I verified both --name (display name, 1–256 chars) and --app-password (an optional IMAP/SMTP app password) on nylas agent account create. There is deliberately no --workspace flag on create — the workspace and its policy come into existence automatically, and you attach a custom policy afterward. Which is exactly what step 3 is for.

Step 3: Cap the daily ramp with a policy

Here's the division of labor that matters: your application decides the warm-up schedule and which recipients to send to. Nylas enforces the ceiling. The ramp logic — how many to send today, spread across the day, to whom — lives in your code. But you can make Nylas backstop your ramp with a hard daily send cap, so a bug in your scheduler can't accidentally blast 1,000 emails on day one.

That cap is a policy field: limit_count_daily_email_sent. Create a policy with this week's number, then attach it to the agent's workspace.

# Create a policy that caps daily sends to week 1's number — API
curl -X POST "https://api.us.nylas.com/v3/policies" \
  -H "Authorization: Bearer <NYLAS_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warm-up week 1 — tenant 4821",
    "limits": {
      "limit_count_daily_email_sent": 15
    }
  }'

The CLI mirrors it. nylas agent policy create takes --name for a simple policy, or --data / --data-file for a full request body — and the limits live under a limits object, so you pass the JSON through --data:

# Create the capped policy — CLI
nylas agent policy create \
  --data '{"name":"Warm-up week 1 — tenant 4821","limits":{"limit_count_daily_email_sent":15}}'

Then attach the policy to the workspace the account was created in. Grab the workspace ID from nylas workspace list. On the API side this is a PATCH /v3/workspaces/{workspace_id} with the policy_id in the body:

# Attach the policy to the agent's workspace — API
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 is the same operation in one line:

# Attach the policy to the agent's workspace — CLI
nylas workspace update <WORKSPACE_ID> --policy-id <POLICY_ID>

I checked nylas workspace update: --policy-id attaches a policy, and passing --policy-id "" detaches it — which maps to setting policy_id to null in the API body (plan maximums apply when nothing's attached). At the end of each warm-up week you bump the policy's limit_count_daily_email_sent to the next tier and the ceiling rises with your ramp. The cap is a safety net, not the schedule — your app still has to pace the actual sends.

Raise the cap each week

When week 2 starts and your ramp climbs, update the same policy in place rather than creating a new one. The update is a PUT /v3/policies/{policy_id} — all fields are optional, so you send only the limit you're changing, nested under limits:

# Raise the daily send cap for week 2 — API
curl -X PUT "https://api.us.nylas.com/v3/policies/<POLICY_ID>" \
  -H "Authorization: Bearer <NYLAS_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "limits": {
      "limit_count_daily_email_sent": 75
    }
  }'

nylas agent policy update takes the policy ID and the same partial JSON body through --data:

# Raise the daily send cap for week 2 — CLI
nylas agent policy update <POLICY_ID> \
  --data '{"limits":{"limit_count_daily_email_sent":75}}'

Repeat at the start of week 3 (300) and week 4 (1000). Because the update is partial, you never have to re-send the rest of the policy — just the new ceiling.

Step 4: The warm-up ramp itself

This is the schedule, straight from the domain warm-up guide. It assumes a daily target of 500–1,000 emails during a typical 8-hour send window, ramped over roughly four weeks. Within each week, nudge the daily number up by 10–20% every day or so:

Week	Total emails per day	Emails per hour (approx.)	Notes
Week 1	5 – 15	1 – 2	Start very low, focus on highly engaged recipients
Week 2	30 – 75	4 – 10	Gradually increase, maintain a steady increase
Week 3	150 – 300	20 – 40	Moderate volume
Week 4	500 – 1,000+	60 – 125+	Full ramp-up to target volume

Three rules ride alongside the numbers, and they're as load-bearing as the volumes:

Spread sends across the day. Don't fire the whole day's batch at once. Distribute across business hours (say 9 AM–5 PM) with randomized delays between messages so the pattern looks human.
Send only to real, engaged recipients. This is the single biggest lever, especially in week 1. A reply is a very strong positive signal, a click is a strong one, an open is a mild one — and a spam-mark or a hard bounce hurts. For a brand-new tenant agent, that means seeding the warm-up with people who actually want the mail: the tenant's own team, beta users, internal stakeholders. Tell them to open, click, and reply.
Send transactional-style content. Booking confirmations, password resets, account notifications — the kind of mail with high trust and high open rates. No all-caps, no link-stuffing, no sales pitch during warm-up.

Because an Agent Account is a grant, the first warm-up send is the ordinary send call. Here's the API form to an engaged recipient:

# Send a warm-up message from the agent — API
curl -X POST "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
  -H "Authorization: Bearer <NYLAS_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{ "name": "Dana Okafor", "email": "dana@acmecustomer.com" }],
    "subject": "Your Acme account is ready",
    "body": "Hi Dana — your workspace is set up. Reply here any time and I will help you get started."
  }'

And the CLI equivalent. The first positional argument is the grant (you can pass the grant_id or the agent's email):

# Send a warm-up message from the agent — CLI
nylas email send <GRANT_ID> \
  --to dana@acmecustomer.com \
  --subject "Your Acme account is ready" \
  --body "Hi Dana — your workspace is set up. Reply here any time and I will help you get started."

One thing I confirmed while writing this: nylas email send has no attachment flag. If your warm-up content needs an attachment, you build it as a draft (nylas email drafts create --attach) or send via the API. For plain warm-up mail you won't miss it.

The scheduling — which N recipients today, the per-message jitter, the daily increase — is your app logic. The warm-up guide ships a Python script you can run daily from cron that handles the pacing for one day's target; adapt it to send through your agent's grant instead of the Transactional Send endpoint, and update the daily target each week to match the table above.

Step 5: Watch bounces and complaints so you can back off

You can't manage deliverability you can't see. While the ramp runs, the thing that tells you whether reputation is holding is the stream of deliverability webhooks Agent Accounts emit: message.delivered, message.bounced, message.complaint, and message.rejected. These are the same events Nylas uses to calculate your bounce and complaint rates — the rates that, if they climb too high, pause sending. Catching a dip in your own telemetry is what keeps you under those thresholds.

Webhooks are application-scoped, not grant-scoped — and that's a feature when you're running many tenants. You subscribe once at the app level, and events for every tenant's agent arrive at the same endpoint, each payload carrying a grant_id you filter on. So you don't re-subscribe per tenant; provision the subscription once and route by grant_id. Subscribe with POST /v3/webhooks:

# Subscribe to deliverability webhooks — API (app-scoped, once)
curl -X POST "https://api.us.nylas.com/v3/webhooks" \
  -H "Authorization: Bearer <NYLAS_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_types": [
      "message.delivered",
      "message.bounced",
      "message.complaint",
      "message.rejected"
    ],
    "webhook_url": "https://hooks.yourcompany.com/nylas/deliverability"
  }'

The CLI creates the same subscription with --url and --triggers (comma-separated, or repeated flags):

# Subscribe to deliverability webhooks — CLI
nylas webhook create \
  --url https://hooks.yourcompany.com/nylas/deliverability \
  --triggers message.delivered,message.bounced,message.complaint,message.rejected

Run nylas webhook triggers to list every available trigger type if you want to confirm the names yourself. Honest CLI note: the signal you act on — the bounce and complaint events themselves — arrives over the webhook stream and gets handled by your receiver, which is application code, not a CLI command. The CLI helps you set the subscription up and verify deliveries (nylas webhook verify checks a signature locally; nylas webhook server runs a local receiver for testing), but reacting to a complaint spike by lowering the ramp is logic you write.

Wire those events into your back-off rule: when bounces or complaints climb for a tenant's grant_id, slow or pause that tenant's ramp, and stop mailing any address that hard-bounces or complains. One quick implementation note since these matter in production — the API delivers at-least-once (up to three attempts per event), so dedupe on the top-level notification id, which stays constant across retries of the same event. The inner message id identifies the message; the notification id identifies the delivery.

Guardrails: DMARC and per-tenant isolation

Two things to get right before you scale this across tenants.

Publish DMARC, but roll it out in stages. DKIM and SPF are already verified, but DMARC is the layer you add. Publish a record at _dmarc.<your-sending-subdomain> starting at p=none so mail is delivered normally while providers send you aggregate reports — you confirm your agent's mail authenticates and aligns before you tighten anything. Once reports are clean, move to p=quarantine (you can ease in with pct=25), then finally p=reject. Give each stage a couple of weeks of clean reports. Because Agent Accounts sign with your domain's DKIM key and send from your verified domain, alignment works out of the box with relaxed alignment, which is the default they're set up for.

Reputation doesn't transfer between domains. If your model is one domain per tenant, you warm each domain on its own schedule. The reputation a freshly provisioned agent builds is tied to its domain — there's no shared head start across tenants. That's the cost of per-tenant domain isolation, and it's why the warm-up belongs in your provisioning pipeline rather than as a one-time thing you did for the first tenant and forgot about. Every new tenant on a new domain starts the four-week clock over.

What's next

Domain warm-up guide — the full ramp schedule, engagement signal table, and the daily send script
Email deliverability for Agent Accounts — DMARC staging, webhook monitoring, and SPF/DKIM alignment troubleshooting
Managing domains — register and verify a custom Agent Account domain
Agent Accounts overview — provisioning, policies, and the grant model
CLI command reference — every nylas agent, nylas workspace, and nylas webhook subcommand used above

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/agent-account-custom-domain-rollout-plan.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

GDPR retention and erasure for an agent mailbox

Qasim — Sat, 11 Jul 2026 12:27:47 +0000

Most "AI email" demos never think about deletion. The agent reads, replies, files things away, and the inbox just grows. That's fine in a demo. It is a problem the first time a real person emails your agent, because the moment that mailbox holds someone else's name, address, order history, or support complaint, you've taken on a data-protection obligation — and "we kept everything forever" is not a defensible retention policy.

An Agent Account on Nylas accumulates personal data you have to be able to purge. It's a mailbox the agent owns — support@yourcompany.com answering to a model instead of a human — and every inbound message lands in it. Under GDPR that data needs two things you can prove: a retention window so it doesn't live forever, and an erasure path so you can delete a specific person's mail when they ask. This post builds both, with the curl and the CLI for each step.

A quick, honest caveat before any of it: this is a docs-and-demo walkthrough, not legal advice. The Nylas primitives below cover the mail held in the mailbox. Any derived copy you made — rows in your own database, lines in your application logs, a vector store you embedded the message into — is yours to purge separately. The API can delete the message; it can't reach into your Postgres. Keep that in mind throughout.

What the platform gives you

Nothing new to learn on the data plane. An Agent Account is just a grant with a grant_id, so everything you already know about Messages and Threads applies directly — listing, reading, and deleting mail run against the same grant-scoped endpoints any other Nylas integration uses. Retention and erasure split cleanly into two layers:

Retention is a control-plane setting. It lives on a policy — an application-scoped resource that bundles limits and spam settings — attached to the workspace your Agent Account belongs to. Two fields cap how long mail survives: limit_inbox_retention_period and limit_spam_retention_period. Set them once and Nylas deletes aged-out mail for you, per account, with no cron job on your side.
Erasure is a data-plane operation. To honor a right-to-erasure request for one person, you find their messages with GET /v3/grants/{grant_id}/messages filtered by sender, then hard-delete each one with DELETE .../messages/{id}?hard_delete=true — a plain delete only trashes the message, which isn't erasure. For a full identity wipe, you delete the grant itself.

The split matters because the two answer different questions. Retention answers "how long do we keep anything?" — a blanket time bound. Erasure answers "delete this person's data, now" — a targeted request. A compliant agent mailbox needs both; one doesn't substitute for the other.

I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for. Where it matters I'll show the curl and the nylas ... form side by side, because in practice you set retention once through the API and run erasure ad hoc from a terminal when a request comes in.

Before you begin

You need an Agent Account, an API key for the same application, and the host set to https://api.us.nylas.com. Every API call below carries Authorization: Bearer <NYLAS_API_KEY>. If you don't have an account yet, you provision one against a registered domain — either the API:

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

or the CLI, which creates the nylas connector for you if it doesn't exist yet:

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

Either path returns a grant_id. The API also auto-creates a default workspace and a default policy for the account — that default workspace is where you'll attach the retention policy in a moment. Full background lives in the Agent Accounts docs and the Policies, Rules, and Lists guide. CLI reference is at cli.nylas.com/docs/commands.

One plan note up front: on the free plan, retention defaults to 30 days in the inbox and 7 days in spam, and those defaults aren't configurable. The two retention fields below are configurable on paid plans, where you set your own windows. So if you're prototyping on the free tier, you already have a 30-day inbox bound whether you ask for it or not — which is a reasonable default, but probably not the number your legal team picked.

Set retention windows on a policy

Retention is two fields inside a policy's limits object:

limit_inbox_retention_period — days a message stays in the inbox before Nylas deletes it.
limit_spam_retention_period — days a message stays in spam before deletion. This must be shorter than the inbox window, so spam clears out ahead of legitimate mail. If you set spam longer than inbox, the API rejects it.

Both take a number of days. Pick windows that match your documented retention schedule — the number you'd write down for an auditor, not a number you guessed. Here's a policy that keeps inbox mail for a year and spam for 30 days:

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 Retention Policy",
    "limits": {
      "limit_inbox_retention_period": 365,
      "limit_spam_retention_period": 30
    }
  }'

The CLI takes the same JSON body through --data, so the policy you describe is identical:

nylas agent policy create --data '{
  "name": "Support Agent Retention Policy",
  "limits": {
    "limit_inbox_retention_period": 365,
    "limit_spam_retention_period": 30
  }
}'

Both return a policy id. Hold onto it — a policy does nothing on its own. It only takes effect once a workspace points at it, and every Agent Account in that workspace inherits the windows. You attach it to the default workspace your account already landed in:

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>"
  }'

nylas workspace update <WORKSPACE_ID> --policy-id <POLICY_ID>

That's the entire retention story on the platform side. From here, Nylas enforces the windows itself — there's no scheduled job for you to write, monitor, or page on when it silently stops running at 3am. The part I like as an SRE is exactly that: retention isn't a script that can rot. It's a property of the account, declared once, enforced by the platform.

A workspace with no policy attached runs its accounts at your plan's maximum limits — which on a paid plan can mean no retention bound at all. So "we have an Agent Account" does not imply "we have a retention window." Attaching the policy is the step that makes the claim true. If you ever need to widen or tighten the window, PATCH the policy and every account in the workspace follows; on the default workspace, policy_id and rule_ids are the only fields you're allowed to change, which keeps this hard to get wrong.

Build the erasure path

Retention handles the passive case — mail aging out on a schedule. Erasure handles the active one: a named individual exercises their right to be forgotten and you have to remove their mail specifically, today, regardless of how old it is.

The shape is two steps. First, find every message from that person. Then delete each one. Both run against the grant, on the same Messages endpoints any Nylas app uses — there's nothing Agent-Account-specific here, which is the point.

Step 1 — find the subject's messages

Filter the message list by sender. The Messages API takes a from query parameter that matches the sender address, so a single call returns the candidate set:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages?from=jane.doe@example.com&limit=50" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

The CLI exposes the same filter as --from, and --id prints the message IDs you'll feed into the delete step:

nylas email list <NYLAS_GRANT_ID> --from jane.doe@example.com --id

A few honest things to watch for, because "find their messages" is deceptively simple. --from matches the sender, so this finds mail the subject sent to the agent. Mail the agent sent to the subject lives in the Sent folder with the agent as sender — pass --folder SENT (or list all folders) and filter on the recipient side if your erasure scope includes outbound copies. And one person can email from more than one address; if you only have a name, you may need to run the lookup for each known address. Don't assume a single from value captures everything tied to a person.

Step 2 — hard-delete each message

This is the step where the obvious call does the wrong thing, and it matters more here than anywhere else in the post. A plain DELETE on a message does not erase it — it moves the message to Trash. For a right-to-erasure request, trashed mail is still retained mail, and "we moved it to a folder" is not deletion. To actually remove a message, you pass ?hard_delete=true, which deletes it immediately instead of trashing it, and that operation is irreversible:

curl --request DELETE \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>?hard_delete=true" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

Two things gate that flag. First, hard_delete has to be enabled for your application — turn on Enable hard delete in the Nylas Dashboard under Customizations > API before the parameter does anything. Second, and this is the one to internalize: the CLI cannot hard-delete. nylas email delete only moves a message to Trash — there is no hard-delete flag on it. So for true erasure of an individual message, the API is your only path:

# CLI: trashes the message — does NOT permanently erase it
nylas email delete <MESSAGE_ID> <NYLAS_GRANT_ID>

That's fine for an inbox-cleanup workflow, but don't reach for it to satisfy an erasure request and assume the data is gone — it's sitting in Trash.

Threads have the same trap, with no escape hatch. Deleting a thread (DELETE /v3/grants/{grant_id}/threads/{thread_id}, or nylas email threads delete) moves the thread and all its messages to Trash. There is no hard_delete parameter on the thread endpoint at all — so thread deletion is a convenience for clearing a conversation out of view, not an erasure primitive. If a single back-and-forth carried the personal data across several replies, list the thread's messages and hard-delete each one individually; don't rely on the thread delete to erase them.

So the erasure loop is: list by sender, collect the message IDs, then DELETE .../messages/{id}?hard_delete=true on each, through the API. Keep an audit record of what you deleted and when — the message IDs and a timestamp — without storing the message content you just erased. A proof-of-erasure log that quietly retains the bodies defeats the entire exercise; log the fact of deletion, not the data.

Full erasure: delete the whole mailbox

Sometimes the subject is the agent identity. If the personal data tied to one person is the entire reason an Agent Account exists — a per-customer agent mailbox, say, that you spun up for a single client who's now offboarding — hard-deleting individual messages is the long way around, and it's also the one case where the CLI gives you a clean full wipe. Deleting the grant removes the whole mailbox: every message, thread, folder, and the connection itself. This is the only full-erasure path that doesn't depend on the hard_delete toggle, because it tears down the mailbox rather than emptying it message by message.

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

The CLI does this through the agent-account or auth commands — both revoke the same underlying grant:

nylas agent account delete support@yourcompany.com --yes

nylas auth revoke <NYLAS_GRANT_ID>

This is the nuclear option, and it's the right one for full erasure of an agent identity. It's also irreversible — the grant and its mailbox are gone, with no undelete. Reach for per-message hard-delete when you're scrubbing one person out of a shared agent mailbox, and grant deletion when the entire mailbox represents the person you're erasing.

Guardrails and honest limits

A few things the demo glosses over that a compliance review won't:

Custom metadata isn't available on Agent Accounts. On a normal grant you might tag messages with a subject ID in metadata to make erasure lookups trivial. That's not an option here — Agent Accounts don't support custom metadata — so your erasure index has to live in your system, keyed off the message IDs you already store. Plan for that when you design the handler.
Derived copies are your problem, not the API's. This is worth repeating because it's the most common gap. If your agent summarized a thread into your database, embedded a message into a vector store, or wrote the sender address into a log line, deleting the message from the mailbox leaves all of those untouched. Erasure is only complete when every copy is gone. Build the deletion of your derived data into the same handler that calls the Nylas DELETE.
Retention defaults aren't a policy you chose. The free-plan 30-day inbox / 7-day spam window is a default, not a decision. If you're on a paid plan and never attached a policy, your accounts run at plan maximums — potentially no bound at all. Don't mistake "it seems to clean up" for "we have a documented retention schedule." Attach the policy explicitly.
limit_spam_retention_period must be shorter than limit_inbox_retention_period. It's a hard constraint the API enforces. Set both, and set spam lower.
A plain delete is not erasure. This is the single most important thing to get right in this post. A bare DELETE on a message moves it to Trash; thread deletion trashes the whole conversation; the CLI's nylas email delete and nylas email threads delete only trash. None of those erase. Erasure requires either ?hard_delete=true on the message endpoint (API only, with the Dashboard toggle enabled) or deleting the grant. Treat "I deleted it" and "I erased it" as different claims, because the platform does.
Hard-delete and grant deletion are irreversible. Once you do erase — hard_delete=true on a message, or DELETE on the grant — there's no undelete and no Trash to recover from. Confirm the subject and the ID set before an erasure pass. That's exactly what you want for a right-to-erasure request, and exactly what you don't want to trigger by accident.

None of this is legal advice, and your retention windows and erasure SLAs should come from your own data-protection program, not from the example numbers above. What the platform gives you is the mechanism: a declarative retention bound that the platform enforces, and a deterministic deletion path you can run on demand. The policy layer matters most for compliance — it's the difference between intending to delete old data and proving the system does.

What's next

Policies, Rules, and Lists for the full limits object, including the storage cap and send quotas alongside the two retention fields
Email API security & compliance for scoped OAuth, signed webhooks, revocable grants, and the data-residency choice between the US and EU regions
Agent Accounts for provisioning, workspaces, and how the grant abstraction carries through every endpoint
Nylas CLI commands for the full nylas agent, nylas workspace, and nylas email command surface used throughout this post

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/data-retention-email-agent.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Keep your agent's mail out of spam traps

Qasim — Sat, 11 Jul 2026 12:27:32 +0000

Spam traps are the failure mode nobody puts in the demo. A bounce is loud — you get a 5.x.x back, your code logs it, you move on. A complaint at least gives you a webhook. A spam trap gives you nothing. The message gets accepted, no error comes back, and somewhere a mailbox provider quietly writes your domain down as a spammer. By the time you notice, your inbox placement has already cratered and you have no single bounce to point at.

That's the trap, literally. And it's the one that bites autonomous agents the hardest, because the whole appeal of an agent is that it acts without a human watching every send. Point a model at a list it scraped, let it loop, and it'll happily mail a recycled address that's been a trap for two years. The agent never sees a problem. You only see the aftermath in your deliverability dashboard a week later.

I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for when I'm wiring up an Agent Account to not do this. The good news is that an Agent Account is just a grant — a grant_id that works with every grant-scoped endpoint you already know — so there's nothing new to learn on the data plane. The defense is mostly discipline: validate before you send, honor every complaint, and age out the addresses that never wanted to hear from you.

What a spam trap actually is, and why it's not a bounce

It's worth being precise here, because the three things people lump together behave completely differently.

A bounce is a rejected delivery. The receiving server tells you the address is bad, you get a message.bounced event, and you stop. Bounce handling is a solved problem — you listen, you suppress, you're done.

A complaint is a recipient hitting "report spam." The mailbox provider relays that back as a feedback loop, and you get a message.complaint event. The address is real and reachable; the human just doesn't want your mail. If you keep mailing them, you're training the provider to filter you.

A spam trap is neither. It's an address with no human behind it, planted (or recycled) specifically to catch senders who don't manage their lists. There are two flavors:

Pristine traps — addresses that were never valid and never opted in. Published in places only a scraper would find. If you hit one, it means you're mailing addresses you harvested rather than addresses that gave you consent.
Recycled traps — addresses that were real, went dormant, bounced for months, and then got reactivated by the provider as a trap. If you hit one, it means you kept mailing an address long after it stopped engaging.

Here's the part that makes traps dangerous: they don't bounce. A pristine trap accepts your mail silently. A recycled trap accepts it too, now that it's live again. There is no Nylas "is this a spam trap" endpoint — there can't be, because the whole point of a trap is that it's indistinguishable from a real inbox until your reputation tanks. So the defense can't be a lookup. It has to be behavior: don't mail addresses you can't trust, and stop mailing addresses that have gone quiet.

That's the honest framing. Everything below is built on it.

What you actually get from Nylas

You don't get a trap detector. You get the two signals that let you build trap avoidance, plus the machinery to enforce a suppression list at the platform edge:

Deliverability webhooks — message.delivered, message.bounced, message.complaint, and message.rejected. These tell you what happened to every outbound message. Complaints and bounces are your strongest "stop mailing this person" signals.
Lists and Rules — application-scoped suppression. A List holds addresses; a Rule with an in_list condition blocks any outbound send to them; a workspace activates that rule across your Agent Accounts. Once an address is suppressed here, your agent physically cannot email it, even if its own logic slips.

The webhooks tell you who to suppress. The Lists and Rules make the suppression unbreakable. Your application code fills the gap Nylas can't — validating recipients before the first send, and aging out the ones who never engaged.

Let's wire all three.

Before you begin

You need an Agent Account on a registered domain and your API key. If you're starting cold, provision one. The grant it returns is your grant_id for everything after.

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

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

The API auto-creates a default workspace and policy for the account, which matters later: a suppression rule has to be activated on a workspace, and this is the one your new account already belongs to.

A reminder on message.rejected, because it's easy to misread. That event fires for one specific reason — an outbound message was rejected because an attachment contained a virus. It is not a generic "this send failed" signal and has nothing to do with traps. Subscribe to it for security telemetry, but don't wire it into your suppression logic.

Subscribe to the complaint and bounce webhooks

This is step one of trap defense, because a complaint or a hard bounce is the clearest evidence that an address should never receive another send. Subscribe once, at the application level — Nylas webhooks are app-scoped, not grant-scoped, so a single subscription covers every Agent Account you run. Each payload carries a grant_id you filter on.

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.complaint",
      "message.bounced",
      "message.rejected"
    ],
    "webhook_url": "https://yourapp.com/webhooks/deliverability",
    "description": "Agent Account deliverability signals"
  }'

Now the honest note you'd want from a colleague rather than a marketing page: you have to create this one through the API, not the CLI. The CLI can absolutely create webhooks — nylas webhook create --url <URL> --triggers <...> — and I use it constantly for message.created and friends:

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

But run nylas webhook triggers and you'll see the published trigger catalog doesn't list the deliverability events. The CLI validates --triggers against that catalog, so message.complaint won't go through the flag today. The POST /v3/webhooks body above accepts them directly. This is the one place in the whole flow where the CLI can't mirror the API, and I'd rather tell you that than have you debug a rejected flag.

When a complaint lands, your handler should do exactly one thing first: add that address to your suppression list. Don't wait for a daily batch — a person who reported you as spam must not receive a second message. Dedupe the webhook itself on the top-level notification id (constant across Nylas's up-to-three retry attempts) so a retried delivery doesn't double-process.

Build the suppression list and the rule that enforces it

A logged complaint that doesn't change behavior is just a sad log line. The enforcement lives in a List plus a Rule, activated on a workspace. This is the part that makes suppression structural rather than a hope that your send loop remembers to check.

First, the list — an address-typed collection. Seed it with the complaining or hard-bouncing addresses as they come in.

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

nylas agent list create \
  --name "Suppressed recipients" \
  --type address \
  --item complained@example.com

Add to it as complaints arrive — POST /v3/lists/<LIST_ID>/items with an items array, or the CLI's add:

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": ["complained@example.com"] }'

nylas agent list add <LIST_ID> complained@example.com

Next, the Rule. It's an outbound rule with one in_list condition against recipient.address, and a single terminal block action. An outbound block rejects the send before it ever reaches the provider — the API returns 403, and no message goes out.

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 suppressed recipients",
    "trigger": "outbound",
    "match": {
      "conditions": [
        { "field": "recipient.address", "operator": "in_list", "value": ["<LIST_ID>"] }
      ]
    },
    "actions": [ { "type": "block" } ]
  }'

The CLI condenses this into condition-and-action flags:

nylas agent rule create \
  --name "Block suppressed recipients" \
  --trigger outbound \
  --condition recipient.address,in_list,<LIST_ID> \
  --action block

One detail worth knowing: recipient.address matches any recipient on the message — To, CC, BCC, and the SMTP envelope. So a suppressed address hidden in a BCC still trips the block. That's exactly the DLP-grade coverage you want; an agent can't sneak a suppressed contact through on a carbon copy.

Activate the rule — it's inert until you do

This is the step people skip, and then wonder why their block rule does nothing. A rule does nothing until a workspace references it. Creating the rule through POST /v3/rules only defines it. You have to add its ID to a workspace's rule_ids array, and only then does it run for the Agent Accounts in that workspace.

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 '{ "rule_ids": ["<RULE_ID>"] }'

nylas workspace update <WORKSPACE_ID> --rules-ids <RULE_ID>

A nice shortcut from the CLI side: nylas agent rule create already attaches the rule it creates to the default workspace for you — that's what "create a rule and attach it to the default agent workspace" in its help text means. So if your accounts live in the default workspace, the CLI path collapses suppression-rule creation and activation into a single command. The explicit workspace update above is what you reach for when you built the rule through the API, or when you're attaching it to a custom workspace. Either way, the principle holds: an unattached rule is a no-op.

With this in place, every complaint your webhook catches flows into the list, and every send the agent attempts to a listed address dies at 403 before it can compound the damage. The platform is now enforcing a boundary your application code can't accidentally cross.

Validate recipients before the first send — this is your job

Here's where I have to be straight with you: everything past this point is your application logic. Nylas doesn't ship a "is this a spam trap" check, and no provider does, because traps are designed to be invisible. The suppression list above handles addresses you've learned are bad. Trap avoidance is about not mailing questionable addresses in the first place.

The single most important rule: never email a scraped, purchased, or old list. Pristine traps live exactly where a scraper would find them. If your agent's input is a list someone harvested, you will hit traps — it's not a question of if. The only addresses safe to mail are ones that asked to hear from you.

Before any first send, run cheap validation in your own code:

Syntax and domain checks. Reject malformed addresses, and confirm the domain has an MX record before you bother sending. A domain with no MX can't receive mail; sending anyway is wasted reputation.
Role and disposable filtering. Be wary of info@, admin@, postmaster@ style role addresses on lists you didn't build, and of known disposable-domain providers. Neither belongs in an agent's outreach.
Consent provenance. This is the one that actually matters. Track how each address entered your system — a form submission, an account signup, a reply to a real conversation. Addresses with no provenance trail are exactly the ones that turn out to be traps.

None of this is a Nylas feature, and I won't pretend it is. It's a validation layer you own, and it's the difference between an agent that builds reputation and one that quietly burns it.

Age out the addresses that never engage

Recycled traps are the slow killer. An address that was real goes dormant, you keep mailing it out of habit, and one day the provider flips it into a trap. The defense is to stop mailing addresses that have gone quiet — before they get recycled.

Use the deliverability webhooks as your engagement ledger. message.delivered confirms a send landed; the absence of any positive signal over time is your aging cue. In your own datastore, track last-engagement per recipient and apply a policy like:

No opens, clicks, or replies in 90 days? Move them to a re-engagement track — one carefully worded "are you still there?" send, not your normal cadence.
Still silent after that? Stop mailing them entirely and add them to the same suppression list you built above. A never-engaged address that you keep hitting is a recycled trap waiting to happen.

You can mine engagement signals from the grant-scoped Messages and Threads endpoints the Agent Account already exposes — GET /v3/grants/{grant_id}/messages to see what came back, nylas email list and nylas email read from the terminal when you're spot-checking a thread by hand. There's no special endpoint for this; it's the same data plane every grant has, which is rather the point of the Agent Account abstraction. You're not learning a new API to do reputation hygiene — you're using the one you already have, with discipline.

The shape of the whole defense

Put together, trap defense for an Agent Account is three loops that reinforce each other:

Inbound signal — subscribe to message.complaint and message.bounced (via the API, since the CLI trigger catalog omits them), and treat each as a hard "suppress now."
Structural enforcement — push every suppressed address into an address List, blocked by an outbound in_list Rule that's activated on the workspace. The agent physically can't reach a suppressed address, BCC included.
Behavioral hygiene — your own code validates provenance before the first send and ages out never-engaged contacts before they become recycled traps.

The first two are Nylas machinery you can stand up in an afternoon. The third is the part nobody can do for you, and it's the part that actually keeps you out of the traps — because a trap, by definition, won't tell you it's a trap. The only way to avoid one is to never have been the kind of sender that hits them.

What's next

Email deliverability for Agent Accounts — domain authentication, DMARC staging, and the full deliverability-webhook list
Policies, Rules, and Lists — the complete schema for Lists, the in_list operator, outbound block rules, and workspace activation
Agent Accounts overview — the grant model and how Agent Accounts reuse every grant-scoped endpoint
Nylas CLI command reference — nylas agent, nylas webhook, and nylas workspace in full

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-deliverability-api-for-agents.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Measure reply-rate analytics for your email agent

Qasim — Sat, 11 Jul 2026 04:59:55 +0000

Most "email analytics" demos reach straight for the open pixel. Drop a 1x1 transparent GIF in the body, watch the loads roll in, call it engagement. That worked in 2015. Today Apple's Mail Privacy Protection pre-fetches every image the instant a message hits the inbox, so a chunk of your "opens" are Apple's proxy warming a cache, not a human reading anything. Gmail proxies images too. Corporate gateways strip them. The number you get back is noise wearing a confidence interval.

There's a signal sitting right next to it that nobody can fake or block: did they reply? A reply is a human deciding your message was worth typing back to. It's lower-volume than an open and it's slower to arrive, but it's true. And if your sender is a Nylas Agent Account — a mailbox your agent owns, sends from, and receives into — reply rate is something you can actually compute, because every send and every inbound reply land in the same threaded data plane you already have read access to.

This post is the build. I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for, and I'll show the raw HTTP next to each so you can wire it into whatever language your agent runs in.

What you're actually measuring

Reply rate is one fraction:

reply rate = replied_threads / sent_threads   (per segment, per time window)

sent_threads is the count of distinct conversations your agent started in some window. replied_threads is how many of those got at least one inbound message back from a real recipient. Segment by campaign, by recipient cohort, by prompt version — whatever dimension you want to compare — and watch it move over time.

The mechanism that makes this computable is threading. When the agent sends, Nylas stamps the outbound message with a Message-ID and returns a thread_id. When the recipient replies, their client sets In-Reply-To and References pointing back at that Message-ID, Nylas stitches the reply into the same thread, and the inbound message.created webhook carries the same thread_id. So the entire correlation is: remember which thread_id you sent into, and when an inbound reply shows up on that thread, count it. No subject-line guessing, no header parsing by hand. The email threading doc goes deep on the header chain if you want it; for analytics you only need the thread_id.

One thing to get straight up front, because it shapes the whole design: Agent Accounts don't support custom message metadata. On a regular grant you might stuff a campaign key into the send and filter on it later. You can't here. The mapping from thread_id to "which campaign / which run / which segment" lives in your database. That's not a limitation so much as a clarification of where the line is — Nylas owns the email data plane, your app owns the analytics.

Why this beats open tracking

Opens are noisy and increasingly blocked. Apple MPP, image proxying, and gateway stripping inflate or suppress the count depending on the recipient's setup. You can't tell a real open from a proxy pre-fetch.
A reply is unforgeable intent. Nobody's mail client replies on their behalf. The signal is sparse but it means exactly what you think it means.
It's the right loop for an agent. An autonomous agent doesn't need a dashboard a human reads quarterly; it needs a number it can optimize against. Reply rate per prompt version tells the agent which copy actually works.
Nothing new on the data plane. An Agent Account is just a grant with a grant_id. Sends, threads, messages, webhooks — all the same grant-scoped endpoints you'd use for any mailbox. The agent abstraction adds zero new API surface to learn.

Honest tradeoff, stated plainly: reply rate is a truer signal but a lower-volume one. On cold outreach you might see single-digit reply percentages where opens read 40%. If you need a high-frequency proxy for "message got displayed," opens still have a (degraded) place. If you need to know whether your agent's email is actually working, reply rate is the metric that won't lie to you. You can run both — they answer different questions.

Before you begin

You need an Agent Account to send from. It's provisioned in two equivalent ways.

The API call is POST /v3/connect/custom with provider: nylas and a settings.email on a domain you've registered (a real custom domain, or a *.nylas.email trial subdomain):

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",
    "settings": { "email": "agent@yourcompany.com" },
    "name": "Outbound Agent"
  }'

The CLI does the same in one line:

nylas agent account create agent@yourcompany.com --name "Outbound Agent"

Either way you get back a grant_id. No OAuth dance, no refresh token — the agent owns the mailbox outright. Hold onto that grant_id; it's the identifier in every endpoint below. The Agent Accounts docs cover domain warm-up and the free-plan limits (200 messages per account per day, worth knowing before you batch a campaign).

You'll also want a small table in your own store. The schema is boring on purpose:

-- one row per agent send
CREATE TABLE agent_sends (
  thread_id    TEXT PRIMARY KEY,   -- returned by the send call
  message_id   TEXT NOT NULL,
  segment      TEXT NOT NULL,      -- "q2-trial-nudge", "prompt-v3", etc.
  sent_at      TIMESTAMPTZ NOT NULL,
  replied_at   TIMESTAMPTZ         -- NULL until a reply lands
);

-- dedup ledger so we never double-count a webhook
CREATE TABLE seen_notifications (
  notification_id TEXT PRIMARY KEY
);

That's the entire persistence layer. Everything else is reads against Nylas.

Send, and record the thread

When the agent sends, capture the thread_id off the response and write a row. The send endpoint is POST /v3/grants/{grant_id}/messages/send:

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 on your trial",
    "body": "Hi there — checking in on how the trial is going."
  }'

The response carries id (the message id) and thread_id. That thread_id is the key you store against your segment:

INSERT INTO agent_sends (thread_id, message_id, segment, sent_at)
VALUES ('<thread_id>', '<message_id>', 'q2-trial-nudge', now());

The CLI equivalent, with --json so you can pipe the response into your recorder:

nylas email send agent@yourcompany.com \
  --to prospect@example.com \
  --subject "Following up on your trial" \
  --body "Hi there — checking in on how the trial is going." \
  --json

Pass the account as the first positional grant-id argument (the email resolves to the grant). The --json output includes the same thread_id; grab it with jq and run your insert. If the agent is replying into an existing thread rather than starting one, use --reply-to <message-id> (or reply_to_message_id in the API body) — Nylas sets the threading headers so the reply lands on the original thread, and your thread_id mapping is already correct.

The rule: record on every send, no exceptions. A send you forgot to log is a thread that can never count as sent, which silently deflates your denominator and inflates your rate. Tag every send, even ones you don't think you'll measure.

Subscribe to inbound replies

Inbound mail fires the standard message.created webhook. One important fact about Nylas webhooks: they're application-scoped, not grant-scoped. You subscribe once at the app level, and events for every grant in the app arrive at that one endpoint, each payload carrying the grant_id it belongs to. You don't create a webhook per Agent Account.

The subscription is POST /v3/webhooks:

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://your-app.example.com/nylas/inbound",
    "description": "Reply-rate inbound signal"
  }'

Or from the CLI:

nylas webhook create \
  --url https://your-app.example.com/nylas/inbound \
  --triggers message.created \
  --description "Reply-rate inbound signal"

While building, you don't need a public URL at all — nylas webhook server --tunnel cloudflared --secret <WEBHOOK_SECRET> stands up a local receiver behind a tunnel and prints each event as it arrives, which is how I test the handler before deploying it. The --secret is required whenever --tunnel is set, since the server verifies each event's signature; pass --no-tunnel instead if you just want a loopback-only receiver for local dev. Nylas signs every webhook with an X-Nylas-Signature header (hex HMAC-SHA256 of the raw body using your webhook secret); verify it in production, and nylas webhook verify checks a signature locally if you want to sanity-check your comparison logic.

Correlate: match each inbound reply to a sent thread

Here's the loop the whole post builds toward. For each message.created event:

Dedup on the notification id. Nylas guarantees at-least-once delivery — the same event can arrive up to three times. The top-level notification id is constant across all retries of one event, so it's your dedup key. If you've seen it, drop the event.
Filter out the agent's own sends. message.created fires for outbound messages too. You only care about real replies, so skip any message whose from is the agent's own address.
Match thread_id against your agent_sends table. If the inbound reply's thread_id is one the agent sent into, that thread just earned a reply.

import os, hmac, hashlib

def handle_message_created(raw_body: bytes, signature: str, db):
    # Signature check: HMAC-SHA256 of the raw body. Guard equal length
    # before constant-time compare — timingSafeEqual-style compares throw
    # on a length mismatch.
    expected = hmac.new(
        os.environ["NYLAS_WEBHOOK_SECRET"].encode(),
        raw_body, hashlib.sha256,
    ).hexdigest()
    if len(expected) != len(signature) or not hmac.compare_digest(expected, signature):
        return 401

    event = json.loads(raw_body)

    # 1. Dedup on the top-level notification id (constant across retries)
    notif_id = event["id"]
    if db.already_seen(notif_id):
        return 200
    db.mark_seen(notif_id)

    obj = event["data"]["object"]

    # 2. Real replies only — skip the agent's own outbound sends
    agent_addr = "agent@yourcompany.com"
    senders = [p.get("email", "").lower() for p in obj.get("from", [])]
    if agent_addr in senders:
        return 200

    # 3. Match the reply's thread to a recorded send
    thread_id = obj["thread_id"]
    send = db.find_send_by_thread(thread_id)
    if send and send["replied_at"] is None:
        db.mark_replied(thread_id, when=obj["date"])  # first reply wins

    return 200

A note on the payload body. The Nylas docs aren't fully consistent on whether message.created ships the full body inline, so use the safe framing: don't rely on the webhook payload for the body — fetch the full message by id when you need it, and branch on message.created.truncated. For reply-rate counting you usually don't need the body at all (the thread_id, from, and date on the summary are enough), but if you want the reply text to feed back into the agent, fetch it:

# Full message by id
curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/<MESSAGE_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

nylas email read <message-id> agent@yourcompany.com

When the event arrives as message.created.truncated (the payload exceeded ~1 MB), the body isn't inline and the fetch-by-id above is mandatory rather than optional. Branch on the trigger type and re-fetch.

If you'd rather reconstruct the whole conversation — say, to confirm the reply really is a back-and-forth and not an auto-responder — read the thread instead of the single message:

# Full thread by id
curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<GRANT_ID>/threads/<THREAD_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

nylas email threads show <thread-id> agent@yourcompany.com

The thread object gives you message_ids, participants, and both latest_message_received_date and latest_message_sent_date — handy as a cross-check that a received message genuinely arrived after your send.

Aggregate the rate yourself

The counting is done in your database, not in Nylas. There's no Nylas endpoint that returns "reply rate for campaign X" — and there shouldn't be, because the segmentation is your domain logic. With the two tables above, the rate per segment is a single query:

SELECT
  segment,
  count(*)                              AS sent_threads,
  count(replied_at)                     AS replied_threads,
  round(100.0 * count(replied_at) / count(*), 1) AS reply_rate_pct
FROM agent_sends
WHERE sent_at >= now() - interval '30 days'
GROUP BY segment
ORDER BY reply_rate_pct DESC;

Bucket by date_trunc('week', sent_at) instead of one window and you've got the trend line. Because replies trickle in over days, give each cohort time to mature before you trust its rate — a campaign sent yesterday will look worse than it really is until its replies land. I anchor every cohort to its sent_at rather than the wall clock for exactly that reason. The message timestamp on each event (obj["date"], also what date -u formats if you're stamping your own records) keeps sent and replied on the same clock.

That's the full loop: send and record the thread_id, receive message.created and dedup on the notification id, filter the agent's own sends, match the reply's thread, and divide replied by sent per segment. Threading is what makes a reply attributable to a specific send, and attribution is what turns "we got some replies" into a per-campaign rate the agent can steer on.

Guardrails and gotchas

Don't double-count multi-reply threads. A prospect might reply twice. The replied_at IS NULL guard means the first reply flips the thread to "replied" and later ones are ignored — exactly what you want, since the unit is threads that got a reply, not reply messages.
Auto-responders look like replies. An out-of-office bounce arrives as a real inbound message.created. If your reply rate suddenly spikes on a cold list, sample the threads — you may be counting vacation autoresponders. Filtering those is heuristic (subject patterns, known sender domains); decide whether they count for your use case.
Webhooks are at-least-once, so the dedup ledger isn't optional. Without it, three delivery attempts of one reply count as one reply (because replied_at only flips once) but still cost you three handler runs and three signature checks. Dedup on the notification id first, before any work.
The denominator is the fragile part. Reply rate breaks far more often from undercounted sends than from miscounted replies. Make the send-recording write part of the same code path as the send itself, not a follow-up job that can fail independently.
Reconcile against threads periodically. Webhooks can be missed during an extended grant outage. A nightly pass that lists recent threads for the grant and checks latest_message_received_date against your agent_sends rows catches anything the live path dropped.

What's next

Track email reply rates for AI agents — the cookbook recipe this post is built on, including the polling-vs-webhook tradeoff table
Email threading for agents — the header chain behind thread_id and why it beats subject matching
Agent Accounts — provisioning, supported endpoints, and plan limits
Nylas CLI command reference — every nylas email, nylas webhook, and nylas agent subcommand used above

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-reply-rate-tracking-agent.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

A/B test email subject lines with an agent — no ESP required

Qasim — Sat, 11 Jul 2026 04:59:21 +0000

Subject-line A/B testing is the kind of thing you usually rent. You sign up for an ESP, drop your contacts into their list, pick "split test" from a dropdown, and let their black box decide a winner — on their definition of "winner," with their attribution, on their schedule. That's fine if email is your whole product. It's a lot of ceremony if you have an agent that already sends mail and you just want to know which of two subjects gets more humans to reply.

Here's the pivot: the experiment is just two sends and a counter. If your agent owns a mailbox, it can run the split itself — pick a variant per recipient, send from its own address, watch replies land back in its own threads, and tally the result. No ESP, no list import, no separate analytics product. The whole thing lives inside the same mailbox the agent already uses.

I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for, and I'll show the matching HTTP call for each one so you can wire it into whatever your agent is actually built on. The data plane is the same either way.

What you actually get

An Agent Account is a real, sending-and-receiving mailbox that your code owns outright — no human, no OAuth handshake, no token to refresh. Under the hood it's just a Nylas grant with a grant_id, which is the important part: every grant-scoped endpoint you already know (Messages, Threads, Folders, Webhooks) works against it unchanged. There's nothing new to learn on the data plane. You send with POST /v3/grants/{grant_id}/messages/send, you read threads with GET /v3/grants/{grant_id}/threads/{thread_id}, and replies arrive as message.created webhooks. That's the entire surface area this experiment needs.

What Nylas does not do is run the experiment for you. There's no "split test" endpoint, no built-in significance math, no variant tracking. And that's correct — an experiment is your business logic, not the mail provider's. Nylas moves the email and reports the events; the random assignment, the sample-size discipline, and the winner call all live in your app. I'll be honest about that line throughout, because the parts you own are the parts that make the result trustworthy.

Why this beats reaching for an ESP

No data export. Your recipients, your sends, your replies all stay in your system. You're not syncing a contact list into a third party just to test two strings.
Reply rate, not open rate. Most ESP split tests optimize opens or clicks. With an agent mailbox you can attribute on replies — a human typed something back — which is a far stronger signal for outreach, support, or sales follow-ups.
One code path, every provider. A reply from Gmail, Outlook, Yahoo, or an IMAP mailbox lands as the same message.created event on the same thread shape. You write the attribution once.
The math is yours, so you can trust it. You control the split, the minimum sample, and when you're allowed to declare a winner. No vendor deciding "statistical significance" behind a curtain.

The tradeoff: you're writing the experiment harness yourself. If you only ever test subject lines for newsletter blasts and never look at replies, a marketing ESP is genuinely the better tool. This is for the case where an agent is the sender and replies are the outcome you care about.

Before you begin

You'll need a Nylas project and API key, plus one Agent Account to send from. If you've never set one up, the Agent Accounts quickstart walks the whole flow; the supported-endpoints reference lists exactly what a grant can do.

Provision the mailbox. The API auto-creates a default workspace and policy, so a single call is enough:

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": "Outreach Bot",
    "settings": { "email": "outreach@yourcompany.com" }
  }'

Same thing from the CLI:

nylas agent account create outreach@yourcompany.com --name "Outreach Bot"

The email has to live on a domain you've registered with Nylas (a custom domain, or a *.nylas.email trial subdomain). Both calls return a grant_id — that's the handle every command below uses. One caveat worth front-loading: a brand-new sending domain warms over roughly four weeks, so don't read a low reply rate in week one as a verdict on your subject line. It might just be your domain reputation.

A note on what's not available, because it shapes the design: Agent Accounts don't support custom metadata or templates. You can't tag a send with key1: variant_a and filter on it later, and you can't render a Nylas-hosted template. Both are fine — they just mean the variant mapping lives in your database, and if a subject's matching body needs HTML, you render it yourself and pass it in the body field. The mailbox stays dumb; your app stays smart.

Step 1: assign a variant per recipient

This is your code, not Nylas's. For each recipient, flip a fair coin and record the assignment before you send. Keeping it deterministic and stored up front is what makes the experiment honest — you decide the split in advance, not after you've peeked at results.

import secrets

SUBJECTS = {
    "A": "Quick question about your trial",
    "B": "Are you stuck on anything?",
}

def assign_variant() -> str:
    # secrets gives a fair, unbiased coin — don't use a time-seeded PRNG here
    return "A" if secrets.randbelow(2) == 0 else "B"

A 50/50 split keeps the two cohorts the same size, which keeps the later comparison simple. The point of randomizing per recipient rather than splitting your list down the middle is to avoid accidentally correlating a variant with some property of the list order — newest signups, say, or a particular acquisition source.

Write the assignment to your own store keyed by recipient. You'll fill in the thread_id in the next step once the send returns it:

-- your DB, your schema
INSERT INTO experiment_sends (recipient, variant, thread_id, replied)
VALUES ('prospect@example.com', 'A', NULL, false);

Step 2: send each variant from the agent mailbox

Now send. The subject comes from the variant; everything else is identical so you're testing the one thing you mean to test. If you omit the from field, Nylas defaults it to the Agent Account's own address — exactly what you want here.

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 '{
    "to": [{ "email": "prospect@example.com" }],
    "subject": "Quick question about your trial",
    "body": "Hi there — checking in to see how the trial is going."
  }'

The CLI equivalent, which is the one I actually run when I'm poking at this by hand:

nylas email send <NYLAS_GRANT_ID> \
  --to prospect@example.com \
  --subject "Quick question about your trial" \
  --body "Hi there — checking in to see how the trial is going."

The send response carries a thread_id. Record it against the variant you assigned. This is the load-bearing line of the whole experiment: the thread_id is how a future reply gets credited back to variant A or B. There's no metadata tag doing this for you — the link lives only in your DB.

UPDATE experiment_sends
SET thread_id = 'thread_abc123'
WHERE recipient = 'prospect@example.com';

If your body is HTML, render it yourself and pass the markup straight into body — remember, templates aren't supported on Agent Accounts, so there's no server-side rendering step. One subject string, one matching body, one recorded thread, per recipient. Loop that across your list and the experiment is live.

Step 3: attribute replies back to the winning variant

Replies come in as the standard message.created webhook. Webhooks are application-scoped, not grant-scoped, so you subscribe once at the app level and every grant's events arrive at the same endpoint, each payload carrying a grant_id you filter on.

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://your-app.example.com/nylas/replies",
    "description": "Subject-line experiment reply attribution"
  }'

From the CLI:

nylas webhook create \
  --url https://your-app.example.com/nylas/replies \
  --triggers message.created \
  --description "Subject-line experiment reply attribution"

When the webhook fires, the attribution logic is short but has three guards you can't skip:

Dedupe on the notification id. Nylas guarantees at-least-once delivery — the same event can arrive up to three times. The top-level notification id is constant across all retries of one event, so that's your dedup key. If you've seen it, drop it.
Ignore the agent's own sends. message.created also fires when your agent sends mail. Check the from address: if it's the Agent Account itself, it's not a reply, skip it. Only an inbound message from someone else counts.
Match the thread_id to your DB. Pull thread_id from the event, look it up in experiment_sends, and credit that row's variant. A reply to a thread you don't have on file isn't part of the experiment.

def handle_webhook(notification):
    if seen_before(notification["id"]):          # guard 1: dedup on notification id
        return

    msg = notification["data"]["object"]
    sender = msg["from"][0]["email"]
    if sender == AGENT_EMAIL:                     # guard 2: skip the agent's own sends
        return

    thread_id = msg["thread_id"]
    row = db.lookup_send(thread_id)               # guard 3: match to a tracked send
    if row and not row.replied:
        db.mark_replied(thread_id)                # credit row.variant with a reply

One thing the brief is right to flag: don't trust the webhook payload for the message body. The docs disagree on whether the body is inline — the agent-accounts guide says fetch it, the general webhook doc says it's inline unless the message exceeds ~1 MB. They agree on the action, so do that: when you need the actual reply text, fetch the full message with GET /v3/grants/{grant_id}/messages/{message_id}, and branch on the message.created.truncated trigger name for the oversized case. For pure reply attribution you don't even need the body — the thread_id and from are enough.

If you'd rather verify a thread by hand while debugging, the CLI reads it directly:

nylas email threads show <thread-id> <NYLAS_GRANT_ID>

A webhook is the live path, but keep a periodic reconciliation poll too — list recent threads and re-check any tracked send that hasn't been marked replied. The same poll covers you if a grant is offline long enough to miss events. (You'll want a real send timestamp for windowing that poll; date at the shell is fine for the lower bound while you're testing locally.)

Step 4: call the winner — honestly

Here's where most home-grown A/B tests go wrong, so this is the part to slow down on. Reply rate is a low-volume signal. If variant A is 3 replies out of 40 and variant B is 5 out of 40, that gap is almost certainly noise. Two or three replies either way will flip it. Declaring a winner there is worse than not testing at all, because you'll act on a result that isn't real.

A few rules I'd hold yourself to, all of which are your app's job, not Nylas's:

Set a minimum sample per variant before you start, and don't look until you hit it. Peeking at results and stopping the moment one variant pulls ahead is the classic way to manufacture a fake winner. Pick the number first, then run to it.
For reply rates in the single-digit-percent range, "enough" is bigger than you think — typically hundreds of sends per variant, not dozens, before a few points of difference means anything.
Run a real significance test on the two proportions (a two-proportion z-test or a chi-square is plenty) rather than eyeballing the percentages. If you're not comfortable picking a test, the safe default is: bigger sample, larger observed gap, more skepticism.

# your stats — Nylas has no opinion on significance
a_rate = a_replies / a_sent
b_rate = b_replies / b_sent
winner = "A" if a_rate > b_rate else "B"
# but only report it once both a_sent and b_sent clear your pre-set minimum,
# and only if a significance test on the two proportions clears your threshold.

The discipline is the product here. Nylas delivers the inbound reply events carrying a thread_id, at least once per event — so your app does the dedup on the notification id and your app matches each thread_id back to its variant; Nylas neither dedupes nor attributes for you. Whether you turn those attributed replies into a trustworthy decision is then entirely about the sample-size and significance rules you enforce before peeking.

Guardrails worth knowing

Free-plan send cap: 200 messages per account per day. A subject test that needs hundreds of sends per variant may take several days to fill — that's fine, just account for it in your "don't peek early" window.
Domain warm-up: the ~4-week reputation ramp on a new domain can depress replies independently of your subject. Don't start the experiment that matters on a cold domain.
Inbound retention: the free plan keeps inbox mail for 30 days. Reconcile and persist your reply tallies before that window closes if you're running a long test.
Variant mapping is yours to protect. Since there's no metadata tag, a lost or corrupted thread_id mapping means an un-attributable reply. Treat the experiment_sends table as the source of truth and write the thread_id in the same transaction as the send.

What's next

Track email reply rates for AI agents — the general reply-rate signal this experiment is a special case of
Supported endpoints for Agent Accounts — the full grant-scoped surface, including what isn't available yet
Agent Accounts overview — what an agent mailbox is and how the grant model fits together
Nylas CLI command reference — every nylas command used above, with flags

Two subjects, a fair coin, and a thread you already own. That's a real subject-line experiment — no ESP, no list import, no black box deciding the winner for you. The only thing standing between you and a trustworthy result is the sample-size discipline, and that part was always going to be your job.

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-reply-rate-tracking-agent.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Run a shared team inbox owned by an AI agent

Qasim — Fri, 10 Jul 2026 11:56:20 +0000

A shared inbox where the agent drafts and humans approve from Outlook is a powerful hybrid — and it's the part of "AI email" that most demos quietly skip.

Most "AI email" demos point a model at a human's personal inbox: connect a Gmail grant, summarize threads, maybe auto-draft a reply that nobody actually trusts enough to send. That's fine for a personal assistant. It falls apart the moment you want the agent to be a participant on a real team mailbox — support@yourcompany.com — where five humans and one agent all need to see the same messages, the same folders, and the same draft sitting in the queue.

The naive fix is to give the agent its own service and bolt a UI on top. Now you're building a mail client. You've got a database of "agent state," a sync loop, a permissions layer, and a frontend nobody asked for, all to reimplement what Outlook already does well.

There's a better shape. A Nylas Agent Account is a real mailbox you can drive two ways at once: the agent works it over the API, and your humans work it from their normal mail client over IMAP/SMTP. Both surfaces read and write the same storage. A draft the agent creates via the API shows up in the Drafts folder in Apple Mail. A message a human drags into "Needs review" in Outlook shows up in the API's folders field within seconds. That bidirectional sync is the whole trick, and it's what makes genuine human+agent collaboration possible instead of two systems fighting over one inbox.

I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for when I'm wiring this up. Every step shows the raw curl call and the nylas equivalent, because you'll want the API in your service and the CLI on your laptop.

What you actually get

An Agent Account is just a grant — the same grant_id abstraction you already use for every other Nylas mailbox. Nothing new to learn on the data plane:

Agent side (API): Messages, Drafts, Folders, Threads, Attachments, Webhooks — every grant-scoped endpoint works exactly as it does for a Gmail or Microsoft grant.
Human side (IMAP/SMTP): Outlook, Apple Mail, Thunderbird connect with the account email and an app password. People work the mailbox the way they always have.
Shared state: flags, folder moves, drafts, and sends propagate across both surfaces and fire the same webhooks, no matter which side initiated them.

The model is: the agent triages and drafts, a human reviews and approves from the comfort of their mail client, and the queue between them is just a folder both sides can see.

Why this beats building your own review UI

You don't write a mail client. Outlook is the review UI. Humans approve drafts where they already live.
The agent doesn't poll a side-channel. It gets message.created webhooks for inbound mail and reads/writes the real mailbox.
There's one source of truth. No reconciliation between "agent's view" and "human's view" — it's literally one mailbox.
It degrades gracefully. If your agent service is down, the humans still have a fully working mailbox. If a human is on vacation, the agent still triages.

One honest caveat up front, because it matters for how you scope this: this is not a multi-user ACL system. There's one app password for the mailbox, and everyone who connects a client shares it. You can't grant Alice read-only and Bob send. If you need per-person permissions, that lives in your application layer in front of the API, not in the shared inbox. I'll come back to the security tradeoff at the end.

Before you begin

You need:

A Nylas application and API key.
A registered sending domain — either your own custom domain or a Nylas *.nylas.email trial subdomain. New domains warm over roughly four weeks, so don't provision one the morning of a launch.
An email address on that domain for the inbox, e.g. support@yourcompany.com.

The API base host in these examples is https://api.us.nylas.com (use the EU host if your app is in the EU region), and every request authenticates with Authorization: Bearer <NYLAS_API_KEY>.

If this is your first Agent Account, read the Agent Accounts quickstart first. The walkthrough below assumes you've at least skimmed it.

Provision the shared mailbox

An Agent Account is created with POST /v3/connect/custom, "provider": "nylas", and the email on your registered domain. No OAuth, no refresh token — it's a Nylas-hosted mailbox. The optional top-level name sets the display name humans see in the From field.

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

Notice I'm setting app_password right in the create call. That's the credential your humans use to connect their mail clients (more on it next). The CLI does the same thing in one line:

nylas agent account create support@yourcompany.com \
  --name "Support Team" \
  --app-password "Sh4redInb0xReview2024!"

The response gives you a grant_id. That's the only identifier the agent side needs from here on.

Workspaces, briefly. When you create the account, the API auto-creates a default workspace and policy for it. If you run several agent inboxes — say a sales-outreach group and a support-triage group with different send limits — you can drop this account into a specific workspace at creation by passing a workspace_id in the POST /v3/connect/custom body. The CLI create command has no --workspace flag; to attach a custom policy after the fact you use nylas workspace update <workspace-id> --policy-id <policy-id>. For a single shared inbox the default workspace is fine — you can ignore this entirely.

Set the app password so humans can connect

The app password is what turns an API-only mailbox into a human+agent one. Until you set it, Nylas rejects every IMAP LOGIN and SMTP AUTH attempt. I set it at creation above, but you can also set or rotate it on an existing account.

Over the API, a PATCH to the grant replaces the whole settings object, so send the email alongside the new password:

curl --request PATCH \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "settings": {
      "email": "support@yourcompany.com",
      "app_password": "Sh4redInb0xReview2024!"
    }
  }'

The CLI has a dedicated command for it:

nylas agent account update support@yourcompany.com \
  --app-password "Sh4redInb0xReview2024!"

The password must be 18–40 characters, printable ASCII, with at least one uppercase, one lowercase, and one digit. Nylas stores it as a bcrypt hash — you can't read it back, only reset it. Rotating it disconnects any live mail client, and each one reconnects after the user types the new value.

Now hand your team these connection settings. They're exact, straight from the Nylas mail-client docs:

Setting	Value
IMAP server	`mail.us.nylas.email` (US) · `mail.eu.nylas.email` (EU)
IMAP port	`993` (implicit TLS)
SMTP server	`mail.us.nylas.email` (US) · `mail.eu.nylas.email` (EU)
SMTP port	`465` (implicit TLS) or `587` (STARTTLS)
Username	The account email, e.g. `support@yourcompany.com`
Password	The app password you just set

Most clients auto-detect TLS. If yours asks, pick SSL/TLS for 993 and 465, STARTTLS for 587. With IMAP IDLE, clients see new mail pushed in without polling — so when the agent moves a message, the human's Outlook updates on its own.

The key insight: one mailbox, two surfaces

This is the part worth internalizing, because everything else builds on it. IMAP and the API are not two copies that sync — they're two doors into the same room. Every user-visible action flows through the same storage and fires the same webhook, regardless of which door it came through:

The agent marks a message read via the API → the human's client sees it as read.
A human stars a message in Apple Mail → the API's starred field flips to true and a message.updated webhook fires.
A human drags a message to a folder in Outlook → the API's folders array updates.
The agent creates a draft via the API → it appears in the Drafts folder in every connected client.

Propagation is seconds, not minutes. That tight loop is exactly what you need for "agent drafts, human approves" to feel like one workflow instead of two disconnected ones.

Build the review queue out of folders

The cleanest way to coordinate agent and humans is a shared work queue, and the simplest queue is a folder. Create a "Needs review" folder once; both sides can see it.

Over the API:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Needs review" }'

Or from the terminal:

nylas email folders create "Needs review" <NYLAS_GRANT_ID>

Both return the folder's ID. Stash it — the agent needs it to route messages, and it shows up as a mailbox in everyone's mail client automatically.

When inbound mail arrives, the agent decides what it can't handle alone and moves those messages into the queue. A message's folder membership lives in its folders array, so you update the message with PUT /v3/grants/{grant_id}/messages/{message_id}:

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "folders": ["<NEEDS_REVIEW_FOLDER_ID>"] }'

From the CLI it's one command:

nylas email move <MESSAGE_ID> --folder <NEEDS_REVIEW_FOLDER_ID> <NYLAS_GRANT_ID>

The instant that runs, the message disappears from INBOX and shows up under "Needs review" in your team's Outlook. The folder is the handoff.

The agent drafts; a human sends

Here's the core workflow. The agent never sends on its own — it writes a draft and leaves it for a human. Drafting is a first-class endpoint: POST /v3/grants/{grant_id}/drafts.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "to": [{ "email": "customer@example.com" }],
    "subject": "Re: Trouble resetting my password",
    "body": "Hi there — I can see your account is locked after several failed attempts. I have unlocked it; you should be able to reset now. Let me know if it sticks."
  }'

The CLI version, the one I use when I'm testing a prompt by hand:

nylas email drafts create <NYLAS_GRANT_ID> \
  --to customer@example.com \
  --subject "Re: Trouble resetting my password" \
  --body "Hi there — I can see your account is locked after several failed attempts. I have unlocked it; you should be able to reset now. Let me know if it sticks."

That draft now sits in the Drafts folder. Because IMAP and the API share state, your reviewer opens Outlook, sees the agent's draft, edits a sentence if they want, and hits send — entirely inside their mail client. No bespoke approval UI, no extra service. The human's mail client is the approval step.

If you'd rather the agent send on approval — say a reviewer clicks "approve" in your own tool and your backend sends the agent's draft — you send the draft by ID with POST /v3/grants/{grant_id}/drafts/{draft_id} (the send-draft endpoint), or from the CLI:

nylas email drafts send <DRAFT_ID> <NYLAS_GRANT_ID>

Both paths are valid; pick based on where you want the human's "yes" to live. For replies that need to stay threaded, the CLI has a shortcut that fetches the original to preserve the subject and threading headers:

nylas email reply <MESSAGE_ID> --body "Thanks for the patience — all set now." <NYLAS_GRANT_ID>

Read what came in

The agent reads the mailbox like any grant. List recent messages with GET /v3/grants/{grant_id}/messages:

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

Or:

nylas email list <NYLAS_GRANT_ID> --limit 10

To pull one message's full content, including its body, fetch it by ID — GET /v3/grants/{grant_id}/messages/{message_id} — or nylas email read <MESSAGE_ID> <NYLAS_GRANT_ID>. That by-id fetch matters for webhooks, which is the next piece.

Wire up webhooks so the agent reacts in real time

You don't want the agent polling. Inbound mail fires the standard message.created event. One important detail: webhooks are application-scoped, not grant-scoped. You subscribe once at the app level with POST /v3/webhooks, and events for every grant in your app land at that one endpoint, each payload carrying the grant_id so you can route it to the right inbox.

A few things to get right:

Don't rely on the webhook payload for the body. Fetch the full message with GET /v3/grants/{grant_id}/messages/{message_id} when you need the content, and branch on message.created.truncated — Nylas uses that event type for very large messages, at which point you re-fetch by ID anyway. Treating the by-id fetch as your source of truth keeps you correct in both cases.
Dedupe on the top-level notification id. Delivery is at-least-once (up to three attempts per event), and that outer id is constant across all retries of a single event — it's your dedup key. You can additionally guard on the inner message id (data.object.id) so you never act twice on the same message.
Verify the signature. Each webhook carries an X-Nylas-Signature header: a hex HMAC-SHA256 of the raw request body using your webhook secret. Compare it with a constant-time compare like Node's crypto.timingSafeEqual, but check that both buffers are the same length first — it throws on a length mismatch. Locally, nylas webhook verify runs the same check so you can sanity-test before deploying.

With that in place, the loop closes: mail arrives → message.created → agent fetches the body → agent triages, drafts, and moves to "Needs review" → a human approves from Outlook. Humans and agent, same mailbox, in real time.

Guardrails and honest tradeoffs

A few things I'd want a teammate to know before they ship this:

One password, one trust boundary. Everyone with the app password has full read/write to the mailbox. There's no per-user ACL. Treat the app password like a shared production credential: store it in a secrets manager, rotate it on personnel changes, and remember that rotating it kicks every connected client. If you need real per-person permissions, build them in your own service in front of the API — the shared inbox can't do it for you.
No custom metadata as agent state. Don't try to stash your agent's bookkeeping on the messages. Keep workflow state — "draft #4 is awaiting Alice's approval since 2pm" — in your database, keyed by message and draft IDs. The mailbox holds mail; your app holds the workflow.
Free-plan limits are real. 200 messages per account per day, 3 GB of storage per org, 30-day inbox retention (7 days for spam). Fine for a pilot; size your plan before a busy launch.
Deletes go to Trash by default. DELETE /v3/grants/{grant_id}/messages/{message_id} trashes a message unless you pass ?hard_delete=true. The CLI nylas email delete only trashes. The only true full wipe of a mailbox is deleting the grant itself.

None of these are dealbreakers — they're just the edges. Knowing where they are means you won't design yourself into a corner expecting the inbox to be something it isn't.

What's next

Connect mail clients to an Agent Account — the full IMAP/SMTP reference, the folder mapping, and the sync table.
How Agent Account workspaces work — group multiple agent inboxes and apply shared policies.
Agent Accounts overview — provisioning, policies, rules, and the rest of the data plane.
Nylas CLI command reference — every nylas command shown above, with its flags.

Build the agent against the API, hand your team an app password, and let the queue between them be a folder both sides can see. That's the whole shared inbox.

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/shared-inbox-api-for-ai-agents.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Qualify real estate leads with an email agent

Qasim — Fri, 10 Jul 2026 01:27:51 +0000

A property inquiry has a half-life measured in minutes. Someone is scrolling listings at 11pm, they fill out the "request more info" form on the three-bedroom on Maple, and they fire the same form off to four other listings on the same street. Whichever agent replies first — with answers, not a "thanks, I'll be in touch" — is the one who gets the showing. By the time a human checks email at 9am, that lead has already toured two other houses in their head.

Most "AI for real estate" tools try to fix this by bolting a chatbot onto a website, or by pointing a model at the agent's personal Gmail and hoping it doesn't reply to the agent's mom. Both are awkward. The first never sees the email leads that come in through Zillow or a portal; the second makes the model a creepy ghostwriter inside a human's private inbox. What you actually want is for the listing inquiries to land somewhere that is the agent — an address that can read the question, qualify the buyer, check its own calendar, and put a showing on it, autonomously, at 11pm, without a human awake.

That's a Nylas Agent Account: a grant with its own email address and its own calendar. It's a real participant, not a bot reading over a human's shoulder. I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for when I'm prototyping one of these loops — and I'll show the raw API call next to each one, because the CLI is just a friendly wrapper over the same /v3/grants/{grant_id}/... endpoints.

What the agent actually does

Strip the AI out and a real estate lead loop is four moves:

An inquiry arrives — "Is the Maple St listing still available? What's the HOA?" — as email, on a thread.
The agent answers the question and starts qualifying — budget, timeline, mortgage pre-approval. It replies in-thread asking what it still needs to know.
The lead replies with some of those answers. The agent updates what it knows.
Once the lead is qualified, the agent books a showing on its own calendar and sends the invite.

Three of those four moves map straight onto Nylas primitives — inbound mail, in-thread reply, calendar event. The fourth — deciding whether a lead is qualified and what to ask next — is your application code. Nylas hands you the email text; your LLM extracts "pre-approved up to $650k, wants to move by September" and decides the lead is ready to book. I'll be honest about that boundary the whole way through, because pretending the API does the reasoning is exactly the demo magic that falls apart in production.

The nice thing is the data plane never changes. An Agent Account is just a grant with a grant_id. If you've used the Nylas email and calendar APIs, you already know every verb below. Nothing new to learn on the data plane.

One thing to get out of the way first, because it's the most common wrong turn: Scheduler is not available for Agent Accounts. No booking pages, no availability-config API, no /v3/scheduling/*. That door is locked for this provider. What you have instead is the grant's own free/busy plus the Events API — and that's enough to book the showing yourself.

Before you begin

You need:

An Agent Account (a grant). The quickstart walks through it; the short version is one POST /v3/connect/custom with "provider": "nylas" and an email on a registered domain — no refresh token, no OAuth dance:

  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": "Maple Realty Listings",
      "settings": { "email": "listings@yourbrokerage.com" }
    }'

Or, from the CLI:

  nylas agent account create listings@yourbrokerage.com --name "Maple Realty Listings"

Its grant_id, and a Nylas API key exported as NYLAS_API_KEY.
A message.created webhook so the agent reacts within seconds of an inquiry — that responsiveness is the whole selling point.
A database. Lead state lives in your DB, not on the message. Agent Accounts don't support custom metadata on messages, so the budget, timeline, and pre-approval status you extract have to live in your own store, keyed by thread_id.

New to all this? Read What are Agent Accounts first. All API examples use the US base host https://api.us.nylas.com and a bearer token — swap in api.eu.nylas.com for the EU region.

Step 1: Receive the inquiry

Inbound mail to the agent fires the standard message.created webhook. Webhooks are application-scoped, not grant-scoped — you subscribe once at the app level with POST /v3/webhooks, and events for every grant arrive at that one endpoint. Each payload carries a grant_id you filter on, so an app running ten listing agents still has a single webhook URL.

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://leads.yourbrokerage.com/webhooks/nylas",
    "description": "Listing inquiry handler"
  }'

The CLI does the same in one line:

nylas webhook create \
  --url "https://leads.yourbrokerage.com/webhooks/nylas" \
  --triggers message.created \
  --description "Listing inquiry handler"

Two things to bake into the handler before you do anything clever:

Dedupe on the notification id. Nylas guarantees at-least-once delivery — the same event can arrive up to three times. The top-level notification id is constant across all retries of one event, so that's your delivery dedup key. Drop it in a seen_notifications set with a TTL and bail early on repeats. (You can additionally guard on the inner data.object.id, the message id, so you never act twice on the same message even across distinct events.)
Don't rely on the webhook payload for the body. Whether the body ships inline depends on size, so don't build on it. When you need the full message, fetch it by id with GET /v3/grants/{grant_id}/messages/{message_id}, and branch on message.created.truncated — that variant fires for large messages and never includes the body, so re-fetch.

// Express handler — verify X-Nylas-Signature first, then:
app.post("/webhooks/nylas", async (req, res) => {
  res.status(200).end(); // ack fast; Nylas retries on non-2xx

  const event = req.body;
  if (event.type !== "message.created" && event.type !== "message.created.truncated") return;
  if (event.data.object.grant_id !== AGENT_GRANT_ID) return;

  // Delivery dedup: notification id is constant across retries.
  if (await seen(event.id)) return;
  await markSeen(event.id);

  await handleInquiry(event.data.object); // {id, thread_id, ...} — fetch body next
});

Step 2: Read the message

The webhook gave you summary fields and a thread_id. To extract budget and intent, you need the body — fetch it by id:

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

From the CLI:

nylas email read <MESSAGE_ID>

If you want the whole conversation so far — useful once a lead has gone a few rounds — pull the thread instead:

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

Or, from the CLI:

nylas email threads show <THREAD_ID>

What you do with that text is your code. "Hi, saw the Maple St place, we're pre-approved around $600k and hoping to move before the school year — is it still available?" is natural language. Feed it to an LLM and have it return structured fields: budget, timeline, preapproved, plus the actual question to answer. Persist that against the thread_id in your DB. Don't pretend the API parses intent — it hands you text and you decide what it means.

The qualification logic is the part you own end to end. A reasonable bar: you'll book a showing once you have a budget that overlaps the listing price, a timeline inside your window, and a pre-approval signal (or an explicit "paying cash"). Missing any of those, the agent's job in step 3 is to ask for it — politely, one or two questions at a time, not an interrogation.

Step 3: Answer and qualify, in-thread

The agent replies on the same thread — answering the question that was asked and asking for whatever qualification data is still missing. Replying in-thread keeps the whole conversation in one place in the lead's inbox, where they'll naturally reply again. Pass reply_to_message_id and Nylas sets the In-Reply-To and References headers for you:

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 '{
    "reply_to_message_id": "<INBOUND_MESSAGE_ID>",
    "to": [{ "email": "buyer@example.com" }],
    "subject": "Re: Maple St listing",
    "body": "Yes, 142 Maple St is still available — HOA is $210/month and it includes water and trash. To line up a showing, two quick things: roughly what price range are you targeting, and are you already pre-approved with a lender?"
  }'

The CLI version is shorter, because reply fetches the original message and fills in recipient, subject, and threading automatically:

nylas email reply <INBOUND_MESSAGE_ID> \
  --body "Yes, 142 Maple St is still available — HOA is \$210/month and it includes water and trash. To line up a showing, two quick things: roughly what price range are you targeting, and are you already pre-approved with a lender?"

The wording — what to answer, which qualification question to lead with, how warm to sound — is generated by your LLM from the gaps in the lead record you saved in step 2. The send and the threading are Nylas; the phrasing and the choice of what to ask are yours.

This is the after-hours payoff. That reply goes out at 11:04pm, four minutes after the inquiry, while a human agent is asleep and the four competing listings sit unanswered. By the time anyone wakes up, this lead is mid-conversation with you.

Step 4: Loop on the reply until qualified

The lead replies: "We're pre-approved up to $650k and want to be in before September." That fires another message.created on the same thread. Your handler dedupes on the notification id (step 1), looks up the thread_id in your DB, sees a lead mid-qualification, fetches the body (step 2), and merges the new facts into the record.

Now your code re-checks the bar. Still missing something? Reply again asking for it (step 3). Got everything — budget overlaps, timeline fits, pre-approved? The lead is qualified. Move to booking.

Two things keep this survivable in production:

State lives on the thread, in your DB. Map thread_id to the lead's qualification record — what you know, what you've asked, how many rounds you've run. Keep it durable; these conversations span hours or days. There's no custom-metadata field on the message to lean on, so this is on you.
Cap the rounds. Decide what happens after, say, three exchanges with no progress: hand off to a human agent, or send a "happy to answer more by phone" close and stop. Open-ended LLM-on-LLM back-and-forth burns your daily send quota for nothing — Agent Accounts cap outbound sends per day.

Step 5: Check the agent's own calendar

The lead is qualified. Before the agent proposes a showing time, it checks its own free/busy so it never offers a slot it's already booked into. The endpoint is POST /v3/grants/{grant_id}/calendars/free-busy — give it a window and the agent's own address:

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": 1750766400,
    "end_time": 1751025600,
    "emails": ["listings@yourbrokerage.com"]
  }'

The response is a list of busy blocks for that address over the window. The open slots are the gaps between them — computing those gaps is your code. Free/busy tells you what's taken; you decide what counts as a showing slot (daylight hours? 45-minute blocks with travel buffer?).

The CLI wraps the same call:

nylas calendar availability check \
  --emails listings@yourbrokerage.com \
  --start "this saturday 9am" \
  --end "this sunday 6pm"

A point worth stating plainly: free/busy here checks the agent's calendar, not the buyer's. You're qualifying and booking over email precisely because you can't see the buyer's calendar. So the agent proposes a couple of slots it's confirmed open on its end and lets the buyer pick — exactly how a human agent texts "I've got Saturday at 10 or 2, which works?"

Step 6: Book the showing on the agent's calendar

The buyer picks a slot — or you offer two and they reply "Saturday at 10 works." Now you create the event. Because the agent is a real calendar participant, creating with notify_participants=true sends a normal ICS invitation from the agent's address. The buyer gets it in Gmail or Outlook and clicks Accept like any other invite. calendar_id is a required query parameter; use primary:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary&notify_participants=true" \
  --header "Authorization: Bearer $NYLAS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Showing — 142 Maple St",
    "location": "142 Maple St",
    "when": { "start_time": 1751032800, "end_time": 1751035500 },
    "participants": [
      { "email": "buyer@example.com" }
    ]
  }'

The CLI creates the same event:

nylas calendar events create \
  --calendar primary \
  --title "Showing — 142 Maple St" \
  --location "142 Maple St" \
  --start "2026-06-27 10:00" \
  --end "2026-06-27 10:45" \
  --participant buyer@example.com

One honest gap to call out: notify_participants is a query parameter on the API create call, and the CLI events create doesn't expose a flag for it. So if you need the invitation email to fire — which you do, for a showing — book it through the API path, or follow the CLI create with an explicit confirmation email. Speaking of which: send one final reply on the thread — "You're confirmed for Saturday at 10am, 142 Maple St, see you there" — so the conversation closes in the buyer's inbox where it started, not as a silent calendar ping.

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": "buyer@example.com" }],
    "subject": "Re: Maple St listing",
    "body": "You'\''re all set — Saturday at 10:00 AM, 142 Maple St. I'\''ve sent a calendar invite. See you there!"
  }'

Or, from the CLI:

nylas email send \
  --to buyer@example.com \
  --subject "Re: Maple St listing" \
  --body "You're all set — Saturday at 10:00 AM, 142 Maple St. I've sent a calendar invite. See you there!"

After the create fires, event.created lands on the agent's calendar; when the buyer clicks Accept, their RSVP flows back to the agent's mailbox and event.updated fires with their status. The lead is now genuinely booked: a real showing on a real calendar, qualified and scheduled entirely over email, at 11pm, with no human in the loop.

Guardrails and honest tradeoffs

A few things I'd build in before pointing this at real leads:

The qualification is yours, and it will be wrong sometimes. Parsing "pre-approved around $600k" or "before the school year" out of free-text email is an LLM task, and LLMs misread numbers and dates. Don't auto-book off a shaky parse — when confidence is low, ask one clarifying question instead of guessing.
Validate the slot one more time before you book. Re-run free/busy right before the create call. A showing can get booked into a slot that filled up during the back-and-forth.
Every reply and invite counts against the send quota. A lead that runs three qualification rounds plus a confirmation plus an invite is several sends. Cap your rounds — partly for sanity, partly for quota.
Dedupe or you'll double-book. Webhook redelivery and concurrent workers both re-trigger the handler. Dedupe on the notification id, and make booking idempotent on thread_id so two near-simultaneous "yes" replies don't create two showings.
State has nowhere to hide. No custom metadata on messages means your DB is the single source of truth for every lead. Treat the thread_id-keyed record as the system of record, not the inbox.
No Scheduler, by design. If your instinct is to hand the buyer a booking page, remember that's not available for Agent Accounts. The free/busy-plus-Events flow above is the supported path, and for a single-agent showing it's honestly simpler.

What's next

The shape is deliberately plain: inbound inquiry → read and qualify → reply asking for what's missing → loop → check own free/busy → book the showing. Three Nylas primitives and one piece of reasoning you own. The after-hours responsiveness — answering and qualifying while competitors sleep — is the entire point.

Agent Account calendars — hosting events, receiving invites, and RSVPs once the time is agreed
Handle email replies in an agent loop — the webhook-to-reply pattern this post is built on
Email threading for agents — the thread-state pattern that carries qualification across replies
Supported endpoints — the full list of what works (and the handful that doesn't) for Agent Account grants
CLI command reference — every nylas email and nylas calendar flag used above

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/lead-qualification-email-agent-workflow.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Build an SDR agent with its own follow-up inbox

Qasim — Fri, 10 Jul 2026 01:27:45 +0000

SDR automation dies when replies hit a no-reply box. The sequence engine is the easy part — anyone can fire "step 1 of 5" on a cron. The part that quietly breaks every outbound tool is the other direction: a prospect reads your third touch, types "not now, circle back in Q3," and hits reply. That reply is the single most valuable signal in the whole campaign, and it lands in no-reply@yourcompany.com, which is to say it lands nowhere. The prospect who told you exactly when to follow up gets your "step 4" two days later anyway, because your sequence engine never heard them.

The naive fix is to point an LLM at a human SDR's mailbox and let it draft. That works right up until you want the agent to be a participant — to send under its own address, receive the reply under that same address, and decide what to do next without a person in the loop. A human's inbox is the wrong substrate for that. You don't want an autonomous sender borrowing a rep's OAuth grant and threading replies into the rep's personal inbox where a notification storm waits.

What you want is an address the agent owns: it sends the sequence, it receives "not now" and "send me pricing" and "unsubscribe," it classifies each one, routes it to the right next action, and — the piece every outbound tool forgets — stops the sequence the moment a real reply arrives. That address is a Nylas Agent Account. I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for when wiring this up; the curl calls beside them are what the CLI runs under the hood, so either drops straight into your stack.

What an Agent Account actually is

The thing to internalize before you write a line of code: an Agent Account is just a grant. Same grant_id, same /v3/grants/{grant_id}/* endpoints, same Authorization: Bearer <NYLAS_API_KEY> header as any connected Gmail or Microsoft mailbox you've ever integrated. There's no separate "outbound" SDK, no new auth model, no second data plane. If you've ever sent a message or listed a thread from a Nylas grant, you already know the entire data plane for this post. The grant abstraction is the spine here — nothing new to learn on the read/write side.

What's different is the control plane. There's no human OAuth and no refresh token to babysit. You provision the mailbox yourself on a domain you own (or a *.nylas.email trial subdomain), and Nylas hosts it. For prospecting that's exactly right: outbound@yourcompany.com belongs to the system, not to a rep who might leave and take their refresh token with them. And because it's a real mailbox, replies land back in it as ordinary inbound messages you can read and answer — which is the whole reason this beats a transactional send.

One tradeoff to flag up front, because it shapes the architecture: Agent Accounts don't support custom metadata on messages. You can't stamp { "prospect_id": "P-901", "step": 3 } onto the outbound email and read it back later to figure out where someone sits in the sequence. That's fine, and it's the right design anyway. Your sequence state — who's on which step, who replied, who's paused — was always going to live in your own database. The email is the message; your DB is the state machine. Hold that thought, because it's also where "stop on reply" lives.

Why this beats a one-way sequencer

Let me be fair to the blast tools first. If your outbound is a pure one-way drip — five touches, no intention of reading what comes back — a transactional ESP or a classic sequencer is a fine fit. The Agent Account earns its keep the moment a reply needs a decision:

Replies go somewhere, and get classified. "Not now," "send me pricing," and "unsubscribe" are three completely different next actions, and a no-reply box collapses all of them into silence. The agent reads each reply and routes it: snooze the sequence, send the one-pager, suppress the address forever.
The sequence stops on engagement. A one-way drip keeps firing on schedule. A conversational agent keys off the message.created webhook — the instant a reply lands on a tracked thread, you flip that prospect's state to paused and the next touch never sends. Nobody gets "step 4" an hour after they replied.
Context survives across steps. Every send and reply rides the same thread, so the prospect sees one coherent conversation, not five disconnected blasts with the same footer.
It's one grant. The same Agent Account that sends step 1 receives the reply, sends the pricing follow-up, and logs the unsubscribe. One mailbox, one auth model.

Here's the honest line: the LLM does the classification, and your code does the routing. Nylas doesn't classify "not now" vs "send pricing" for you — it delivers the reply, you fetch the body, and your own model or rules decide what bucket it's in. Don't let anyone tell you the platform reads intent. It moves mail; you read intent.

Before you begin

You'll need:

A Nylas API key from the dashboard, exported as NYLAS_API_KEY.
A domain you own for the mailbox, or a Nylas *.nylas.email trial subdomain. This matters more for cold outbound than for any other use case. New domains warm over roughly four weeks — start low-volume and ramp, because a brand-new domain blasting a cold list is how you land in spam folders on day one.
The Nylas CLI if you want the terminal path: nylas init once to store your key.
A public HTTPS endpoint for the webhook. A tunnel (cloudflared) is fine in development.
Your own data plane: a prospect store, a sequence-state table, and an LLM or ruleset for reply classification.

:::info
New to Agent Accounts? Start with What are Agent Accounts for the product overview, then come back here.
:::

Provision the outbound mailbox

Create the grant first. The API call is POST /v3/connect/custom with provider: "nylas" and the email on your domain. The optional top-level name sets the display name prospects see.

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

The response carries the grant_id — the only identifier you carry forward. Nylas also auto-creates a default workspace and policy for the account, which matters later when we add a suppression list.

The CLI collapses connector setup, grant creation, and the default workspace into one command:

nylas agent account create outbound@yourcompany.com --name "Acme Outbound"

If the nylas connector doesn't exist in your app yet, this creates it first, then the grant. Add --json to capture the grant_id for a script. Export it as GRANT_ID for the rest of this post.

Subscribe to inbound replies

The sequence needs to know when a prospect writes back. Inbound mail fires the standard message.created webhook — the same trigger every Nylas inbox uses. One thing to get right conceptually: webhooks are application-scoped, not grant-scoped. You subscribe once at the app level against /v3/webhooks, and events for every grant in your app arrive at that one endpoint, each payload carrying a grant_id you filter on. You don't register a webhook per Agent Account.

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://api.yourcompany.com/hooks/outbound",
    "description": "SDR sequence replies"
  }'

From the terminal, list the available triggers, register the webhook, then stand up a local listener to watch real events during development:

nylas webhook triggers
nylas webhook create --url https://api.yourcompany.com/hooks/outbound --triggers message.created
nylas webhook server --port 4000 --tunnel cloudflared --secret <webhook-secret>

nylas webhook server runs a local endpoint behind a cloudflared tunnel and verifies the X-Nylas-Signature HMAC on each event, so you can trigger a real reply and watch the payload land before you ship the production handler. In production, verify that signature yourself: it's a hex HMAC-SHA256 of the raw request body using your webhook secret. If you compare with a constant-time function like Node's crypto.timingSafeEqual, guard that both buffers are equal length first — it throws on a length mismatch.

Send the sequence

A prospecting sequence is a handful of touches spaced over days: an intro, a value-add follow-up, a case study, a last-call. Each one is a normal grant send — POST /v3/grants/{grant_id}/messages/send.

Here's the first step as a curl call:

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": "dana@acme.com", "name": "Dana Lee" }],
    "subject": "Quick question about Acme'\''s onboarding flow",
    "body": "Hi Dana — noticed Acme onboards a lot of new accounts each week. Worth a 15-minute look at how teams like yours cut that time? Reply here and I'\''ll send specifics."
  }'

The same send from the CLI:

nylas email send "$GRANT_ID" \
  --to dana@acme.com \
  --subject "Quick question about Acme's onboarding flow" \
  --body "Hi Dana — worth a 15-minute look? Reply here and I'll send specifics."

The response includes the message's id and thread_id. Persist both, keyed to the prospect, the moment the send returns:

prospect P-901 → { thread_id, last_message_id, step: 1, state: "active", next_send_at }

That row is your sequence state. There's no metadata on the email to lean on, so this DB record is the only place that knows Dana is on step 1 of prospect P-901's sequence and that step 2 is due in two days.

Schedule the later steps instead of running a cron

You don't have to hold step 2 in a job queue and fire it yourself. The send endpoint accepts a send_at (Unix timestamp) and Nylas queues the message server-side:

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": "dana@acme.com", "name": "Dana Lee" }],
    "subject": "Re: Quick question about Acme'\''s onboarding flow",
    "body": "Following up — here is a two-minute breakdown of the onboarding numbers I mentioned.",
    "send_at": 1751385600
  }'

To compute a real timestamp instead of hardcoding one, the CLI's date is your friend:

date -v+2d +%s   # macOS: two days from now as a Unix timestamp

The CLI takes a duration or a clock time directly and computes the timestamp for you — 30m, 2h, 1d, a time like 14:30, or a phrase like "tomorrow 9am":

nylas email send "$GRANT_ID" \
  --to dana@acme.com \
  --subject "Re: Quick question about Acme's onboarding flow" \
  --body "Following up — here is a two-minute breakdown." \
  --schedule 2d

A scheduled send returns a schedule_id you can store and cancel later — which matters a lot, because canceling the queued step is exactly how you stop the sequence when the prospect replies. More on that next.

Catch the reply and classify it

This is the behavior that separates a conversation from a pestering. The signal is the message.created webhook: a reply on a thread you're tracking means the prospect engaged, and the rest of the touches should not fire blindly.

Two things to get right in the handler before any classification logic:

message.created fires for outbound too. When your agent sends a reply, the webhook fires for that sent message as well. Filter on the sender at the top of the handler so the agent never reacts to its own mail.
Dedup on the notification id. The API guarantees at-least-once delivery — the same event can arrive up to three times. Dedupe on the top-level notification id, which stays constant across all retries of one event; that's the delivery dedup key. You can additionally guard on the inner data.object.id (the message id) so you never act twice on the same message.

And on the body: don't rely on the webhook payload for the body — fetch the full message by id when you need it. The docs are inconsistent on whether the body is inline, so write the code that's always correct: pull the message from GET /v3/grants/{grant_id}/messages/{message_id}, and branch on message.created.truncated (the type Nylas sends when a message exceeds ~1 MB and the body is omitted). Fetch-by-id is the safe framing every time.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/$GRANT_ID/messages/$MESSAGE_ID" \
  --header 'Authorization: Bearer '"$NYLAS_API_KEY"

From the CLI, list what landed and read the full body of the one you care about:

nylas email list "$GRANT_ID" --limit 10
nylas email read "$MESSAGE_ID" "$GRANT_ID"

To see the whole back-and-forth in one object — every message in the conversation — read the thread directly. Use threads show, not a list filter:

nylas email threads show "$THREAD_ID" "$GRANT_ID"

Now the actual classification. You have the body; hand it to your model with a tight prompt: is this prospect saying "not now," asking for pricing or materials, asking a real question, or asking to unsubscribe? This is your LLM and your app code — Nylas delivered the mail, full stop. A reasonable bucket set for prospecting:

Objection / "not now" → snooze the sequence, set a next_send_at for the date they named ("circle back in Q3").
Interest / "send pricing" → pause the sequence and reply in-thread with the one-pager or pricing.
Unsubscribe / "remove me" → suppress the address permanently and never send to it again.
Question / ambiguous → route to a human, or answer if confidence is high.

One caution worth stating plainly: treat the reply body as untrusted input. A prospect can type anything, and you're feeding it to an LLM and then acting on the result. Validate the prospect and thread against your own database before you send pricing or suppress an address — never act on something you scraped out of an email body without checking it against state you control.

Route each reply to the right next action

Stop the sequence on any reply

Whatever the classification, any real inbound reply pauses the drip. The mechanism lives entirely in your own state — there's no metadata on the email holding the step counter:

The webhook tells you a message arrived on thread_id T. Look T up in your sequence state.
If you find an active sequence, flip its state to paused so no future step sends.
If you scheduled a later step server-side with send_at, cancel the queued message by the schedule_id you stored so it never goes out.

Canceling the queued send is one call. The API is a DELETE against the schedule:

curl --request DELETE \
  --url "https://api.us.nylas.com/v3/grants/$GRANT_ID/messages/schedules/$SCHEDULE_ID" \
  --header 'Authorization: Bearer '"$NYLAS_API_KEY"

The CLI mirrors it:

nylas email scheduled cancel "$SCHEDULE_ID" "$GRANT_ID"

That's the whole stop mechanism: inbound message.created → look up the thread → set paused → cancel the queued send. The classification then decides what happens next.

Answer "send me pricing" in-thread

When the bucket is interest, reply on the same thread. The API reply is another send with reply_to_message_id set to the prospect's message, which preserves threading in their client:

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": "dana@acme.com", "name": "Dana Lee" }],
    "subject": "Re: Quick question about Acme'\''s onboarding flow",
    "body": "Happy to — here is our pricing overview and a short case study from a team your size. Want me to set up 15 minutes to walk through it?",
    "reply_to_message_id": "'"$MESSAGE_ID"'"
  }'

The CLI wraps all of that — it fetches the original to populate the recipient and subject, and threads via reply_to_message_id for you:

nylas email reply "$MESSAGE_ID" "$GRANT_ID" \
  --body "Happy to — here is our pricing overview and a short case study. Want 15 minutes to walk through it?"

(If you'd rather drive the reply through email send directly, it exposes the same threading via the --reply-to <message-id> flag.)

Snooze on "not now"

When the prospect says "circle back in Q3," you don't reply — you reschedule. Set the sequence state's next_send_at to the date they named and leave the drip paused until then. No API call needed beyond storing the date; when that date arrives, your scheduler resumes the sequence with a fresh send. The win is that you're following up when they told you to, which is worth ten cold touches.

Honor unsubscribes and watch deliverability

Cold outbound lives or dies on deliverability, and the fastest way to torch a domain is to keep mailing people who asked you to stop, or to keep hammering addresses that bounce. Two pieces close that loop.

Unsubscribes and bounces belong on a suppression list. Agent Account rules support an in_list operator that matches a sender address against a managed list — exactly the shape of a suppression list. The pattern is two pieces: a list you populate with addresses to suppress, and a rule that acts on in_list matches.

Start by creating the list. It's an address-typed list (the type is immutable, and it's what from.address matches against). Create it via POST /v3/lists:

curl --request POST \
  --url 'https://api.us.nylas.com/v3/lists' \
  --header 'Authorization: Bearer '"$NYLAS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Suppressed addresses", "type": "address" }'

When a prospect unsubscribes or an address hard-bounces, add it to the list. The API appends items to the existing list:

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": ["dana@acme.com"] }'

The CLI does both in two commands — create the list (optionally seeding it inline with --item), then append more addresses as they come in:

nylas agent list create --name "Suppressed addresses" --type address
nylas agent list add "$LIST_ID" dana@acme.com

Now the rule that enforces the list. A rule is inert until it's attached to a workspace — remember the default workspace Nylas created with the account. From the CLI, agent rule create builds the rule and attaches it to that default workspace in one step:

nylas agent rule create \
  --name "Suppress unsubscribed" \
  --condition from.address,in_list,"$LIST_ID" \
  --action block

The equivalent API path is creating the rule via POST /v3/rules, then activating it by attaching it through the workspace's rule_ids (PATCH /v3/workspaces/{workspace_id} with { "rule_ids": ["<rule-id>"] }, or nylas workspace update <workspace-id> --rules-ids <rule-id>). Skip that attach step and the rule does nothing. One honest limitation to design around: inbound rules match only on from.* fields — from.address, from.domain, from.tld — they cannot match on subject or message content. So "suppress anyone whose reply contains the word unsubscribe" is not a rule. You classify that intent in your app code after the webhook, then add the address to the list. The rule enforces the list; your code populates it.

Watch bounces and complaints. Agent Accounts emit deliverability webhooks beyond message.created: message.delivered, message.bounced, message.complaint, and message.rejected (which fires specifically when an outbound message is rejected because an attachment carried a virus — not as a generic rejection). A hard bounce or a spam complaint is a strong signal to stop mailing that address; in your webhook handler, route both into the same suppression list you built above with one agent list add (or POST /v3/lists/{list_id}/items). One transparency note from working on the CLI: these deliverability triggers are wired through the webhooks API — subscribe to them in your trigger_types array — and there isn't a dedicated CLI shortcut for each, so the API is the path here. I'd rather tell you that than have you hunt for a flag that doesn't exist.

What's next

You've got the full loop: provision a replyable outbound mailbox, send a scheduled multi-step sequence, catch each reply via message.created, classify "not now" vs "send pricing" vs "unsubscribe" in your own code, route each to the right action, stop the sequence on engagement, and protect the domain with a suppression list. From here:

Handle email replies in an agent loop — the detection, dedup, and routing patterns in depth.
Nylas for sales engagement — booking the meeting and logging activity once a prospect bites.
Agent Accounts overview — policies, rules, and the deliverability webhooks.
Nylas CLI command reference — every email, webhook, and agent command with full flags.

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/agent-account-sales-development-inbox.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

Run a legal intake agent on its own mailbox

Qasim — Fri, 10 Jul 2026 01:27:37 +0000

Law-firm intake is one of those problems that looks like a chatbot and isn't. A prospective client emails intake@yourfirm.com describing a dispute, and what the firm actually needs is careful capture and a clean handoff — collect the matter details, check the names against existing clients and known adverse parties, and put the whole thing in front of a human attorney. The one thing you must not do is let a model freelance legal advice over email.

Most "AI email" demos point a model at a human's inbox and let it draft replies. That's fine for a personal assistant. It's the wrong shape for regulated intake, where you want the agent to be a participant with its own address, its own audit trail, and a hard wall between "I'm gathering facts" and "an attorney decides." So this post builds the agent on a dedicated mailbox using a Nylas Agent Account, wires up inbound webhooks, walks the collect-and-reply loop, and — the interesting part — implements conflict-check routing that knows the difference between what a mail rule can see and what your application has to classify itself.

I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for. Every step gets the two-angle tour: the raw curl call and the nylas equivalent.

What you get

An Agent Account is just a grant — the same grant_id abstraction behind every Nylas mailbox. There's nothing new to learn on the data plane. Once the account exists, you read with GET /v3/grants/{grant_id}/messages, you send with .../messages/send, you reply in-thread with reply_to_message_id. The same calls you'd make against a connected Gmail account work here, except this mailbox belongs to your application instead of a person.

For intake specifically, that buys you:

A real, addressable inbox (intake@yourfirm.com) that prospects can email and reply to, with threads that hold together across days.
Inbound webhooks so your code reacts the moment a new-matter inquiry lands.
Account-level Rules that can reject mail from known-adverse senders at SMTP, before your application ever sees it.
A clean place to park escalations — a folder an attorney monitors — with the agent's auto-replies paused.

Before you begin

You'll need a Nylas application with an API key, and a registered sending domain (a custom domain, or a Nylas *.nylas.email trial subdomain to start). New domains warm over roughly four weeks, so if deliverability matters for client correspondence, register the real one early. Examples below use https://api.us.nylas.com and an Authorization: Bearer <NYLAS_API_KEY> header.

One honest caveat up front, because this is a regulated space: what follows builds intake capture and routing, not legal advice. The agent collects facts and hands off to a licensed attorney. Nothing here is legal advice about how to run a conflicts process — your firm's rules govern that. Treat the agent as the front desk, not the lawyer.

Provision the intake mailbox

Create the Agent Account with POST /v3/connect/custom, using provider: "nylas" and a settings.email on your registered domain. The optional top-level name sets the display name prospects see. No OAuth, no refresh token.

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": "Firm Intake",
    "settings": { "email": "intake@yourfirm.com" }
  }'

The response carries a grant_id. That's your handle for everything else.

From the CLI it's one line. The API auto-creates a default workspace and policy for the account, so you don't pass a workspace on create:

nylas agent account create intake@yourfirm.com --name "Firm Intake"

There's no --workspace flag here, and that's deliberate — if you later want a custom policy (stricter send limits, tighter retention), you attach it to the account's workspace separately with nylas workspace update <workspace-id> --policy-id <policy-id>. For most intake setups, the default workspace is fine to start.

Receive new-matter inquiries

Inbound mail to an Agent Account fires the standard message.created webhook. Webhooks in Nylas are application-scoped, not grant-scoped: you subscribe once at the app level, and every grant's events arrive at that one endpoint, each payload carrying a grant_id you filter on. So you subscribe through the top-level /v3/webhooks endpoint:

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://intake.yourfirm.com/webhooks/nylas"
  }'

Or with the CLI:

nylas webhook create \
  --url https://intake.yourfirm.com/webhooks/nylas \
  --triggers message.created

When an inquiry lands, you get a notification. Two things matter in how you handle it.

First, dedup. Nylas guarantees at-least-once delivery — the same event can arrive up to three times. The dedup key is the top-level notification id, which stays constant across all retries of one event. Record it; if you've seen it, drop the duplicate. (The inner data.object.id is the message id — you can additionally guard on that to avoid acting twice on the same message, but the notification id is the delivery-level key.) For an intake agent this is not optional: you do not want to send a prospect two "thanks, we got your inquiry" replies because a worker retried.

Second, the body. Don't rely on the webhook payload for the message body — fetch the full message by id when you need it, and branch on message.created.truncated (which Nylas uses when the body is large). The reliable move is always the same: take the message id from the notification and go get the message.

A sketch of the handler:

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

  const event = req.body;
  if (event.type !== "message.created" && event.type !== "message.created.truncated") return;
  if (seen(event.id)) return;          // dedup on the notification id
  markSeen(event.id);

  const { grant_id, id: messageId } = event.data.object;
  await handleInquiry(grant_id, messageId);
});

Read the inquiry

Now fetch the full message by id. Keep this as a plain read — fetching does not mark anything read, that's a separate PUT if you want it.

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

From the terminal, while you're developing the agent and want to eyeball what came in:

nylas email read <message-id>

nylas email read shows the full message content; add -r if you specifically want to mark it read after viewing. This is the input your classifier works on — the prospect's description of the matter, the parties involved, the relief they're after.

Reply to collect the details you're missing

A first-touch inquiry is almost never complete. The agent's job is to ask for the specific facts intake needs — the other party's full legal name, the jurisdiction, key dates, whether litigation has already started — and to do it in-thread so the conversation holds together.

Reply with reply_to_message_id set to the inbound message. That preserves the thread by setting the In-Reply-To and References headers, so the prospect sees a threaded reply, not a fresh email:

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": "<MESSAGE_ID>",
    "to": [{ "email": "prospect@example.com" }],
    "subject": "Re: New matter inquiry",
    "body": "Thanks for reaching out. To get your matter to the right attorney, could you share the full legal name of the other party, the state where this is happening, and any key dates?"
  }'

The CLI fetches the original to populate recipient and subject automatically, so you only supply the body:

nylas email reply <message-id> --body "Thanks for reaching out. To route your matter, could you share the full legal name of the other party, the state involved, and any key dates?"

When the prospect replies, message.created fires again on the same thread_id. Pull the thread for full context before deciding what to ask next, so the agent reasons over the whole exchange instead of one stray reply:

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

nylas email threads show <thread-id>

Loop until you have what intake needs. Two practical notes on the loop: the webhook fires for the agent's own outbound sends too, so filter on the sender to avoid replying to yourself, and keep the dedup guard in place because multiple replies can land on one thread.

Conflict-check routing: what a Rule can do, and what it can't

Here's the part that trips people up, and it's worth being precise about because conflicts are exactly where "close enough" gets a firm in trouble.

Agent Accounts have account-level Rules that filter mail. An inbound Rule matches on sender fields only — from.address, from.domain, and from.tld, with operators is, is_not, contains, and in_list. That makes Rules a genuinely good fit for one slice of conflict checking: known adverse parties you can identify by their email. If your firm maintains a list of domains or addresses you must not represent against, a Rule can reject that mail at SMTP before it ever reaches the mailbox.

Build it as a List the conflicts team can maintain, then a Rule that references it. From the CLI:

nylas agent list create --name "Adverse parties" --type domain --item adverseco.example
nylas agent rule create --name "Suppress adverse-party mail" \
  --trigger inbound \
  --condition from.domain,in_list,<LIST_ID> \
  --action block

The same thing over the API — create the list, seed it with the adverse-party domains, then create the rule. The create call returns the list's id, which you use both to add items and to reference the list from the rule:

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

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": ["adverseco.example", "anothercounterparty.example"] }'

The CLI does the same — the --item flag above seeds at creation time, and nylas agent list add appends to an existing list, which is what the conflicts team runs as the watchlist grows:

nylas agent list add <list-id> adverseco.example anothercounterparty.example

That's the seam non-engineers own: they keep the List current, and every rule referencing it picks up new values immediately. With the list seeded, create the rule that references it:

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

One thing to know: a Rule is inert until it's attached to a workspace via that workspace's rule_ids. The CLI nylas agent rule create attaches the new rule to the account's default workspace for you; over the raw API you add the rule's ID to the workspace's rule_ids array with PATCH /v3/workspaces/{workspace_id}. Until you do, the rule exists but does nothing.

Now the honest limit, and it's the whole reason this section exists. A Rule cannot read message content. It matches the sender, not the subject and not the body. Real conflict checking is mostly about names inside the matter — the opposing party a prospect mentions in their description, a company that isn't the sender, a person who'll never appear in a from header. A Rule can't see any of that, and you should never claim it does.

So content-level conflict checks are application-side classification, not a Rule. After you fetch the message, run the matter text through your own conflicts logic (your client database, a watchlist, an LLM extracting party names — your call), and act on the result by moving the message, not by trusting a rule to have caught it:

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "folders": ["<CONFLICT_REVIEW_FOLDER_ID>"] }'

nylas email move <message-id> --folder <conflict-review-folder-id>

The mental model worth keeping: sender-based suppression is a Rule; content-based conflict review is your code plus a folder move. Conflating the two is how you'd accidentally let a real conflict through because you assumed a rule was reading something it can't.

Escalate to a human attorney

When the agent has collected enough — or when conflict logic flags a possible hit — the matter goes to a person. Escalation here means two concrete things, and neither of them is "the agent decides the case."

First, move the message into a human-review folder an attorney monitors. Create that folder once — the response carries the folder id you route into later:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Attorney review" }'

nylas email folders create "Attorney review"

Then route into it with the same PUT ... folders[] / nylas email move you used for conflict review — just a different destination folder.

nylas email move <message-id> --folder <attorney-review-folder-id>

Second, pause the agent's auto-replies for that thread. This is application-side state — you flip a flag in your own store keyed by thread_id and your webhook handler checks it before replying. Nylas Agent Accounts don't support custom metadata on messages, so don't try to stash "escalated" on the message itself; keep that state in your database. Once an attorney is in the loop, your handler sees the flag and stops generating replies, so the agent never talks over a lawyer.

That's the clean handoff: facts captured, routed, parked in front of a human, with the bot silenced. The agent did intake. The attorney does law.

Guardrails worth keeping

A few things I'd nail down before pointing real prospects at this:

Dedup is load-bearing. Webhook redelivery plus concurrent workers will re-trigger your handler. Guard on the notification id, and additionally on the message id, before you ever send a reply.
Sender suppression and content conflicts are different mechanisms. Rules catch known-adverse senders; your code catches adverse parties named in the matter. Run both.
Keep fetch and mark-read separate. Reading a message via GET doesn't change its unread state — mark it read explicitly with PUT ... {"unread": false} if your attorney's view depends on it.
Watch the limits while prototyping. Free-plan Agent Accounts cap at 200 messages per account per day, with 30-day inbox and 7-day spam retention. That's plenty for intake testing; size it up for production volume.
This is intake, not advice. The agent gathers and routes. Every substantive decision lands with a licensed attorney. Build the wall in code, and don't let "helpful auto-reply" drift into anything that reads like counsel.

What's next

The grant abstraction is the whole trick here: once intake@yourfirm.com is an Agent Account, every endpoint you already know — messages, threads, folders, webhooks — works exactly as it does on a personal mailbox. Read the Agent Accounts overview for provisioning and domain warming, the Policies, Rules, and Lists guide for the full Rule condition reference (including exactly which fields each trigger accepts), and the handle email replies recipe for the reply-loop and dedup patterns in depth. The CLI commands are all documented at cli.nylas.com/docs/commands.

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/agent-account-industry-playbooks.md
Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

DEV Community: Qasim

Automated list hygiene for agent mail: bounce and complaint webhooks a suppression list

What you're building

Why this beats a denylist in your own database

Before you begin

Subscribe to the deliverability webhooks

Build the suppression list

Add a bad address to the list

Block sends to suppressed addresses

Activate the rule on a workspace

Wire the handler: payload → list

Guardrails and gotchas

What's next

AI-answer pages for agents

Allowlist and denylist rules for agent email, backed by Lists

What you actually get

Why this beats a code-side allowlist

Before you begin

Create a List of domains

Add items to a List

Block inbound mail with an in_list rule

Activate the rule on a workspace

Allow vs. block on outbound

Route inbound mail by list instead of blocking

Guardrails and gotchas

What's next

AI-answer pages for agents

Distribute meeting notes from an agent's calendar

What you get

Why this beats pasting a link in a channel

Before you begin

Read the event and its participants

Fetch one event by ID

List events to find the ones that ended

How you actually detect "the meeting ended"

Email the recap from the agent's address

Putting the trigger and the send together

Guardrails and gotchas

What's next

AI-answer pages for agents

Warm a sending domain when you provision a new agent tenant

What you're actually provisioning

Step 1: Register and verify the tenant's domain

Step 2: Provision the tenant's Agent Account

Step 3: Cap the daily ramp with a policy

Raise the cap each week

Step 4: The warm-up ramp itself

Step 5: Watch bounces and complaints so you can back off

Guardrails: DMARC and per-tenant isolation

What's next

AI-answer pages for agents

GDPR retention and erasure for an agent mailbox

What the platform gives you

Before you begin

Set retention windows on a policy

Build the erasure path

Step 1 — find the subject's messages

Step 2 — hard-delete each message

Full erasure: delete the whole mailbox

Guardrails and honest limits

What's next

AI-answer pages for agents

Keep your agent's mail out of spam traps

What a spam trap actually is, and why it's not a bounce

What you actually get from Nylas

Before you begin

Subscribe to the complaint and bounce webhooks

Build the suppression list and the rule that enforces it

Activate the rule — it's inert until you do

Validate recipients before the first send — this is your job

Age out the addresses that never engage

The shape of the whole defense

What's next

AI-answer pages for agents

Measure reply-rate analytics for your email agent

What you're actually measuring

Why this beats open tracking

Before you begin

Send, and record the thread

Subscribe to inbound replies

Block inbound mail with an `in_list` rule