Policies, Rules, and Lists

Agent Accounts ship with three admin-scoped resources that control how mail is handled on the account level:

Policies bundle limits, spam settings, and linked rules. One policy can apply to many Agent Accounts.
Rules match inbound messages by sender and run actions (block, mark_as_spam, assign_to_folder, and more).
Lists are typed collections of domains, TLDs, or addresses that rules reference through the in_list operator.

All three are application-scoped. You create them once and reference them by ID on the grants you provision — they have no grant ID in the path; your API key identifies the application.

You can inspect existing policies and rules from the Nylas CLI with nylas agent policy list and nylas agent rule list. Creation and updates currently go through the API.

When to use them

Policies, Rules, and Lists are optional. An Agent Account works out of the box with sensible plan defaults for send rate, storage, retention, and spam detection — you only need these resources when you want to customize that behavior or filter inbound messages. Reach for them when you need to:

Customize limits per agent or customer. Different send quotas, storage caps, or retention windows for different Agent Accounts — for example, stricter limits on prototype accounts, higher quotas on a production sales agent.
Tune spam handling. Enable DNSBL checks and header anomaly detection, or turn the sensitivity dial up or down for a particular class of agent.
Reject known-bad senders at SMTP. A block rule rejects the message before it’s ever delivered to the mailbox, so your application never sees it.
Route inbound mail automatically. Move newsletters to a folder, auto-star mail from key customers, archive or trash noise without writing any application code.
Maintain dynamic allow/block lists. A List fronted by a Rule lets non-engineers update who’s allowed or blocked without touching rule definitions or redeploying anything.

If none of these apply, skip this page — your Agent Accounts will use plan defaults and deliver every inbound message to the inbox.

How the pieces fit together

The three resources form a chain. Lists hold values. Rules reference lists (via the in_list operator) and describe conditions and actions. Policies bundle limits and a set of linked rule IDs. An Agent Account gets a policy_id on its grant, which pulls in every rule and limit at once.

Resource	What it owns	How it’s referenced
List	A typed collection of domains, TLDs, or email addresses	By ID, from a rule condition’s `value` (when `operator` is `in_list`)
Rule	Match conditions on `from.address`, `from.domain`, or `from.tld` and actions (`block`, `mark_as_spam`, `assign_to_folder`, and more)	By ID, in a policy’s `rules` array
Policy	Limits, spam detection settings, options, and the rule IDs it applies	By ID, in a grant’s `settings.policy_id`
Agent Account	The grant itself	`settings.policy_id` on `POST /v3/connect/custom`

When a message arrives for an Agent Account, Nylas looks up the grant’s policy_id, evaluates each linked rule in priority order (lowest number first), and applies the first matching action. Limits on the policy govern what the account can send and store.

Policies

A policy is the configuration you reuse across many Agent Accounts. It contains:

Limits — attachment size and count, allowed MIME types, total message size, per-account storage, daily send quotas, and inbox/spam retention.
Spam detection — DNSBL checking, header anomaly detection, and a spam_sensitivity dial (0.1–5.0; higher is more aggressive).
Options — additional folders to auto-create, CIDR-based email aliasing.
Rules — the array of Rule IDs that apply to grants using this policy.

Every limit is optional. If you omit one, it defaults to your plan’s maximum. If you request a value above the plan maximum, the API returns an error.

Create a policy

curl --request POST \
  --url "https://api.us.nylas.com/v3/policies" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Standard Agent Account Policy",
    "limits": {
      "limit_attachment_size_limit": 26214400,
      "limit_attachment_count_limit": 50,
      "limit_inbox_retention_period": 365,
      "limit_spam_retention_period": 30
    },
    "spam_detection": {
      "use_list_dnsbl": true,
      "use_header_anomaly_detection": true,
      "spam_sensitivity": 1.5
    }
  }'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "id": "b1c2d3e4-5678-4abc-9def-0123456789ab",
    "name": "Standard Agent Account Policy",
    "limits": {
      "limit_attachment_size_limit": 26214400,
      "limit_attachment_count_limit": 50,
      "limit_inbox_retention_period": 365,
      "limit_spam_retention_period": 30
    },
    "spam_detection": {
      "use_list_dnsbl": true,
      "use_header_anomaly_detection": true,
      "spam_sensitivity": 1.5
    },
    "rules": [],
    "created_at": 1742932766,
    "updated_at": 1742932766
  }
}

Apply a policy to an Agent Account

Pass policy_id in settings when you create the grant.

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": "[email protected]",
      "policy_id": "<POLICY_ID>"
    }
  }'

You can change the policy on an existing grant by updating its settings.policy_id. If policy_id is unset, the grant inherits the policy_id configured on the application’s nylas connector, if any.

For the complete policy schema, see the Policies API reference.

Rules

A rule decides what to do with an inbound message. It has:

Match conditions against from.address, from.domain, or from.tld using the operators is, is_not, contains, or in_list.
An operator (all or any) for combining multiple conditions with AND or OR.
Actions that run when the match hits: block, mark_as_spam, assign_to_folder, mark_as_read, mark_as_starred, archive, or trash.

Rules run in priority order (lower numbers first; range 0–1000, default 10). The block action is terminal — it rejects the message at the SMTP level and can’t be combined with other actions.

Block a known spam domain

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 spam-domain.com",
    "priority": 1,
    "match": {
      "conditions": [
        { "field": "from.domain", "operator": "is", "value": "spam-domain.com" }
      ]
    },
    "actions": [
      { "type": "block" }
    ]
  }'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "id": "c1d2e3f4-5678-4abc-9def-0123456789ab",
    "name": "Block spam-domain.com",
    "priority": 1,
    "enabled": true,
    "trigger": "inbound",
    "match": {
      "operator": "all",
      "conditions": [
        { "field": "from.domain", "operator": "is", "value": "spam-domain.com" }
      ]
    },
    "actions": [{ "type": "block" }],
    "created_at": 1742932766,
    "updated_at": 1742932766
  }
}

Link the rule to a policy

curl --request PUT \
  --url "https://api.us.nylas.com/v3/policies/<POLICY_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "rules": ["<RULE_ID>"]
  }'

Route newsletters to a folder

Combine multiple conditions with operator: "any" (OR) and pair actions — an assign_to_folder action with a mark_as_read action.

curl --request POST \
  --url "https://api.us.nylas.com/v3/rules" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Newsletters → Reading folder",
    "match": {
      "operator": "any",
      "conditions": [
        { "field": "from.address", "operator": "contains", "value": "newsletter@" },
        { "field": "from.domain", "operator": "contains", "value": "substack.com" }
      ]
    },
    "actions": [
      { "type": "assign_to_folder", "value": "<READING_FOLDER_ID>" },
      { "type": "mark_as_read" }
    ]
  }'

For the full rule schema, see the Rules API reference.

Lists

A list is a typed collection of values that rules match against via the in_list operator. Use lists when a rule’s allow/block values change over time — update the list and every rule that references it picks up the new values immediately.

Each list has a fixed type, set at creation and immutable:

Type	Values it holds	Rule field it matches
`domain`	Domain names (`example.com`)	`from.domain`
`tld`	Top-level domains (`com`, `xyz`)	`from.tld`
`address`	Full email addresses (`[email protected]`)	`from.address`

Values are lowercased and trimmed on write, and validated against the list’s type. For example, a domain list rejects full email addresses. Duplicate additions are silently ignored.

Create a list

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

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

Add items to a list

Add up to 1000 items per request.

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

Reference a list from a rule

Use "operator": "in_list" and pass one or more List IDs as value.

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",
    "match": {
      "conditions": [
        {
          "field": "from.domain",
          "operator": "in_list",
          "value": ["<LIST_ID>"]
        }
      ]
    },
    "actions": [
      { "type": "block" }
    ]
  }'

Deleting a list cascades to its items, and rules that reference the list through in_list stop matching its values after deletion. For the full list schema, see the Lists API reference.

Audit which rules ran

Every time the rule engine evaluates an inbound message (or SMTP envelope) for an Agent Account, Nylas records an audit entry. Use GET /v3/grants/{grant_id}/rule-evaluations to list those entries, most recent first — it’s the fastest way to answer “why did this message get blocked / routed / marked?” for a specific grant.

Each record includes the evaluation stage (smtp_rcpt if the message was rejected before acceptance, inbox_processing if it was evaluated post-acceptance), the sender data that was considered (from_address, from_domain, from_tld), the IDs of any matched rules, and the actions that were applied (blocked, marked_as_spam, archived, folder_ids, and so on). Cross-reference matched_rule_ids with the Rules API to see the conditions each matching rule was built from.

Keep in mind

Order rules carefully. Lower priority runs first, and the first matching block action is terminal. Put specific rules (is, in_list against a small list) before broad ones (contains).
Prefer lists over inline values when the set is likely to grow. One list can feed many rules and be updated without touching rule definitions.
Start with spam_sensitivity: 1.0 and tune from there. Go up if spam is slipping through; go down if legitimate mail is getting marked.
Set both retention values. limit_spam_retention_period must be shorter than limit_inbox_retention_period, so spam clears out ahead of the inbox.
Use separate policies per agent archetype. A sales-outreach agent and a support-triage agent have different send limits and spam tolerances — model them as separate policies rather than one catch-all.

What’s next

Policies API reference for the full endpoint documentation
Rules API reference for every condition operator, action, and field
Lists API reference for list and list-item management
BYO Auth reference — nylas provider for passing policy_id when you create an Agent Account
Provisioning and domains to create Agent Accounts against a registered domain