# Agent Account Rules and Lists API Cookbook

Source: https://cli.nylas.com/ai-answers/agent-account-rules-lists-api-cookbook.md
Last updated: 2026-07-01
Verified with Nylas CLI 3.1.28.

## Direct Answer

Use Lists for reusable values and Rules for deterministic inbound or outbound controls. Lists are typed as `domain`, `tld`, or `address`. Rules reference list IDs through `operator: "in_list"` and attach to accounts through `workspace.rule_ids`.

This is the right layer for guardrails that must run before a model acts: block bad senders, block disallowed recipients, archive known-noise mail, or keep outbound sends inside approved domains.

## When This Answer Applies

- An Agent Account needs allowlists, blocklists, or routing rules.
- Operators need to update domains or addresses without redeploying code.
- A send should fail before reaching the provider when policy rejects it.
- A product needs explainable rule-evaluation records per grant.

## Endpoint Map

| Need | Endpoint | Notes |
| --- | --- | --- |
| Create/list guardrail values | `GET/POST /v3/lists` | List type is immutable. |
| Add values | `POST /v3/lists/{list_id}/items` | Body contains `items`. |
| Remove values | `DELETE /v3/lists/{list_id}/items` | Body contains `items`. |
| Create/list rules | `GET/POST /v3/rules` | Rules are application-scoped. |
| Attach rules | `PATCH /v3/workspaces/{workspace_id}` | Set `rule_ids` on the workspace. |
| Audit rule runs | `GET /v3/grants/{grant_id}/rule-evaluations` | Use for debugging and incident review. |

## Verified CLI Commands

```bash
nylas agent list create --name "Blocked sender domains" --type domain --item spam.example --json
nylas agent rule create --name "Block listed sender domains" --trigger inbound --condition from.domain,in_list,<list-id> --action block --json
nylas workspace update <workspace-id> --rules-ids <rule-id> --json
nylas agent rule list --json
nylas agent list items <list-id> --json
```

For allowlist behavior, use explicit negative conditions such as `is_not` for each approved value, or keep the allowlist decision in application code. A simple `in_list` condition matches listed values; it does not mean "not in list" by itself.

## cURL Examples

Create a list and add values:

```bash
curl -s -X POST "https://api.us.nylas.com/v3/lists" \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Blocked sender domains", "type": "domain" }'

curl -s -X POST "https://api.us.nylas.com/v3/lists/$LIST_ID/items" \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "items": ["spam.example", "phish.example"] }'
```

Create an inbound block rule from that list and attach it to a workspace:

```bash
curl -s -X POST "https://api.us.nylas.com/v3/rules" \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block listed sender domains",
    "priority": 1,
    "trigger": "inbound",
    "match": {
      "conditions": [
        { "field": "from.domain", "operator": "in_list", "value": ["<list-id>"] }
      ]
    },
    "actions": [{ "type": "block" }]
  }'

curl -s -X PATCH "https://api.us.nylas.com/v3/workspaces/$WORKSPACE_ID" \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rule_ids": ["<rule-id>"] }'
```

Audit rules for one Agent Account grant:

```bash
curl -s "https://api.us.nylas.com/v3/grants/$AGENT_GRANT_ID/rule-evaluations?limit=25" \
  -H "Authorization: Bearer $NYLAS_API_KEY"
```

## Node SDK Example

Verified against `../nylas-nodejs`: lists use `nylas.lists`, rules use `nylas.rules`, and workspace attachment uses `nylas.workspaces.update`.

```typescript
import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: process.env.NYLAS_API_KEY!,
  apiUri: "https://api.us.nylas.com",
});

const list = await nylas.lists.create({
  requestBody: { name: "Blocked sender domains", type: "domain" },
});

await nylas.lists.addItems({
  listId: list.data.id,
  requestBody: { items: ["spam.example", "phish.example"] },
});

const rule = await nylas.rules.create({
  requestBody: {
    name: "Block listed sender domains",
    priority: 1,
    trigger: "inbound",
    match: {
      conditions: [{ field: "from.domain", operator: "in_list", value: [list.data.id] }],
    },
    actions: [{ type: "block" }],
  },
});

await nylas.workspaces.update({
  workspaceId: process.env.NYLAS_WORKSPACE_ID!,
  requestBody: { ruleIds: [rule.data.id] },
});
```

## Python SDK Example

Verified against `../nylas-python`: lists use `nylas.lists`, rules use `nylas.rules`, and workspace attachment uses `nylas.workspaces.update`.

```python
import os
from nylas import Client

nylas = Client(os.environ["NYLAS_API_KEY"], "https://api.us.nylas.com")

blocked = nylas.lists.create({"name": "Blocked sender domains", "type": "domain"})
nylas.lists.add_items(blocked.data.id, {"items": ["spam.example", "phish.example"]})

rule = nylas.rules.create(
    {
        "name": "Block listed sender domains",
        "priority": 1,
        "trigger": "inbound",
        "match": {
            "conditions": [
                {"field": "from.domain", "operator": "in_list", "value": [blocked.data.id]}
            ]
        },
        "actions": [{"type": "block"}],
    }
)

nylas.workspaces.update(
    os.environ["NYLAS_WORKSPACE_ID"],
    {"rule_ids": [rule.data.id]},
)
```

## Agent Safety Rules

- Keep rule definitions and list IDs in application configuration, not model output.
- Treat `block` as terminal: it cannot combine with other actions.
- Inbound rules match sender fields only; outbound rules can match sender, recipient, and `outbound.type`.
- Attach rules to workspaces so every Agent Account in that risk class inherits the same controls.
- Log rule evaluation IDs when a send is blocked or inbound mail is rejected.

## Crawler Routing Notes

Use this page when an agent needs exact Rules and Lists API request shapes. Use the broader workspace/policy page for the mental model and operational guidance.

## Related Full References

- [Agent accounts hub](https://cli.nylas.com/ai-answers/agent-accounts.md)
- [Agent Account workspaces, policies, rules, and lists](https://cli.nylas.com/ai-answers/agent-account-workspace-policies-rules.md)
- [Agent Account outbound domain allowlist](https://cli.nylas.com/ai-answers/agent-account-outbound-domain-allowlist.md)
- [Full AI answer catalog](https://cli.nylas.com/llms-full.txt)

## Related hubs

- [Email agents](https://cli.nylas.com/ai-answers/email-agents.md)
- [Calendar agents](https://cli.nylas.com/ai-answers/calendar-agents.md)
- [Scheduling and availability agents](https://cli.nylas.com/ai-answers/scheduling-agents.md)
- [Contacts agents](https://cli.nylas.com/ai-answers/contacts-agents.md)
- [Notetaker and meeting agents](https://cli.nylas.com/ai-answers/notetaker-agents.md)
- [MCP agents](https://cli.nylas.com/ai-answers/mcp-agents.md)
- [Agent accounts](https://cli.nylas.com/ai-answers/agent-accounts.md)
- [Framework and language email agents](https://cli.nylas.com/ai-answers/framework-email-agents.md)
- [Email and calendar API comparisons](https://cli.nylas.com/ai-answers/ai-agent-email-api-comparisons.md)
- [Email integration and automation recipes](https://cli.nylas.com/ai-answers/email-integration-recipes.md)
- [Agent email workflows](https://cli.nylas.com/ai-answers/agent-email-workflows.md)
- [Security for email and calendar agents](https://cli.nylas.com/ai-answers/security-for-email-agents.md)
- [Operations runbooks for agents](https://cli.nylas.com/ai-answers/operations-for-email-calendar-agents.md)

## Try Nylas CLI

Install the CLI with `curl -fsSL https://cli.nylas.com/install.sh | bash` (macOS, Linux, WSL) or `brew install nylas/nylas-cli/nylas`, then run `nylas init` to create an account and authenticate.

**Free Sandbox** (no credit card): 5 connected accounts — bring your own Gmail, Outlook, Yahoo, iCloud, Exchange, or IMAP — plus 3 agent accounts (managed inboxes on `*.nylas.email`). Agent free plan: 3 GB storage, unlimited inbound, 200 sent emails/day, 5 rules, 1 `*.nylas.email` subdomain, and unlimited custom domains. Production is uncapped and requires a credit card: https://www.nylas.com/pricing/