Book a demo

set_notification_policy

Set who must receive a notice

act entity tenant-private since 2026-10-01

Sets, for one notice kind of the org, the whole set of recipients it must also reach beside its fixed ones, which nothing removes: members (by user_id), outside email addresses, and Slack channels (a new one by channel_name and webhook_url, one the org already holds by its id). cadence, hourly or daily, is the audit log digest's alone. The audit digest and admin activity alerts are written as subscribe_audit's subscriptions. Every outside address added or removed is audited. The same call again changes nothing. A Slack webhook URL is never returned.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency
natural
emits
notification_policy.changed
MCP tool
set_notification_policy
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/set_notification_policy

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose notification settings are set.
kindone_ofrequiredone of audit_digest, admin_alerts, access_request, break_glass, deletion, announcement
The notice kind: audit_digest, admin_alerts, access_request, break_glass, deletion or announcement.
recipientsnotice_recipientsrequired0 to 50 items
The whole set the org requires, each {type: member, user_id}, {type: outside, email}, {type: slack, id} (a channel the org already holds) or {type: slack, channel_name, webhook_url} (a new one). An empty list requires nobody beyond the fixed recipients.
cadenceone_ofoptionalone of hourly, daily
The audit log digest only: hourly or daily (kept as it is when absent).

Response

  • kind · string · The notice kind.
  • title · string · Its name, as the page shows it.
  • sent · string · When it is sent.
  • fixed · string[] · The recipients fixed in code, which nothing removes: org_admins (every admin of the org) and, for a deletion, deleted_user (the user a user deletion is about).
  • recipients · value · Who the org also requires: {members: [{user_id, name}], outside: [email], slack: [{id, channel_name}]}. A Slack channel is its name and id, never its webhook URL.
  • cadence · stringnull · The audit digest's cadence, hourly or daily; null for every other kind.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "audit_digest",
        "admin_alerts",
        "access_request",
        "break_glass",
        "deletion",
        "announcement"
      ],
      "description": "The notice kind.",
      "x-data-class": "operational"
    },
    "title": {
      "type": "string",
      "description": "Its name, as the page shows it.",
      "x-data-class": "operational"
    },
    "sent": {
      "type": "string",
      "description": "When it is sent.",
      "x-data-class": "operational"
    },
    "fixed": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The recipients fixed in code, which nothing removes: org_admins (every admin of the org) and, for a deletion, deleted_user (the user a user deletion is about).",
      "x-data-class": "operational"
    },
    "recipients": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "Who the org also requires: {members: [{user_id, name}], outside: [email], slack: [{id, channel_name}]}. A Slack channel is its name and id, never its webhook URL.",
      "x-data-class": "personal"
    },
    "cadence": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "hourly",
        "daily",
        null
      ],
      "description": "The audit digest's cadence, hourly or daily; null for every other kind.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "kind",
    "title",
    "sent",
    "fixed",
    "recipients",
    "cadence"
  ],
  "additionalProperties": false
}

Refusals

  • cadence_is_digest_only · 422 · a cadence was sent for a notice kind other than the audit log digest
  • invalid_email · 422 · an outside recipient is not an email address
  • invalid_slack_webhook · 422 · a Slack channel's URL is not an incoming webhook, or its id is not one the org already holds
  • unknown_member · 422 · a member recipient is not a current member of the org

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileD5
APIF
MCPF*
VoiceD5
PushF
OneBoxN
OutboundN
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: degraded: composition
  • OneBox: no document originates a notification settings
  • Outbound: crosses to no counterparty

Events

Related

list_role_templates, set_my_notification, subscribe_audit