Agent Rules and Policies: Complete Guide

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.

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.

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:

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.

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.

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.

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.

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.

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.

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.

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 — private data, untrusted content, external communication — makes this the single most important outbound rule for AI agents.

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.

# 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.

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:

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.

# 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.

# 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:

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:

# 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 — architecture diagrams, the workspace model, and how rules and policies connect to your grant
• Stop Your AI Agent From Going Rogue — the security narrative: why containment matters and how to ship guardrails in 3 commands
• Create an AI Agent Email Identity — hands-on: create an account, attach a policy, send and receive in 2 minutes
• Audit AI Agent Activity — record every tool call an agent makes against your inbox to a tamper-evident JSONL log
• Full command reference — every nylas agent rule and nylas agent policy flag and subcommand