> ## Documentation Index
> Fetch the complete documentation index at: https://archie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending notifications

> Emit a notification to specific users or a whole audience with a single emitNotification mutation. Archie resolves recipients, checks preferences, and delivers on each channel.

To send a notification, your application calls a single mutation — `emitNotification` — with the **event key** of a notification type and a **target** (who should receive it). Archie does the rest: it resolves the recipients, checks their preferences, renders the templates, and delivers on each channel.

You describe *intent* ("notify these users that their build failed"); you never build per-recipient rows yourself.

**Endpoint**

```
https://archie-core.services.archie.com/graphql
```

**Required headers**

| Header | Value |
| - | - |
| `X-Project-Id` | Your project id |
| `X-Environment` | The target environment (e.g., `master`, `staging`, `production`) |
| `Authorization` | `Bearer <accessToken>` |

## The input at a glance

| Field | Required | Description |
| - | - | - |
| `eventKey` | Yes | The notification type to send (must exist and be active in this environment). |
| `target` | Yes | **Exactly one** of `userIds` or `audience` (see below). |
| `sourceService` | Yes | A short label identifying who is sending (e.g., `"billing"`, `"ci"`). Used for auditing. |
| `params` | No | A JSON object of variables for the templates (e.g., `{ "buildId": "42" }`). |
| `channels` | No | Override the type's channels for this send. In v1 the override may only contain `email` and/or `in_app`. Omit it to use each recipient's resolved channels. |
| `action` | No | An optional call-to-action with `url` and/or `text` (e.g., a "View build" link). |
| `dedupKey` | No | A key that makes the send idempotent — repeating the same `dedupKey` will not deliver twice. |
| `expiresIn` | No | How long the in-app item lives, as a duration string (e.g., `"720h"`). Clamped to a maximum of 365 days. |
| `broadcastConfirm` | No | Set to `true` to confirm an intentionally large broadcast (see *Large broadcasts* below). |

## Choosing a target

A target is **exactly one** of:

* **`userIds`** — an explicit list of user ids. Use this for transactional notifications ("notify *this* user").
* **`audience`** — a named group:
  * `SUBSCRIBERS` — everyone whose preference for this type is enabled (respecting per-user opt-in).
  * `ALL_PROJECT_USERS` — every user in the project (use sparingly; respects mandatory and anomaly rules).

## Examples

### Notify specific users

```graphql theme={null}
mutation NotifyUser {
  emitNotification(
    input: {
      eventKey: "order_shipped"
      sourceService: "fulfillment"
      target: { userIds: ["2685ec12-a4c7-491d-a155-d0b09190993b"] }
      params: { orderId: "A-1029", eta: "Friday" }
      action: { text: "Track package", url: "https://app.example.com/orders/A-1029" }
    }
  ) {
    accepted
    targetingMode
    recipientCount
  }
}
```

**Response**

```json theme={null}
{
  "data": {
    "emitNotification": {
      "accepted": true,
      "targetingMode": "user_ids",
      "recipientCount": 1
    }
  }
}
```

### Notify everyone subscribed to a type

```graphql theme={null}
mutation NotifySubscribers {
  emitNotification(
    input: {
      eventKey: "platform_updates"
      sourceService: "product"
      target: { audience: SUBSCRIBERS }
      params: { version: "2.4.0" }
      channels: [in_app, email]
    }
  ) {
    accepted
    targetingMode
    fanoutJobId
  }
}
```

For an audience send, delivery happens **asynchronously**: `accepted: true` means the request was queued. `recipientCount` is therefore `null` and a `fanoutJobId` is returned that identifies the broadcast.

### Make a send idempotent

If your service might retry, pass a stable `dedupKey`. The same key is never delivered twice:

```graphql theme={null}
mutation NotifyOnce {
  emitNotification(
    input: {
      eventKey: "invoice_payment"
      sourceService: "billing"
      target: { userIds: ["2685ec12-…"] }
      params: { invoiceId: "INV-77" }
      dedupKey: "invoice-INV-77-paid"
    }
  ) {
    accepted
    recipientCount
  }
}
```

## Understanding the result

`EmitNotificationResult` tells you what happened **synchronously**:

| Field | Meaning |
| - | - |
| `accepted` | `true` if the request was accepted (delivered for explicit users, or queued for an audience). |
| `targetingMode` | `user_ids`, `subscribers`, or `all_project_users`. |
| `recipientCount` | Number of recipients for an explicit `userIds` send; `null` for an audience (resolved asynchronously). |
| `fanoutJobId` | Identifier for an audience broadcast. |
| `rejectedReason` | When `accepted` is `false`, a short reason code explaining why. |

### When a send is rejected

If `accepted` is `false`, check `rejectedReason`. Common reasons:

| `rejectedReason` | What to do |
| - | - |
| `invalid_input` | A required field is missing or invalid, or the explicit `userIds` list is too large — split it or use an audience. |
| `target_validation_failed` | You must provide **exactly one** of `userIds` or `audience`. |
| `override_channel_not_permitted` | The `channels` override contains a channel that can't be forced in v1 (only `email` and `in_app` are allowed). |
| `broadcast_quota_exceeded` | Too many broadcasts for this type in the current window — slow down or batch. |

<Note>
  A rejection is a normal, expected response (the mutation still returns `200`); it is not a server error.
</Note>

## Large broadcasts

To protect your users from accidental mass-sends, an audience broadcast that resolves to an unusually large number of recipients is **held** unless you explicitly confirm it. If you *intend* to reach a very large audience, set `broadcastConfirm: true`:

```graphql theme={null}
mutation BigAnnouncement {
  emitNotification(
    input: {
      eventKey: "platform_updates"
      sourceService: "product"
      target: { audience: ALL_PROJECT_USERS }
      params: { headline: "New dashboard is live" }
      broadcastConfirm: true
    }
  ) {
    accepted
    fanoutJobId
    rejectedReason
  }
}
```

## Next step

See how recipients read and stream their notifications in [In-app inbox & real-time updates](/docs/features/backend/app-services/notifications/in-app-inbox).