---
title: "Read an inbox rule"
method: GET
path: "/communications/inbox_rule/{id}"
tags: ["Inbox rules"]
---

# Read an inbox rule

`GET /communications/inbox_rule/{id}`

## Request

- Base URL: `https://api.nullplatform.com`
- URL: `https://api.nullplatform.com/communications/inbox_rule/{id}`
- Auth: HTTP bearer

Returns one inbox rule. For a built-in rule your organization edited, it returns your edited version.

## Path parameters

- `id` string, required

## Response `200`

The requested inbox rule.

- InboxRule
  - `id` string: The ID of the inbox rule.
  - `organization_id` integer, nullable: Your organization's ID for its own rules, or `null` for a built-in rule.
  - `publisher` string: Who published the rule: `organization` for your organization's rules.
  - `status` 'active' | 'deprecated': Whether the rule is active. `deprecated` means deactivated.
  - `document` InboxRuleDefinition: The definition of an inbox rule. The main fields are listed here. For every field, including conditions, delays, and batching, read the schema from `GET /communications/inbox_rule/schema`.
    - `id` string, required: Lowercase words with exactly one dot. It also identifies the rule in inbox settings, and it can't change later. > ℹ️ **Note:** It can't start with `platform.`. Using a built-in rule's ID edits that rule for your organization.
    - `status` 'active' | 'deprecated': Whether the rule is active. Defaults to `active`. `deprecated` means deactivated.
    - `source` union, required: What makes the rule fire: - `{ "kind": "invoked" }`: your code calls the emission endpoint. - A source name, like `"deployment"`: the entity changes status in nullplatform. See `GET /communications/inbox_rule/source`. - `{ "kind": "stale", ... }`: an entity stays in a status for too long.
      - string
      - object
    - `context_schema` object: A JSON Schema for the data each send carries. An invoked rule must require `id`, because sends are idempotent by it.
    - `category` object, required: How the rule shows up in inbox settings. All six fields are required.
      - `group` string, required: The group the rule is listed under in inbox settings.
      - `label` string, required: The rule's name in inbox settings.
      - `description` string, required: One line on what the rule announces.
      - `configurable` boolean, required: Whether people can change their mode for this rule.
      - `allows_all` boolean, required: Whether people can choose **Everything** for this rule under a resource. Requires `configurable`.
      - `default_mode` 'off' | 'involved' | 'all', required: What people get until they change it.
    - `severity` 'informational' | 'maintenance' | 'degraded' | 'outage', required: Sets the icon and the color of the notification.
    - `audience` object[], required: One entry per reading. Each entry is a separate notification with its own wording.
      - `as` string, required: The name of this reading.
      - `who` object: Who receives this reading: `{ "user": "${{ context.owner_id }}" }` for a user from the context, or `{ "can": "approval_request:approve" }` for everyone who holds that action on the resource. Without `who`, only the people who chose **Everything** receive it.
      - `action` string, required: The rule's ID, or an ID that starts with it.
      - `content` object, required
        - `title` string, required: The notification's title. Accepts templates like `${{ context.service }}` and inline Markdown.
        - `body` string: The notification's body. Accepts templates, inline Markdown, links, and lists.
      - `fallback` object: Another reading, with the same fields, for when `who` resolves nobody.
    - `visible_to` string[]: The one NRN the rule applies under. Defaults to your organization. Sends for resources outside it are refused.
  - `created_at` string, date-time: When the rule was created.
  - `updated_at` string, date-time: When the rule was last updated.
  - `organization_state` OrganizationState: Only on built-in rules: how the rule stands in your organization.
    - `enabled` boolean: Whether the rule is on for your organization.
    - `customized` boolean: Whether your organization edited the rule.
    - `linked` string[]: Built-in rules that turn on and off together with this one.
    - `replaced_by` string, nullable: The ID of your rule that takes this one's place, if any.

## Other responses

- `4XX`: The request couldn't be processed. For example, a parameter is invalid, the resource doesn't exist, or you don't have permission. The body is a problem details object (RFC 9457).
- `5XX`: Something went wrong on nullplatform's side. The body is a problem details object (RFC 9457).

## Changes

- **2026-10-22** `3d300f7f8452`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nullplatform/apis/nullplatform-api/changes/communications/inbox_rule/:id/get.md)

---

[API](https://skmtc.dev/nullplatform/apis/nullplatform-api.md) - [All operations](https://skmtc.dev/nullplatform/apis/nullplatform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nullplatform/apis/nullplatform-api/revisions/d3f66bc633d4?raw)