Tune spam detection for your agent mailbox Nylas introduced spam detection tuning for agent mailboxes, allowing developers to set per-agent spam sensitivity via a policy object with three knobs: DNSBL toggle, header-anomaly detection, and a spam_sensitivity dial. The policy attaches to a workspace, so every agent in that workspace inherits the same spam posture, enabling different thresholds for different classes of agents. The default spam settings on an agent mailbox are a guess. They might be too loose — phishing and junk land in your support agent's inbox and your model dutifully drafts a reply to a Nigerian prince. Or they're too aggressive — a customer's reply from a slightly-misconfigured small-business mail server gets flagged, and your "always reply within 5 minutes" SLA quietly breaks because the message never reached the agent. Most people building on top of an inbox treat spam as something the provider handles invisibly, and never touch it. That's fine for a human's inbox — a human sees the spam folder, eyeballs false positives, and corrects course. An autonomous agent doesn't. It acts on what arrives, and never notices what got filtered. So the spam threshold stops being a background convenience and becomes a parameter you actually have to set per agent. On Nylas Agent Accounts, you set it on a policy . The policy carries a spam detection block with three knobs — a DNSBL toggle, a header-anomaly toggle, and a spam sensitivity dial — and you attach that policy to a workspace so every agent in the workspace inherits the same spam posture. Different class of agent, different policy, different threshold. That's the whole idea, and it's what this post walks through. 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 both the raw API call and the CLI equivalent, because half the time I'm in a provisioning script and the other half I'm poking at a single workspace from a shell. Quick grounding, because it's easy to overthink this. An Agent Account is just a grant https://developer.nylas.com/docs/v3/agent-accounts/ with a grant id . Everything on the data plane — listing messages, reading bodies, sending — is the same grant-scoped API you'd use against any connected mailbox. Spam detection doesn't change any of that. It changes what arrives before your agent ever sees it. The control plane is three application-scoped resources: policies limits and spam settings , rules inbound/outbound match-and-act , and lists typed value collections rules reference . Spam tuning lives entirely on the policy . Rules are a separate lever — a block rule rejects a known-bad sender at SMTP, a mark as spam rule routes a match to junk — but those are exact-match decisions you make about specific senders. The spam detection block is the fuzzy, score-based filter that runs on everything . This post is about that fuzzy dial, not the rules. One more thing worth saying plainly: you don't attach a policy to a grant. You attach it to a workspace , and every Agent Account in that workspace inherits it. That indirection is the feature. It's how "tune spam per class of agent" becomes a real operation instead of a thousand individual settings. The spam detection object on a policy has exactly three fields. No more, no fewer — I checked the spec so you don't have to invent any. | Field | Type | Range | What it does | |---|---|---|---| use list dnsbl | boolean | true / false | Enables DNS-based block list DNSBL checking on inbound mail. The sender's IP gets looked up against block lists of known spam sources. | use header anomaly detection | boolean | true / false | Enables header-anomaly detection — catches malformed or forged headers that legitimate mail servers don't produce. | spam sensitivity | number float | 0.1 – 5.0 | The threshold dial. Higher is more aggressive more mail flagged as spam ; lower is more permissive more mail reaches the inbox . | A few honest notes on each, because the field names tell you what but not when to reach for them . use list dnsbl is cheap insurance against bulk spam from compromised hosts. The tradeoff is that DNSBLs occasionally list shared IPs or freshly-provisioned cloud ranges, so an agent that legitimately expects mail from senders on consumer ISPs or new infrastructure can see false positives. For a support agent receiving mail from real companies, leave it on. For an agent that ingests from a long tail of unknown small senders, watch your false-positive rate before you commit. use header anomaly detection is almost always safe to enable. Well-behaved mail servers produce well-formed headers; forged headers are a strong spam signal. The only place I'd think twice is if you're receiving from a known-janky internal system that mangles headers — but that's rare enough that "on" is a sensible default. spam sensitivity is the one you'll actually tune over time. The range is 0.1 to 5.0 , and the docs recommend starting at 1.0 and adjusting from there: go Here's how I think about the dial in practice. The right value depends entirely on the cost of each kind of mistake for that agent. Support-triage agent spam sensitivity ~ 1.5 , both toggles on . A missed legitimate customer email is expensive — it's a broken SLA. A little spam slipping through is cheap, because your triage logic should classify and ignore junk anyway. Bias toward permissive : you'd rather the agent see one spam message than miss one real one. Outreach / cold-send agent spam sensitivity ~ 2.5 , both toggles on . This agent emails strangers and the replies it cares about come from real prospects, but the inbox attracts auto-responders, bounce-backs, and opportunistic spam keyed off the From address. You can afford to be aggressive, because a dropped reply from a genuine prospect is rare and the noise volume is high. High-trust internal agent spam sensitivity ~ 0.5 , DNSBL maybe off . If an agent only ever receives mail from your own domains or a known set of partners, crank sensitivity down and consider turning DNSBL off entirely — you don't want a partner's misconfigured relay flagged, and the threat surface is tiny. Pair this with an inbound allow-list rule if you want belt-and-suspenders. None of these numbers are magic. They're starting points you move based on what you see in the agent's actual mail. The point is that one global default can't be right for all three at once — which is exactly why this is a per-policy setting. You need: Authorization: Bearer