Source: https://cli.nylas.com/guides/agent-rules-and-policies

# Agent Rules and Policies: Complete Guide

Your agent account can send and receive email. Without rules and policies, it has no guardrails. This guide is the complete reference: every trigger, condition field, operator, action, and policy setting available on the agent surface. Covers inbound filtering, outbound controls, priority ordering, send limits, spam detection, and real-world rule patterns.

Written by [Nick Barraclough](https://cli.nylas.com/authors/nick-barraclough) Product Manager

Reviewed by [Pouya Sanooei](https://cli.nylas.com/authors/pouya-sanooei)

Updated May 25, 2026

> **TL;DR:** Rules are condition-action pairs that filter your agent's inbound and outbound email. Policies set send limits, attachment caps, and spam sensitivity. Together they form the guardrail layer that a prompt injection cannot bypass. This guide covers every primitive — for the security narrative, see [Stop Your AI Agent From Going Rogue](https://cli.nylas.com/guides/stop-ai-agent-going-rogue).

## What are agent rules and policies?

Agent rules are deterministic condition-action pairs that intercept your agent's email before the agent sees it. Each rule has a trigger (inbound or outbound), one or more conditions (match on sender domain, recipient address, or message type), and one or more actions (block, archive, mark as read, star, or trash). Rules evaluate in priority order — lower numbers fire first — and they execute at the workspace layer, outside the agent's decision loop.

Policies are the container that holds send limits, attachment constraints, spam detection settings, and inbox retention periods. Your agent account's workspace references one policy and one or more rules. The CLI creates, lists, and manages both through the `nylas agent rule` and `nylas agent policy` command surfaces. For the architecture behind how workspaces connect these to your grant, see [Getting Started with Agent Accounts](https://cli.nylas.com/guides/getting-started-agent-accounts).

## What does a rule look like?

Every rule has 3 parts: a trigger that decides when it fires, conditions that decide what it matches, and actions that decide what it does. The CLI lets you build rules from flags (for common cases) or from JSON (for anything more complex). A single rule can have multiple conditions combined with `all` (every condition must match) or `any` (at least one must match), and multiple actions that all fire when the conditions are met.

Anatomy of a rule: trigger plus conditions plus actionsTriggerinbound or outboundConditionsfield, operator, value (match all or any)Actionsblock, archive, mark_as_read, star, trashwhen does it fire?what does it match?what does it do?Rules evaluate in priority order (lower number = fires first)

The `nylas agent rule create` command accepts the 3 parts as repeatable flags. The defaults when creating from flags are: `trigger=inbound`, `enabled=true`, and `match.operator=all`. A simple rule that blocks a domain takes one command and completes in under 2 seconds:

```bash
nylas agent rule create \
  --name "Block spam domain" \
  --condition from.domain,is,spam-sender.com \
  --action block
```

## What triggers are available?

Agent rules support 2 triggers that determine when the rule evaluates: inbound (when email arrives at your agent's address) and outbound (when your agent sends email). Inbound is the default. Each trigger exposes different condition fields — outbound rules can match on recipient fields and message type that inbound rules cannot.

| Trigger | When it fires | Available condition fields |
| --- | --- | --- |
| `inbound` | Email arrives at your agent's address | `from.address`, `from.domain`, `from.tld` |
| `outbound` | Your agent sends email | `from.*`, `recipient.address`, `recipient.domain`, `recipient.tld`, `outbound.type` |

The `outbound.type` field distinguishes between new messages (`compose`) and replies (`reply`). This lets you write rules like "archive all outbound replies to a specific domain" without affecting new sends.

## What conditions can a rule match on?

Conditions are the matching logic that decides whether a rule fires. Each condition is a triple of field, operator, and value — written as `field,operator,value` in the `--condition` flag. You can repeat `--condition` for multiple conditions and combine them with `--match-operator all|any`.

| Field | Operators | Example |
| --- | --- | --- |
| `from.address` | `is`, `is_not`, `contains`, `in_list` | `from.address,is,ceo@example.com` |
| `from.domain` | `is`, `is_not`, `contains`, `in_list` | `from.domain,is,example.com` |
| `from.tld` | `is`, `is_not`, `contains`, `in_list` | `from.tld,is,ru` |
| `recipient.address` | `is`, `is_not`, `contains`, `in_list` | `recipient.address,is,user@example.com` |
| `recipient.domain` | `is`, `is_not`, `contains`, `in_list` | `recipient.domain,in_list,safe.com,trusted.org` |
| `recipient.tld` | `is`, `is_not`, `contains`, `in_list` | `recipient.tld,is_not,com` |
| `outbound.type` | `is`, `is_not` | `outbound.type,is,compose` |

The `in_list` operator lets you match against multiple values in one condition. Pass comma-separated values after the operator: `from.domain,in_list,example.com,example.org,example.net`. This handles what would otherwise take 3 separate rules in a single condition.

## What actions can a rule take?

Actions determine what happens when a rule's conditions match. Every rule must have at least one action, and you can combine multiple actions on a single rule — for example, `mark_as_read` and `mark_as_starred` together on a VIP sender rule. There are 7 available actions, each covering a different email handling pattern.

| Action | What it does | Flag syntax |
| --- | --- | --- |
| `block` | Rejects the message entirely | `--action block` |
| `mark_as_spam` | Flags the message as spam | `--action mark_as_spam` |
| `archive` | Moves the message out of the inbox | `--action archive` |
| `trash` | Moves the message to trash | `--action trash` |
| `mark_as_read` | Marks as read without moving | `--action mark_as_read` |
| `mark_as_starred` | Stars or flags the message | `--action mark_as_starred` |
| `assign_to_folder` | Routes to a named folder | `--action assign_to_folder=vip` |

## What do real-world rules look like?

Here are 5 practical rules that cover the most common agent email patterns. Each one uses the flag syntax and completes in under 2 seconds. These patterns work with any agent account — you don't need to modify them beyond swapping the domain or address values.

**Block a spam domain (inbound).** Any email from `spam-sender.com` is rejected before your agent sees it. The `block` action is terminal — the message never reaches the inbox.

```bash
nylas agent rule create \
  --name "Block spam domain" \
  --condition from.domain,is,spam-sender.com \
  --action block
```

**Star VIP senders (inbound).** Messages from your CEO get marked as read and starred simultaneously. Two actions on one rule — the agent's inbox shows only the starred flag, reducing noise for automated processing.

```bash
nylas agent rule create \
  --name "VIP sender" \
  --condition from.address,is,ceo@example.com \
  --action mark_as_read \
  --action mark_as_starred
```

**Block multiple TLDs (inbound).** The `in_list` operator matches against multiple values in a single condition. This rule blocks email from 3 TLDs in one pass instead of requiring 3 separate rules.

```bash
nylas agent rule create \
  --name "Block suspicious TLDs" \
  --condition from.tld,in_list,xyz,top,buzz \
  --action block
```

**Archive outbound replies to a domain (outbound).** When your agent replies to anyone at `example.com`, the sent message is archived automatically. The `outbound.type,is,reply` condition ensures new composes are unaffected.

```bash
nylas agent rule create \
  --name "Archive outbound replies" \
  --trigger outbound \
  --condition recipient.domain,is,example.com \
  --condition outbound.type,is,reply \
  --action archive
```

**Allowlist outbound domains (outbound).** This rule restricts your agent to send only to trusted domains. The `is_not` operator combined with `--match-operator any` blocks any outbound email to an unlisted domain. Simon Willison's [lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) — private data, untrusted content, external communication — makes this the single most important outbound rule for AI agents.

```bash
nylas agent rule create \
  --name "Outbound allowlist" \
  --trigger outbound \
  --match-operator any \
  --condition recipient.domain,is_not,trusted.com \
  --condition recipient.domain,is_not,internal.org \
  --action block
```

## How does rule priority work?

Rules evaluate in priority order: the rule with the lowest priority number fires first. If two rules match the same message, the lower-numbered rule's action takes precedence. The default priority when you omit `--priority` is 0. Set explicit priorities when you have rules that could conflict — for example, a `block` rule at priority 1 and a `mark_as_starred` rule at priority 10 ensures blocking fires before starring.

```bash
# Priority 1: block fires first
nylas agent rule create \
  --name "Block attacker domain" \
  --priority 1 \
  --condition from.domain,is,attacker.com \
  --action block

# Priority 10: star fires second (only if not blocked)
nylas agent rule create \
  --name "Star known senders" \
  --priority 10 \
  --condition from.domain,in_list,partner.com,vendor.org \
  --action mark_as_starred
```

## What settings does a policy control?

A policy is the container that holds your agent's operational constraints. While rules handle per-message filtering, policies set account-level limits: how many messages per day, maximum attachment size, inbox retention, and spam detection sensitivity. Create a policy with `nylas agent policy create` and attach it to your agent account at creation time with `--policy-id`.

| Setting | What it controls | Example value |
| --- | --- | --- |
| `limit_count_daily_message_per_grant` | Max outbound messages per day | **500** |
| `limit_attachment_size_limit` | Max attachment size in bytes | **50,480,000 (50 MB)** |
| `limit_attachment_count_limit` | Max attachments per message | **10** |
| `limit_inbox_retention_period` | Days to retain inbox messages | **30** |
| `limit_spam_retention_period` | Days to retain spam messages | **7** |
| `spam_sensitivity` | Spam detection threshold (0 to 1) | **1 (strictest)** |
| `use_cidr_aliasing` | Enable CIDR-based address aliasing | **false** |

The `limit_count_daily_message_per_grant` setting is the most critical for AI agents. Without it, a prompt injection that triggers a send loop has no ceiling. Here's what a production policy looks like — your agent is sending customer receipts, and you want a 500/day cap with 50 MB attachment limits and strict spam filtering:

```bash
nylas agent policy create --data '{
  "name": "Production receipts",
  "limits": {
    "limit_count_daily_message_per_grant": 500,
    "limit_attachment_size_limit": 50480000,
    "limit_attachment_count_limit": 10,
    "limit_inbox_retention_period": 30,
    "limit_spam_retention_period": 7
  },
  "spam_detection": {
    "spam_sensitivity": 1
  }
}'
```

## How do you manage rules and policies day to day?

After creating your initial rules and policy, you'll need to list, inspect, update, and occasionally delete them. The CLI provides a consistent CRUD surface for both. Every command supports `--json` output for scripting. All mutations complete in under 2 seconds.

```bash
# List rules on your default agent account
nylas agent rule list

# List all rules across all agent accounts
nylas agent rule list --all

# Inspect a specific rule (read and get are aliases)
nylas agent rule read <rule-id> --json

# Update a rule's name and priority
nylas agent rule update <rule-id> --name "Updated name" --priority 5

# Replace a rule's conditions and actions
nylas agent rule update <rule-id> \
  --condition from.domain,is,new-domain.com \
  --action archive

# Delete a rule (requires --yes)
nylas agent rule delete <rule-id> --yes

# List, inspect, update, and delete policies
nylas agent policy list --all
nylas agent policy read <policy-id> --json
nylas agent policy update <policy-id> --name "Renamed policy"
nylas agent policy delete <policy-id> --yes
```

Two safety guards protect against accidental breakage. First, you can't delete a rule if it would leave your workspace with zero live rules. Second, you can't delete a policy that's still attached to an agent account's workspace. Detach or rotate the policy before deleting.

## How do you create rules from JSON?

The flag syntax covers most cases, but complex rules with nested conditions or multiple action values are easier to express in JSON. The CLI accepts inline JSON with `--data` or a file path with `--data-file`. The recommended workflow takes 3 steps and under 30 seconds: read the current state, edit the JSON, and push the update.

```bash
# 1. Export current rule as JSON
nylas agent rule read <rule-id> --json > rule.json

# 2. Edit rule.json in your editor

# 3. Push the update
nylas agent rule update <rule-id> --data-file rule.json
```

For creating a new rule from scratch, the full JSON structure looks like this. Every field is explicit — no defaults are assumed when using `--data`:

```bash
nylas agent rule create --data '{
  "name": "Block example domain",
  "enabled": true,
  "trigger": "inbound",
  "match": {
    "operator": "all",
    "conditions": [
      {
        "field": "from.domain",
        "operator": "is",
        "value": "example.com"
      }
    ]
  },
  "actions": [
    { "type": "block" }
  ]
}'
```

## What do you do when rules don't work?

The most common issue is `nylas agent rule list` returning empty results. This usually means one of 3 things: your default grant isn't a managed agent account, the workspace doesn't have rules attached, or the workspace references rules that were deleted. Start diagnosis with these 3 commands:

```bash
# 1. Confirm your default grant is a managed agent account
nylas auth list

# 2. Check if any rules exist across all agent accounts
nylas agent rule list --all

# 3. Inspect the agent account's workspace linkage
nylas agent account get
```

If `nylas agent rule delete` is rejected, either the rule is shared outside the current agent scope, or deleting it would leave the workspace with zero live rules. Attach another rule first, then retry the delete.

## Next steps

- [Getting Started with Agent Accounts](https://cli.nylas.com/guides/getting-started-agent-accounts) — architecture diagrams, the workspace model, and how rules and policies connect to your grant
- [Stop Your AI Agent From Going Rogue](https://cli.nylas.com/guides/stop-ai-agent-going-rogue) — the security narrative: why containment matters and how to ship guardrails in 3 commands
- [Create an AI Agent Email Identity](https://cli.nylas.com/guides/create-ai-agent-email-identity) — hands-on: create an account, attach a policy, send and receive in 2 minutes
- [Audit AI Agent Activity](https://cli.nylas.com/guides/audit-ai-agent-activity) — record every tool call an agent makes against your inbox to a tamper-evident JSONL log
- [Full command reference](https://cli.nylas.com/docs/commands) — every `nylas agent rule` and `nylas agent policy` flag and subcommand