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

# Validate an inbox rule

`POST /communications/inbox_rule/validate`

## Request

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

Runs every check that creating (`mode: new`) or updating (`mode: edit`) an inbox rule runs, limits included, and saves nothing.

Unlike `dry_run=true` on create and update, an invalid definition isn't an error: it answers `200` with `valid: false` and every problem found.

## Request body

- object
  - `definition` InboxRuleDefinition, required: 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.
  - `mode` 'new' | 'edit': `new` checks the definition as a create, and `edit` as an update of the rule in `type_id`.
  - `type_id` string: With `mode: edit`, the ID of the inbox rule you're updating. It must match `definition.id`.

## Response `200`

The verdict, for a valid or an invalid definition alike.

- object
  - `valid` boolean: Whether the definition would be accepted.
  - `problems` object[]: One entry per problem. Empty when the definition is valid.
    - `path` string: A JSON pointer to the invalid field in the definition.
    - `message` string: What's wrong with that field.

## 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-27** `c0f507ec6087`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nullplatform/apis/nullplatform-api/changes/communications/inbox_rule/validate/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)