---
title: "List rule evaluations"
method: GET
path: "/v3/grants/{grant_id}/rule-evaluations"
tags: ["Rules"]
---

# List rule evaluations

`GET /v3/grants/{grant_id}/rule-evaluations`

Returns a paginated list of rule evaluation records for the specified grant. Each record captures
which rules were evaluated against an inbound message, SMTP envelope, or outbound send, the
normalized sender or recipient data that was matched, which rules matched, and which actions were
applied.

Rule evaluations are created automatically as inbound mail is processed and as outbound sends are
evaluated, and serve as an audit trail for the Rules engine. Records are returned in reverse
chronological order (most recent first).

## Query parameters

- `limit` integer
- `page_token` string

## Response `200`

OK

- object
  - `request_id` string — ID of the request.
  - `data` GrantRuleEvaluationObject[]
    - `id` string — Globally unique identifier for this evaluation record (UUID).
    - `grant_id` string — The grant this evaluation belongs to (UUID).
    - `message_id` string, nullable — The inbound message or stored sent copy associated with this evaluation (UUID). `null` when the evaluation happened before a message record existed, such as `smtp_rcpt`, or when an outbound evaluation did not persist a sent copy.
    - `evaluated_at` integer — When the evaluation occurred, in seconds using the Unix timestamp format.
    - `evaluation_stage` 'smtp_rcpt' | 'inbox_processing' | 'outbound_send' — Where in the processing pipeline the evaluation happened. `smtp_rcpt` means the evaluation ran during SMTP RCPT TO processing (before the message was accepted) — `message_id` is `null` in this case. `inbox_processing` means the evaluation ran after the message was accepted and during inbox processing — `message_id` is populated. `outbound_send` means the evaluation ran for an outbound send; `message_id` is populated when a sent copy was stored, and `null` when the send was blocked before storage or no sent copy was persisted.
    - `evaluation_input` object — The normalized sender, recipient, and send-type data that rules were matched against.
      - `from_address` string — The normalized sender email address.
      - `from_domain` string — The normalized domain portion of the sender address.
      - `from_tld` string — The normalized top-level domain of the sender address.
      - `recipient_addresses` string[] — Outbound recipient email addresses considered during rule evaluation.
      - `recipient_domains` string[] — Outbound recipient domains considered during rule evaluation.
      - `recipient_tlds` string[] — Outbound recipient top-level domains considered during rule evaluation.
      - `outbound_type` 'compose' | 'reply' — Outbound send classification used during rule evaluation.
    - `applied_actions` object — The actions that were applied as a result of matching rules. Only populated fields are returned — fields are **omitted** (not set to `false`) when the corresponding action was not applied.
      - `blocked` boolean — The inbound message or outbound send was blocked and not delivered. Terminal action.
      - `marked_as_spam` boolean — The message or stored sent copy was moved to the junk/spam folder.
      - `marked_as_read` boolean — The message or stored sent copy was automatically marked as read.
      - `marked_starred` boolean — The message or stored sent copy was automatically starred.
      - `archived` boolean — The message or stored sent copy was archived.
      - `trashed` boolean — The message or stored sent copy was moved to trash.
      - `folder_ids` string[] — IDs of the custom folders the message or stored sent copy was assigned to.
    - `matched_rule_ids` string[] — IDs of the rules that matched during this evaluation. Empty when no rules matched (for example, when rule execution ran but nothing applied).
    - `application_id` string — The application this evaluation belongs to (UUID). Read-only; derived from the authenticated API key.
    - `organization_id` string — The Nylas organization this evaluation belongs to (UUID). Read-only; derived from the authenticated API key.
    - `created_at` integer — When the evaluation record was created, in seconds using the Unix timestamp format.
    - `updated_at` integer — When the evaluation record was last updated, in seconds using the Unix timestamp format.
  - `next_cursor` string — A cursor for paginating through results. Present when there are more results; pass this value as `page_token` in the next request.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `429` — Rate Limit

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)