> ## Documentation Index
> Fetch the complete documentation index at: https://cubed3-feat-druid-driver-streaming.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Add notification recipients

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Subscribes one or more recipients (1–1000 per request) to a notification. Each recipient is one of: a main console `USER` (identified by `userId` or `email`); an `EMBED_USER` (identified by `embedTenantName` + `externalId`, auto-provisioned if it does not yet exist, and optionally given `securityContext`, `userAttributes`, and `groups` that drive per-recipient rendering); or `SLACK` — **not yet supported**, a request containing a Slack recipient is rejected with `400`. Every recipient must resolve to a valid email (an embed user’s `email`, or an email-shaped `externalId`); otherwise the whole request fails with `400` before anything is written. The operation is idempotent: the response buckets each recipient into `createdRecipients`, `updatedRecipients` (an existing recipient whose embed properties changed), or `unchangedRecipients`.


## OpenAPI

````yaml /api-reference/api.yaml post /v1/deployments/{deploymentId}/notifications/{id}/recipients
openapi: 3.1.0
info:
  title: Cube Cloud REST API
  version: 1.0.0
  description: >-
    Programmatically manage Cube Cloud: deployments and everything scoped to
    them

    (environments, folders, reports, workbooks, notifications, workspace, and
    agents),

    plus account-level users, groups, policies, embedding, and AI settings.
servers:
  - url: https://{tenant}.cubecloud.dev/api
    description: >-
      Cube Cloud API base URL. Replace the whole host if you use a custom
      domain.
    variables:
      tenant:
        default: your-tenant
        description: Your Cube Cloud tenant subdomain
security:
  - bearerAuth: []
tags:
  - name: Deployments
  - name: Environments
  - name: Folders
  - name: Reports
  - name: Workbooks
  - name: Notifications
  - name: Workspace
  - name: App Theme
  - name: Embed
  - name: Embed Tenants
paths:
  /v1/deployments/{deploymentId}/notifications/{id}/recipients:
    post:
      tags:
        - Notifications
      summary: Add notification recipients
      operationId: addRecipients
      parameters:
        - in: path
          name: deploymentId
          required: true
          schema:
            type: integer
          description: Numeric id of the deployment that owns the notification.
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: Numeric id of the notification (scheduled run).
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddNotificationRecipientsInput'
        description: AddNotificationRecipientsInput
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationRecipientsMutationResponse'
          description: ''
components:
  schemas:
    AddNotificationRecipientsInput:
      properties:
        recipients:
          description: Recipients to subscribe (1–1000 per request)
          items:
            $ref: '#/components/schemas/NotificationRecipientInput'
          maxItems: 1000
          minItems: 1
          type: array
      required:
        - recipients
      type: object
    NotificationRecipientsMutationResponse:
      properties:
        createdRecipients:
          description: Recipients newly subscribed by this request
          items:
            $ref: '#/components/schemas/NotificationRecipient'
          type: array
        unchangedRecipients:
          description: Recipients that already existed and were left unchanged
          items:
            $ref: '#/components/schemas/NotificationRecipient'
          type: array
        updatedRecipients:
          description: >-
            Existing recipients whose properties (e.g. embed security context /
            attributes / groups, or Slack channel name) were updated
          items:
            $ref: '#/components/schemas/NotificationRecipient'
          type: array
      required:
        - createdRecipients
        - updatedRecipients
        - unchangedRecipients
      type: object
    NotificationRecipientInput:
      properties:
        channelId:
          oneOf:
            - type: string
              description: Slack channel id (for type=SLACK)
            - type: 'null'
        channelName:
          oneOf:
            - type: string
              description: Slack channel display name (optional, for type=SLACK)
            - type: 'null'
        email:
          oneOf:
            - type: string
              description: Main user email (for type=USER; provide this OR userId)
            - type: 'null'
        embedTenantName:
          oneOf:
            - type: string
              description: Embed tenant name (for type=EMBED_USER)
            - type: 'null'
        externalId:
          oneOf:
            - type: string
              description: Embed user external id (for type=EMBED_USER)
            - type: 'null'
        groups:
          oneOf:
            - items:
                type: string
              type: array
              description: >-
                Embed user groups (type=EMBED_USER). Must reference groups that
                already exist; drives per-recipient access when the report is
                rendered.
            - type: 'null'
        securityContext:
          oneOf:
            - type: object
              additionalProperties: true
              description: >-
                Embed user security context (type=EMBED_USER). Applied for
                per-recipient row-level security when the report is rendered.
            - type: 'null'
        type:
          $ref: '#/components/schemas/NotificationRecipientInputType'
        userAttributes:
          oneOf:
            - items:
                $ref: '#/components/schemas/UserAttributeInput'
              type: array
              description: >-
                Embed user attribute values (type=EMBED_USER). Names must
                reference attribute definitions that already exist.
            - type: 'null'
        userId:
          oneOf:
            - type: integer
              description: Main user id (for type=USER; provide this OR email)
            - type: 'null'
      required:
        - type
      type: object
    NotificationRecipient:
      properties:
        channelId:
          oneOf:
            - type: string
            - type: 'null'
        channelName:
          oneOf:
            - type: string
            - type: 'null'
        email:
          oneOf:
            - type: string
            - type: 'null'
        embedTenantName:
          oneOf:
            - type: string
            - type: 'null'
        embedUserId:
          oneOf:
            - type: integer
            - type: 'null'
        externalId:
          oneOf:
            - type: string
            - type: 'null'
        type:
          $ref: '#/components/schemas/NotificationRecipientType'
        userId:
          oneOf:
            - type: integer
            - type: 'null'
        username:
          oneOf:
            - type: string
            - type: 'null'
      required:
        - type
      type: object
    NotificationRecipientInputType:
      enum:
        - USER
        - EMBED_USER
        - SLACK
      type: string
    UserAttributeInput:
      properties:
        name:
          type: string
        value:
          oneOf:
            - oneOf:
                - type: string
                - type: number
                - items:
                    type: string
                  type: array
                - type: array
                  items:
                    type: number
            - type: 'null'
      required:
        - name
      type: object
    NotificationRecipientType:
      enum:
        - USER
        - EMBED_USER
        - SLACK
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Token authentication. Send `Authorization: Bearer <YOUR_TOKEN>`.'

````