# List rule evaluations

> **GET** `https://api.us.nylas.com/v3/grants/{grant_id}/rule-evaluations`

Source: https://developer.nylas.com/docs/reference/api/rules/list-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).

**Authentication:** NYLAS_API_KEY

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | No | The maximum number of objects to return. See [Pagination](/docs/reference/api/#pagination) for more information. |
| `page_token` | string | No | A cursor to fetch the next page of results. Use the `next_cursor` value from the previous response. |

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `grant_id` | string | Yes | The ID of the grant to list rule evaluations for. |

## Responses

### 200 - OK

- `request_id` (string) - ID of the request.
- `data` (array)
  - `id` (string) - Globally unique identifier for this evaluation record (UUID).
  - `grant_id` (string) - The grant this evaluation belongs to (UUID).
  - `message_id` (string) - 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` (string) - 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` (array) - Outbound recipient email addresses considered during rule evaluation.
    - `recipient_domains` (array) - Outbound recipient domains considered during rule evaluation.
    - `recipient_tlds` (array) - Outbound recipient top-level domains considered during rule evaluation.
    - `outbound_type` (string) - 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` (array) - IDs of the custom folders the message or stored sent copy was assigned to.
  - `matched_rule_ids` (array) - 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.

### 400 - Bad Request

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 404 - Not Found

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The raw error from the provider, if available
    - `code` (string)
    - `message` (string)

### 429 - Rate Limit

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

## Code samples

### cURL

```bash
curl -X GET "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/rule-evaluations?limit=50" \
  -H "Authorization: Bearer <NYLAS_API_KEY>"

```

### Node.js SDK

```javascript
import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function listRuleEvaluations() {
  try {
    const evaluations = await nylas.rules.listEvaluations({
      identifier: "<NYLAS_GRANT_ID>",
      queryParams: {
        limit: 10,
      },
    });

    console.log("Rule evaluations:", evaluations);
  } catch (error) {
    console.error("Error listing rule evaluations:", error);
  }
}

listRuleEvaluations();

```

### Python SDK

```python
from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>",
)

evaluations = nylas.rules.list_evaluations(
    grant_id="<NYLAS_GRANT_ID>",
    query_params={
        "limit": 50,
    },
)

print("Rule evaluations:", evaluations)

```