# Set a message permission for a sender or as a box-wide default

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

**POST** `/permissions/set`

Base URL: `https://{host}`

Sets the `recipientFee` for messages arriving in a named message box.
- If `sender` is omitted the setting is a box-wide default for all senders.
- If `sender` is provided, the setting applies only to that sender.
- `recipientFee` semantics:
  - `-1` — block all messages from this sender (or box-wide)
  - `0`  — always allow (no fee required)
  - `>0` — require this many satoshis before delivery

## Authorization

- x-bsv-auth-identity-key (apiKey in header)

## Body

Content type: `application/json`

- `sender` (string)
  Compressed secp256k1 public key encoded as a 66-character hex string.
- `messageBox` (string, required)
  Message box name (e.g. `notifications`, `inbox`).
- `recipientFee` (integer, required)
  -1 = blocked, 0 = always allow, positive = satoshi amount.

Example:

```json
{
  "sender": "string",
  "messageBox": "string",
  "recipientFee": 0
}
```

## Responses

### 200

Permission set or updated successfully.

- `status` ("success", required)
- `description` (string, required)
  Human-readable confirmation of the new policy.

Example:

```json
{
  "status": "success",
  "description": "string"
}
```

### 400

Invalid request.
Codes: `ERR_INVALID_REQUEST`, `ERR_INVALID_PUBLIC_KEY`, `ERR_INVALID_FEE_VALUE`,
`ERR_INVALID_MESSAGE_BOX`

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```

### 401

Authentication required (`ERR_AUTHENTICATION_REQUIRED`).

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```

### 500

Internal server error (`ERR_DATABASE_ERROR`, `ERR_INTERNAL`).

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```