DEV Community

Qasim
Qasim

Posted on

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

#api #email #devtools #productivity

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:

  1. Deliverability webhooks (message.bounced, message.complaint) tell you which addresses went bad, in real time.
  2. A suppression List of type address holds those bad addresses.
  3. An outbound block rule matches recipient.address in_list <suppression-list> and rejects any send to a suppressed address before it leaves the building.
  4. 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"
  }'
Enter fullscreen mode Exit fullscreen mode

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"
  }'
Enter fullscreen mode Exit fullscreen mode

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
  }
}
Enter fullscreen mode Exit fullscreen mode

CLI:

nylas agent list create --name "Suppressed addresses" --type address
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"]
  }'
Enter fullscreen mode Exit fullscreen mode

CLI:

nylas agent list add <LIST_ID> jane@example.com
Enter fullscreen mode Exit fullscreen mode

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" }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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>"]
  }'
Enter fullscreen mode Exit fullscreen mode

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

nylas workspace update <WORKSPACE_ID> --rules-ids <RULE_ID>
Enter fullscreen mode Exit fullscreen mode

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" }
        ]
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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"]
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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 }
Enter fullscreen mode Exit fullscreen mode

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>"
Enter fullscreen mode Exit fullscreen mode
  • 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

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:

Top comments (0)