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 inbound rules. One policy can apply to many Agent Accounts.
Rules match inbound mail and outbound sends using sender fields, recipient fields, and outbound.type, then run actions like block, mark_as_spam, assign_to_folder, archive, or trash.
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 mail. 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.
Stop sends to the wrong recipients. An outbound block rule rejects a send before it reaches the email provider — useful for data-loss prevention, catching test domains that slipped into production, or keeping an agent from emailing competitors.
Organize the sent side automatically. Archive or auto-star outbound mail based on recipient domain so the sent copy lands where you expect.
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 for inbound processing. An Agent Account gets a policy_id on its grant, which pulls in those limits and inbound rules 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	A `trigger` (`inbound` or `outbound`), match conditions, and actions (`block`, `mark_as_spam`, `assign_to_folder`, and more)	By ID, in a policy’s `rules` array for inbound processing. Outbound sends evaluate enabled outbound rules for the application.
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 inbound rule in priority order (lowest number first), and applies the matching actions. When the account issues a send, Nylas evaluates the application’s enabled outbound rules before handing the message to the provider. Inbound and outbound rules are isolated: inbound rules never run during sends, and outbound rules never run on receipt, so the stored sent copy isn’t re-evaluated against inbound rules. 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 during inbound processing.

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 a message — either on the way in, or on the way out. It has:

A trigger of inbound (runs on received mail) or outbound (runs on sends before they reach the email provider). Defaults to inbound.
Match conditions on fields valid for that trigger, combined with operators is, is_not, contains, or in_list.
An operator (all or any) for combining multiple conditions with AND or OR. If you omit it, the rule defaults to all.
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 and can’t be combined with other actions — for inbound rules it rejects the message at the SMTP level, for outbound rules it rejects the send with HTTP 403 before it reaches the provider.

Condition fields

Which fields you can match depends on the trigger. Inbound rules accept only from.*. Outbound rules can match from.*, recipient.*, and outbound.type.

Field	Trigger	What it matches	Valid operators
`from.address`	inbound, outbound	The full sender email address	`is`, `is_not`, `contains`, `in_list`
`from.domain`	inbound, outbound	The sender’s domain	`is`, `is_not`, `contains`, `in_list`
`from.tld`	inbound, outbound	The sender’s top-level domain	`is`, `is_not`, `contains`, `in_list`
`recipient.address`	outbound	Any recipient address — To, CC, BCC, and SMTP envelope recipients	`is`, `is_not`, `contains`, `in_list`
`recipient.domain`	outbound	The domain of any recipient	`is`, `is_not`, `contains`, `in_list`
`recipient.tld`	outbound	The top-level domain of any recipient	`is`, `is_not`, `contains`, `in_list`
`outbound.type`	outbound	`compose` for brand-new messages, `reply` for replies to existing threads	`is`, `is_not` only

recipient.* fields match against any recipient, which includes BCC and SMTP envelope recipients — useful when you want DLP coverage that catches hidden recipients. is_not is only true when no recipient matches the value. String matching is case-insensitive.

outbound.type is classified as reply when the send request includes reply_to_message_id, or when the raw MIME contains In-Reply-To or References headers. Everything else is compose. Values are normalized to lowercase on write.

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,
    "trigger": "inbound",
    "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 inbound rule to a policy

Policy linkage controls inbound rule evaluation on Agent Accounts.

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",
    "trigger": "inbound",
    "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" }
    ]
  }'

Outbound rules

Outbound rules run when the agent account issues a send. They evaluate before the message is handed off to the provider, so a block action short-circuits delivery entirely — the API returns 403 and no sent copy is created. Non-blocking actions (mark_as_spam, archive, mark_as_read, mark_as_starred, assign_to_folder, trash) apply to the stored sent copy once the send succeeds, not to what the recipient receives.

Block outbound mail to a domain

Useful for data-loss prevention, test domains, or hard-coded competitor blocks.

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 outbound to example.net",
    "trigger": "outbound",
    "match": {
      "conditions": [
        { "field": "recipient.domain", "operator": "is", "value": "example.net" }
      ]
    },
    "actions": [
      { "type": "block" }
    ]
  }'

Archive sent copies to a specific vendor

Keeps automated correspondence out of the main sent folder by archiving and marking the sent copy read.

curl --request POST \
  --url "https://api.us.nylas.com/v3/rules" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Archive sent copies to vendor domain",
    "trigger": "outbound",
    "match": {
      "conditions": [
        { "field": "recipient.domain", "operator": "is", "value": "vendor.example" }
      ]
    },
    "actions": [
      { "type": "archive" },
      { "type": "mark_as_read" }
    ]
  }'

Match only replies with `outbound.type`

Narrow an outbound rule to replies, or to brand-new messages, without looking at recipients at all. The outbound.type field takes one of two values: reply when the send is part of an existing thread, or compose when it’s a brand-new message.

curl --request POST \
  --url "https://api.us.nylas.com/v3/rules" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Star outbound replies",
    "trigger": "outbound",
    "match": {
      "conditions": [
        { "field": "outbound.type", "operator": "is", "value": "reply" }
      ]
    },
    "actions": [
      { "type": "mark_as_starred" }
    ]
  }'

A send is classified as a reply when the API request includes reply_to_message_id or the raw MIME carries In-Reply-To or References. Everything else is compose. outbound.type supports only is and is_not — contains and in_list are rejected.

Rule limits

Rules have fixed caps. Requests that exceed any of these are rejected with a validation error:

50 conditions per rule.
20 actions per rule.
10 lists referenced per in_list condition.
500 characters per condition value string.

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`, `recipient.domain`
`tld`	Top-level domains (`com`, `xyz`)	`from.tld`, `recipient.tld`
`address`	Full email addresses (`[email protected]`)	`from.address`, `recipient.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",
    "trigger": "inbound",
    "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, SMTP envelope, or outbound send 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, or outbound_send for send-time evaluation), the normalized sender or recipient data that was considered (from_address, from_domain, from_tld, recipient_addresses, recipient_domains, recipient_tlds, and outbound_type), the IDs of any matched rules, and the actions that were applied (blocked, marked_as_spam, archived, folder_ids, and so on). For outbound_send, message_id is populated when a sent copy was stored; it is null when the send was blocked before storage or when no sent copy was persisted. 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).
Pick the right trigger. inbound rules only see received mail; outbound rules only see sends. Don’t try to use inbound rules to filter what the agent sends, or vice versa — they’re isolated on purpose.
Handle 403 from sends. An outbound block rule returns 403 and no sent copy is stored. Your application should treat it like any delivery failure — there’s no retry path that will deliver it.
Outbound actions modify the sent copy. mark_as_spam, archive, mark_as_read, assign_to_folder, and friends affect only what’s stored in the agent’s sent folder. They don’t change what the recipient receives.
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