---
title: "Create an inbox rule"
method: POST
path: "/communications/inbox_rule"
tags: ["Inbox rules"]
---

# Create an inbox rule

`POST /communications/inbox_rule`

## Request

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

Creates an inbox rule for your organization from its definition.

Sending the ID of a built-in rule edits that rule for your organization instead of creating a new one. To start over, reset it to default from the UI.

An organization can have up to 50 active inbox rules of its own, edited built-in rules included, and up to 10 active rules on the same entity.

## Query parameters

- `dry_run` 'true' | 'false'

## Request body

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

## Response `200`

With `dry_run=true`: the definition is valid, and nothing was saved.

- DryRunResult
  - `valid` boolean: Always `true`: an invalid definition answers `400`.

## Other responses

- `201`: The inbox rule was created.
- `400`: The definition, the context, or the NRN is invalid. Each entry in `errors` points to one problem.
- `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/post.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)