# Send a message to one or more recipients' message boxes

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

**POST** `/sendMessage`

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

Inserts a message into each recipient's named message box. If the box
does not exist it is created automatically.

**Payment logic**
- If `deliveryFee > 0` (set by server policy) a payment is required
  with output[0] assigned to the server.
- If any recipient's `recipientFee > 0` (set by the recipient) additional
  per-recipient outputs must be included.
- If a recipient has `recipientFee === -1` (blocked) the entire request
  fails with 403 before any DB writes.

Recipients must be unique after public-key canonicalization. Duplicate
compressed/uncompressed representations are rejected before fee or
message-ID allocation.

**Deduplication**  Messages with a duplicate `messageId` are silently
ignored (ON CONFLICT IGNORE). If the database raises a hard duplicate-key
error, a 400 is returned.

**Multi-recipient output routing** When sending to multiple recipients
each output in `payment.outputs` (after the optional server output at
index 0) can include `customInstructions` containing a JSON object with
a `recipientIdentityKey` field. If present, the server routes that output
to the identified recipient. Otherwise, outputs are mapped positionally
to recipients who require a fee.

## Authorization

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

## Body

Content type: `application/json`

- `message` (object, required)
  A message to be stored in a recipient's message box. The `recipient` /
  `recipients` field carries either a single key or an array. When multiple
  recipients are provided, `messageId` must be an array of the same length
  with one ID per recipient (same order).
  - `recipient` (string)
    Identity key of the recipient, or an array of recipient identity keys.
    Alias: `recipients` (array form only). Both fields are accepted for
    back-compat but must not be used simultaneously.
  - `recipients` (string[])
    Preferred plural form. Takes precedence over `recipient` when both are present. Compressed and uncompressed encodings of the same key count as one recipient and must not be repeated.
  - `messageBox` (string, required)
    Named message box (e.g. `payment_inbox`, `notifications`).
  - `messageId` (string, required)
    Unique identifier(s) for the message(s) — typically an HMAC. When
    `recipients` has more than one entry, `messageId` must be an array
    of the same length with one ID per recipient.
  - `body` (string, required)
    Serialized message payload. The official client serializes object
    bodies before sending them.
- `payment` (object)
  Optional payment attached to a message send. Required when the recipient
  has set a `recipientFee > 0` or the server has a `deliveryFee > 0`.
  - `tx` (integer[], required)
    Atomic BEEF (Background Evaluation Extended Format) encoded as a byte array.
  - `outputs` (object[], required)
    Output list. When a server delivery fee applies, output[0] must pay
    the per-recipient delivery fee multiplied by the number of recipients.
    Subsequent outputs are recipient-side.
    - `outputIndex` (integer, required)
      Index of this output in the BEEF transaction.
    - `protocol` ("wallet payment" | "basket insertion", required)
    - `paymentRemittance` (object)
      - `derivationPrefix` (string)
        Base64-encoded derivation prefix.
      - `derivationSuffix` (string)
        Base64-encoded derivation suffix.
      - `senderIdentityKey` (string)
        Compressed secp256k1 public key encoded as a 66-character hex string.
      - `customInstructions` (any)
        Arbitrary per-output routing instructions. The server attempts to
        parse this as JSON. If the parsed object contains a
        `recipientIdentityKey` string field, the output is routed to that
        recipient (batch sends only).
    - `insertionRemittance` (object)
      - `basket` (string)
      - `customInstructions` (string)
        Same `recipientIdentityKey` convention as `paymentRemittance.customInstructions`.
      - `tags` (string[])
  - `description` (string, required)
    Human-readable description for wallet internalization.
  - `labels` (string[])
  - `seekPermission` (boolean)

Example:

```json
{
  "message": {
    "recipient": "string",
    "recipients": [
      "string"
    ],
    "messageBox": "string",
    "messageId": "string",
    "body": "string"
  },
  "payment": {
    "tx": [
      0
    ],
    "outputs": [
      {
        "outputIndex": 0,
        "protocol": "wallet payment",
        "paymentRemittance": {
          "derivationPrefix": "string",
          "derivationSuffix": "string",
          "senderIdentityKey": "string",
          "customInstructions": null
        },
        "insertionRemittance": {
          "basket": "string",
          "customInstructions": "string",
          "tags": [
            "string"
          ]
        }
      }
    ],
    "description": "string",
    "labels": [
      "string"
    ],
    "seekPermission": true
  }
}
```

## Responses

### 200

Message(s) sent successfully.

- `status` ("success", required)
- `message` (string, required)
  Human-readable summary (e.g. "Your message has been sent to 1 recipient(s).").
- `results` (object[], required)
  - `recipient` (string, required)
    Compressed secp256k1 public key encoded as a 66-character hex string.
  - `messageId` (string, required)

Example:

```json
{
  "status": "success",
  "message": "string",
  "results": [
    {
      "recipient": "string",
      "messageId": "string"
    }
  ]
}
```

### 400

Bad request. Possible codes:
- `ERR_MESSAGE_REQUIRED`
- `ERR_INVALID_MESSAGEBOX`
- `ERR_INVALID_MESSAGE_BODY`
- `ERR_RECIPIENT_REQUIRED`
- `ERR_MESSAGEID_REQUIRED`
- `ERR_MESSAGEID_COUNT_MISMATCH`
- `ERR_INVALID_MESSAGEID`
- `ERR_INVALID_RECIPIENT_KEY`
- `ERR_MISSING_PAYMENT_TX`
- `ERR_MISSING_DELIVERY_OUTPUT`
- `ERR_INSUFFICIENT_PAYMENT`
- `ERR_INSUFFICIENT_OUTPUTS`
- `ERR_MISSING_RECIPIENT_OUTPUTS`
- `ERR_DUPLICATE_MESSAGE`

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

### 403

One or more recipients have blocked the sender (`ERR_DELIVERY_BLOCKED`).
The `blockedRecipients` field lists the affected identity keys.

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

Example:

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

### 500

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

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