Before: blocking a new spam domain meant editing a rule definition, reviewing the change, and redeploying config. After: it's one POST that appends a string to a list, and every rule referencing that list picks up the new value immediately — no rule edits, no deploy, and a support person can do it from a script.
That's the design idea behind Lists on Nylas Agent Accounts (currently in beta, along with the Policies and Rules they work with): separate the values from the logic. Rules describe what to do; lists hold the ever-changing who.
A list is a typed collection, and the type
is fixed at creation — immutable afterward:
| Type | Holds | Matches against |
|---|---|---|
domain |
||
Domain names (example.com ) |
||
from.domain , recipient.domain |
||
tld |
||
Top-level domains (com , xyz ) |
||
from.tld , recipient.tld |
||
address |
||
Full addresses (user@example.com ) |
||
from.address , recipient.address |
||
The typing isn't cosmetic. Values are validated on write — a domain
list rejects a full email address — which catches the classic operational error of pasting alice@example.com
into a domain blocklist and silently matching nothing. Values are also lowercased and trimmed on write, and duplicate additions are silently ignored, so your sync script doesn't need its own normalization or dedupe pass.
Create the list, fill it, reference it from a rule via the in_list
operator:
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" }'
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"] }'
curl --request POST \
--url "https://api.us.nylas.com/v3/rules" \
--header "Authorization: Bearer <NYLAS_API_KEY>" \
--header "Content-Type: application/json" \
--data '{
"name": "Block anything on our blocklist",
"trigger": "inbound",
"match": {
"conditions": [
{ "field": "from.domain", "operator": "in_list", "value": ["<LIST_ID>"] }
]
},
"actions": [{ "type": "block" }]
}'
The rule does nothing until a workspace references it in its rule_ids
array — that's how rules apply to the Agent Accounts inside the workspace. One in_list
condition can reference up to 10 lists, and from then on, list updates flow through with no further changes.
The classic blocklist. An inbound block
rule against a domain list, like the one above. Blocked mail is rejected at the SMTP level — never stored, never webhooked, never seen by your LLM.
The allowlist for sensitive inboxes. There's no not-in-list operator, so a list can't directly express "block everyone except members." For a small, stable set of trusted senders, build the inversion from is_not
conditions combined with the all
match operator — block fires only when the sender matches none of the allowed domains:
curl --request POST \
--url "https://api.us.nylas.com/v3/rules" \
--header "Authorization: Bearer <NYLAS_API_KEY>" \
--header "Content-Type: application/json" \
--data '{
"name": "Allowlist: block all but trusted senders",
"priority": 1,
"trigger": "inbound",
"match": {
"operator": "all",
"conditions": [
{ "field": "from.domain", "operator": "is_not", "value": "yourcompany.com" },
{ "field": "from.domain", "operator": "is_not", "value": "stripe.com" }
]
},
"actions": [{ "type": "block" }]
}'
A rule holds up to 50 conditions, which is plenty for an inbox that should only receive verification mail from a handful of services. Rules run in priority order (0–1000, lower first), so give this one a low number and let routing rules run behind it.
The TLD sweep. Junk campaigns cluster on cheap TLDs. A tld
list (xyz
, top
, and whatever this quarter's offender is) backed by a mark_as_spam
rule routes them to junk without maintaining hundreds of domain entries.
Outbound DLP. Lists work in both directions. A recipient.domain
rule with trigger: "outbound"
and a block
action stops your agent from emailing competitor domains, test domains that leaked into production data, or anywhere else on a do-not-contact list. Outbound recipient.*
matching covers To, CC, BCC, and SMTP envelope recipients — so a hidden BCC doesn't slip past the check. Blocked sends return HTTP 403 and no sent copy is stored.
in_list
simply stop matching its values. Rules don't break; they just match less. Audit your rules before deleting a list a block
depends on.block
rule, the message is blocked rather than passed — surfaced as a retryable 503
on sends or a 451
tempfail on inbound SMTP, with blocked_by_evaluation_error: true
in the audit record.GET /v3/grants/{grant_id}/rule-evaluations
shows every evaluation, what matched, and what action ran — your first stop when someone asks why a message was blocked.Example.COM
slipping past a lowercase entry.Can one list feed multiple rules? Yes, and it should. A single "blocked domains" list can back an inbound block
rule for one workspace and a mark_as_spam
rule for another. That's the whole point of separating values from logic — update the list once, every referencing rule follows.
How do different agents get different lists? Through workspaces. A rule applies only to workspaces that carry its ID in rule_ids
, so your sales agents' workspace can reference the do-not-contact rule while the support workspace skips it. Same lists, different rule wiring per agent group.
What's the practical size ceiling? Items load at up to 1,000 per request, so a 50,000-entry blocklist is 50 calls. Past that scale, prefer tld
lists and DNSBL-based spam detection on the policy to brute-force domain enumeration.
The Policies, Rules, and Lists guide has the full schemas and the workspace attachment flow.
A worthwhile starting move: export the sender domains from your agent's last month of inbound mail, sort by volume, and you'll usually find your first blocklist (and sometimes your entire allowlist) staring back at you. Which pattern fits your agent — open inbox with a blocklist, or locked-down inbox with an allowlist?