---
title: "Send a notification from an inbox rule"
method: POST
path: "/communications/inbox_rule/{id}/emission"
tags: ["Inbox rules"]
---

# Send a notification from an inbox rule

`POST /communications/inbox_rule/{id}/emission`

## Request

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

Sends a notification from one of your **invoked** inbox rules: the resource the event is about (`nrn`) and the data the rule's templates read (`context`).

Sends are idempotent by `context.id`. Sending the same `id` for the same `nrn` again answers `200`, marks each entry in `emitted` with `existing: true`, and creates nothing. Sending it for a different `nrn` answers `409`.

Recipients who can't see the resource are left out and counted in `rejected`, and people who turned the rule off for that resource don't receive it.

## Path parameters

- `id` string, required

## Query parameters

- `dry_run` 'true' | 'false'

## Request body

- object
  - `nrn` string, required: The NRN of the resource the event is about. It must be inside your organization, and inside the rule's `visible_to`.
  - `context` object, required: The data the rule's templates read. It must match the rule's `context_schema`, which always requires `id`.
  - `deliver_to` 'me': Set to `me` to send the rule's first reading to yourself only, as a test.

## Response `200`

A retry of an earlier send, nobody was left to notify, or a dry run.

With `dry_run=true`, the body describes what would be sent: `would_emit`, `rejected`, and `unreached` when a reading would reach nobody.

- union
  - EmissionResult
    - `emitted` object[]: One entry per reading that reached someone.
      - `id` string, uuid: The ID of the notification.
      - `as` string: The reading that was sent.
      - `recipients` integer: How many people received it. A count, never user IDs.
      - `existing` boolean: Present on a retry: the notification already existed, and nothing was created.
    - `rejected` integer: How many recipients were left out because they can't see the resource.
    - `test` boolean: Present when you sent the test to yourself with `deliver_to: me`.
  - EmissionDryRun
    - `would_emit` object[]: One entry per reading that would be sent.
      - `as` string: The reading.
      - `recipients` integer: How many people would receive it.
      - `payload` object: The notification as it would be rendered.
      - `existing` boolean: Present when this `context.id` was already sent for the same resource.
    - `rejected` integer: How many recipients would be left out because they can't see the resource.
    - `deferred` 'delay' | 'batch': Present when the rule would defer delivery.
    - `unreached` object[]: Present when a reading would reach nobody, with the reason.
      - `as` string: The reading.
      - `reason` string: Why it would reach nobody.

## Other responses

- `201`: At least one notification was created.
- `202`: The rule declares a delay or a batch, so delivery was deferred.
- `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/:id/emission/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)