# sendnotification

## POST /api/sendnotification

Sends a direct notification to a user identified by email address for a specific app. This endpoint supports default delivery, push-only delivery, in-app-only delivery, and badge-only push updates.

## Authentication

You must include both:

* `X-Auth-Token`: a valid Buzzy auth token
* `X-User-Id`: the matching logged-in user ID

An `X-API-Key` by itself is not enough for this endpoint. The authenticated user must also be able to edit the target app.

## Request

### Headers

| Header       | Value              | Description                        |
| ------------ | ------------------ | ---------------------------------- |
| Content-Type | `application/json` | Request body format                |
| X-Auth-Token | string             | Auth token for the requesting user |
| X-User-Id    | string             | User ID matching the auth token    |

### Body

```json
{
  "appID": "your-app-id",
  "email": "user@example.com",
  "message": "Hello from Buzzy",
  "badgeCount": 7,
  "channel": "push"
}
```

| Parameter    | Type   | Required | Description                                   |
| ------------ | ------ | -------- | --------------------------------------------- |
| `appID`      | string | Yes      | ID of the app the requesting user can edit    |
| `email`      | string | Yes      | Recipient email address                       |
| `message`    | string | No       | Visible notification message                  |
| `badgeCount` | number | No       | Absolute badge number to send                 |
| `channel`    | string | No       | `push`, `inApp`, or omit for default delivery |

## Delivery behavior

* Omit `channel` or use `default` to create an in-app notification and send push delivery.
* Use `channel: "push"` to send push only.
* Use `channel: "inApp"` to create an unread in-app notification only.
* If `channel: "push"` is used without `message`, Buzzy sends a badge-only push update with no visible push body.
* Badge-only push updates are app-only and currently update the Apple app badge number without showing a visible notification message.

## Success response

```json
{
  "ok": true,
  "appID": "your-app-id",
  "email": "user@example.com",
  "channel": "push",
  "hasMessage": false,
  "badgeCount": 7,
  "notificationCount": 0,
  "pushCount": 2
}
```

### Response fields

| Field               | Type           | Description                               |
| ------------------- | -------------- | ----------------------------------------- |
| `ok`                | boolean        | Indicates the request succeeded           |
| `appID`             | string         | App ID used for the notification          |
| `email`             | string         | Recipient email                           |
| `channel`           | string         | Delivery mode used by the request         |
| `hasMessage`        | boolean        | Whether a visible message was supplied    |
| `badgeCount`        | number or null | Badge value sent, if supplied             |
| `notificationCount` | number         | Number of in-app notifications created    |
| `pushCount`         | number         | Number of Firebase push messages prepared |

## Error responses

### Missing app ID

```json
{
  "error": "appID is required"
}
```

### Missing email

```json
{
  "error": "email is required"
}
```

### User is not allowed to send for this app

```json
{
  "error": "Forbidden",
  "message": "Only app admins or authors can send notifications for this app"
}
```

### Recipient not found

```json
{
  "error": "User not found for user@example.com"
}
```

## Example requests

### Default visible notification

```http
POST /api/sendnotification
Content-Type: application/json
X-Auth-Token: your-auth-token
X-User-Id: your-user-id

{
  "appID": "your-app-id",
  "email": "user@example.com",
  "message": "Hello from Buzzy"
}
```

### Badge-only push update

```http
POST /api/sendnotification
Content-Type: application/json
X-Auth-Token: your-auth-token
X-User-Id: your-user-id

{
  "appID": "your-app-id",
  "email": "user@example.com",
  "badgeCount": 12,
  "channel": "push"
}
```

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/sendnotification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.