# 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"
}
```

***