--- id: inbox-rule-create title: Create an inbox rule description: Creates an inbox rule for your organization from its definition. sidebar_label: Create an inbox rule hide_title: true hide_table_of_contents: true api: >- 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 sidebar_class_name: post api-method info_path: docs/api/communications custom_edit_url: null canonical: 'https://docs.nullplatform.com/docs/api/inbox-rule-create' --- 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. ℹ️ **Note:** It can't start with `platform.`. Using a built-in rule's ID edits that rule for your organization.\n","example":"acme.security_finding"},"status":{"type":"string","enum":["active","deprecated"],"description":"Whether the rule is active. Defaults to `active`. `deprecated` means deactivated.","example":"active"},"source":{"description":"What makes the rule fire:\n\n- `{ \"kind\": \"invoked\" }`: your code calls the emission endpoint.\n- A source name, like `\"deployment\"`: the entity changes status in nullplatform. See `GET /communications/inbox_rule/source`.\n- `{ \"kind\": \"stale\", ... }`: an entity stays in a status for too long.\n","oneOf":[{"type":"string"},{"type":"object","additionalProperties":true}],"example":{"kind":"invoked"}},"context_schema":{"type":"object","additionalProperties":true,"description":"A JSON Schema for the data each send carries. An invoked rule must require `id`, because sends are idempotent by it.","example":{"type":"object","required":["id","service","owner_id"],"properties":{"id":{"type":"string"},"service":{"type":"string"},"summary":{"type":"string"},"owner_id":{"type":"integer"}}}},"category":{"type":"object","description":"How the rule shows up in inbox settings. All six fields are required.","required":["group","label","description","configurable","allows_all","default_mode"],"properties":{"group":{"type":"string","description":"The group the rule is listed under in inbox settings.","example":"security"},"label":{"type":"string","description":"The rule's name in inbox settings.","example":"Security findings"},"description":{"type":"string","maxLength":70,"description":"One line on what the rule announces.","example":"Vulnerabilities your CI scanners report."},"configurable":{"type":"boolean","description":"Whether people can change their mode for this rule.","example":true},"allows_all":{"type":"boolean","description":"Whether people can choose **Everything** for this rule under a resource. Requires `configurable`.","example":true},"default_mode":{"type":"string","enum":["off","involved","all"],"description":"What people get until they change it.","example":"involved"}}},"severity":{"type":"string","enum":["informational","maintenance","degraded","outage"],"description":"Sets the icon and the color of the notification.","example":"degraded"},"audience":{"type":"array","description":"One entry per reading. Each entry is a separate notification with its own wording.","items":{"type":"object","required":["as","action","content"],"additionalProperties":true,"properties":{"as":{"type":"string","description":"The name of this reading.","example":"owner"},"who":{"type":"object","additionalProperties":true,"description":"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.","example":{"user":"${{ context.owner_id }}"}},"action":{"type":"string","description":"The rule's ID, or an ID that starts with it.","example":"acme.security_finding"},"content":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"The notification's title. Accepts templates like `${{ context.service }}` and inline Markdown.","example":"Security finding on ${{ context.service }}"},"body":{"type":"string","description":"The notification's body. Accepts templates, inline Markdown, links, and lists.","example":"${{ context.summary }}"}}},"fallback":{"type":"object","additionalProperties":true,"description":"Another reading, with the same fields, for when `who` resolves nobody."}}}},"visible_to":{"type":"array","maxItems":1,"items":{"type":"string"},"description":"The one NRN the rule applies under. Defaults to your organization. Sends for resources outside it are refused.","example":["organization=1:account=2"]}}}}}}} > ℹ️ **Note:** It can't start with `platform.`. Using a built-in rule's ID edits that rule for your organization.\n","example":"acme.security_finding"},"status":{"type":"string","enum":["active","deprecated"],"description":"Whether the rule is active. Defaults to `active`. `deprecated` means deactivated.","example":"active"},"source":{"description":"What makes the rule fire:\n\n- `{ \"kind\": \"invoked\" }`: your code calls the emission endpoint.\n- A source name, like `\"deployment\"`: the entity changes status in nullplatform. See `GET /communications/inbox_rule/source`.\n- `{ \"kind\": \"stale\", ... }`: an entity stays in a status for too long.\n","oneOf":[{"type":"string"},{"type":"object","additionalProperties":true}],"example":{"kind":"invoked"}},"context_schema":{"type":"object","additionalProperties":true,"description":"A JSON Schema for the data each send carries. An invoked rule must require `id`, because sends are idempotent by it.","example":{"type":"object","required":["id","service","owner_id"],"properties":{"id":{"type":"string"},"service":{"type":"string"},"summary":{"type":"string"},"owner_id":{"type":"integer"}}}},"category":{"type":"object","description":"How the rule shows up in inbox settings. All six fields are required.","required":["group","label","description","configurable","allows_all","default_mode"],"properties":{"group":{"type":"string","description":"The group the rule is listed under in inbox settings.","example":"security"},"label":{"type":"string","description":"The rule's name in inbox settings.","example":"Security findings"},"description":{"type":"string","maxLength":70,"description":"One line on what the rule announces.","example":"Vulnerabilities your CI scanners report."},"configurable":{"type":"boolean","description":"Whether people can change their mode for this rule.","example":true},"allows_all":{"type":"boolean","description":"Whether people can choose **Everything** for this rule under a resource. Requires `configurable`.","example":true},"default_mode":{"type":"string","enum":["off","involved","all"],"description":"What people get until they change it.","example":"involved"}}},"severity":{"type":"string","enum":["informational","maintenance","degraded","outage"],"description":"Sets the icon and the color of the notification.","example":"degraded"},"audience":{"type":"array","description":"One entry per reading. Each entry is a separate notification with its own wording.","items":{"type":"object","required":["as","action","content"],"additionalProperties":true,"properties":{"as":{"type":"string","description":"The name of this reading.","example":"owner"},"who":{"type":"object","additionalProperties":true,"description":"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.","example":{"user":"${{ context.owner_id }}"}},"action":{"type":"string","description":"The rule's ID, or an ID that starts with it.","example":"acme.security_finding"},"content":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"The notification's title. Accepts templates like `${{ context.service }}` and inline Markdown.","example":"Security finding on ${{ context.service }}"},"body":{"type":"string","description":"The notification's body. Accepts templates, inline Markdown, links, and lists.","example":"${{ context.summary }}"}}},"fallback":{"type":"object","additionalProperties":true,"description":"Another reading, with the same fields, for when `who` resolves nobody."}}}},"visible_to":{"type":"array","maxItems":1,"items":{"type":"string"},"description":"The one NRN the rule applies under. Defaults to your organization. Sends for resources outside it are refused.","example":["organization=1:account=2"]}}},"created_at":{"type":"string","format":"date-time","description":"When the rule was created.","example":"2026-10-20T14:03:11.000Z"},"updated_at":{"type":"string","format":"date-time","description":"When the rule was last updated.","example":"2026-10-20T14:03:11.000Z"},"organization_state":{"type":"object","description":"Only on built-in rules, in the list: how the rule stands in your organization.","properties":{"enabled":{"type":"boolean","description":"Whether the rule is on for your organization.","example":true},"customized":{"type":"boolean","description":"Whether your organization edited the rule.","example":false},"linked":{"type":"array","items":{"type":"string"},"description":"Built-in rules that turn on and off together with this one.","example":[]},"replaced_by":{"type":"string","nullable":true,"description":"The ID of your rule that takes this one's place, if any.","example":null}}}}}}}},"400":{"description":"The definition, the context, or the NRN is invalid. Each entry in `errors` points to one problem.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A summary of every problem found.","example":"invalid notification type: /category/description must be at most 70 characters"},"errors":{"type":"array","description":"One entry per problem.","items":{"type":"object","properties":{"path":{"type":"string","description":"A JSON pointer to the invalid field in the request body.","example":"/category/description"},"message":{"type":"string","description":"What's wrong with that field.","example":"must be at most 70 characters"}}}}}}}}},"4XX":{"description":"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).","content":{"application/problem+json":{"schema":{"type":"object","description":"Describes what went wrong, following the RFC 9457 problem details format.","required":["type","title","status"],"properties":{"type":{"type":"string","description":"A URI that identifies the kind of problem. It's an identifier, not a link, and it's the same every time this problem occurs.","example":"urn:nullplatform:error:routes-helper:invalid-params"},"title":{"type":"string","description":"A short, human-readable summary of the problem.","example":"There are invalid parameters on the request"},"status":{"type":"integer","description":"The HTTP status code of the response.","example":400},"code":{"type":"string","description":"A stable, machine-readable error code. Use it to handle specific errors in your integrations.","example":"ROUTES_HELPER.INVALID_PARAMS"},"detail":{"type":"string","nullable":true,"description":"More information about what went wrong in this request, when available.","example":null},"errors":{"type":"array","description":"One entry per invalid field or parameter. Only present on validation errors.","items":{"type":"object","properties":{"field":{"type":"string","description":"The name of the invalid field or parameter.","example":"application_id"},"in":{"type":"string","description":"Where the field was sent: `body`, `query`, or `params` (path parameters).","example":"query"},"issue":{"type":"string","description":"What's wrong with the field, such as `required` or `invalid`.","example":"invalid"},"value":{"description":"The value that was sent, when relevant.","example":"not-a-number"},"message":{"type":"string","description":"A human-readable explanation of the issue."}}}},"message":{"type":"string","deprecated":true,"description":"Same value as `title`, kept for backward compatibility. Use `title` or `code` instead.","example":"There are invalid parameters on the request"},"traceId":{"type":"string","description":"An identifier for this request, when available. Include it when you contact nullplatform support."}}}}}},"5XX":{"description":"Something went wrong on nullplatform's side. The body is a problem details object (RFC 9457).","content":{"application/problem+json":{"schema":{"type":"object","description":"Describes what went wrong, following the RFC 9457 problem details format.","required":["type","title","status"],"properties":{"type":{"type":"string","description":"A URI that identifies the kind of problem. It's an identifier, not a link, and it's the same every time this problem occurs.","example":"about:blank"},"title":{"type":"string","description":"A short, human-readable summary of the problem.","example":"Oops.. there was an internal error"},"status":{"type":"integer","description":"The HTTP status code of the response.","example":500},"code":{"type":"string","description":"A stable, machine-readable error code. Use it to handle specific errors in your integrations."},"detail":{"type":"string","nullable":true,"description":"More information about what went wrong in this request, when available.","example":null},"message":{"type":"string","deprecated":true,"description":"Same value as `title`, kept for backward compatibility. Use `title` or `code` instead.","example":"Oops.. there was an internal error"},"traceId":{"type":"string","description":"An identifier for this request, when available. Include it when you contact nullplatform support."}}}}}}}} >