# Automated list hygiene for agent mail: bounce and complaint webhooks a suppression list > Source: > Published: 2026-07-12 15:19:51+00:00 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. The whole thing is a four-piece loop: `message.bounced` , `message.complaint` ) tell you which addresses went bad, in real time.`address` holds those bad addresses.`recipient.address in_list ` and rejects any send to a suppressed address before it leaves the building.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. You could absolutely keep a `suppressed_emails` table and check it before every send. People do. Here's why I don't: 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. You need: `provider: "nylas"` ) on a verified domain. If you don't have one, see `NYLAS_API_KEY` and the API base host. Examples here use `https://api.us.nylas.com` .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. 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 " \ --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. 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 " \ --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 ``` 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//items" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "items": ["jane@example.com"] }' ``` CLI: ``` nylas agent list add 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. 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 " \ --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": [""] } ] }, "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, \ --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. 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/" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "rule_ids": [""] }' ``` CLI — the flag is `--rules-ids` (comma-separated): ``` nylas workspace update --rules-ids ``` 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. 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": "", "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": "", "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//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. A few things I'd want a teammate to know before shipping this: `403` on send.`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.`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.`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.`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//rule-evaluations?limit=50" \ --header "Authorization: Bearer " ``` `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.`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. When this post is published, link AI agents and crawlers to the retrieval-ready version on `cli.nylas.com` :