# Server

Canonical: https://docs.projectbabbage.com/docs/guides/messagebox/server

Guide for running and using a MessageBox Server to relay encrypted messages between peers.


## Overview
The MessageBox Server relays encrypted messages between peers over HTTP and WebSocket. It supports sending, receiving, and acknowledging messages in a secure, identity-key-based system.

It’s designed to be used with the MessageBoxClient, and can be extended by apps like PeerPayClient for use cases such as live payment notifications.

For production, run or select a MessageBox Server and configure clients with its HTTPS and WebSocket endpoints. The examples below use `https://your-messagebox.example` as a placeholder.
________________________________________
## Endpoints
### POST /sendMessage
Sends a message to a recipient's message box.
- **Auth Required:** Yes (sender must be authenticated)
- **Request Body:**
```ts
{
  "message": {
    "recipient": "<recipientPublicKey>",
    "messageBox": "payment_inbox",
    "messageId": "xyz123",
    "body": "{...}"
  }
}
```
- **Behavior:**
  o Validates recipient public key and message structure
  o Automatically creates a message box if it doesn’t exist
  o Inserts the message into the database
  o If the recipient is connected via WebSocket, the message is sent instantly

________________________________________

### POST /listMessages
Lists messages for a specific message box belonging to the authenticated user.
- **Auth Required:** Yes
- **Request Body:**
```ts
{
  "messageBox": "payment_inbox"
}
•	Response:
json
Copy
{
  "status": "success",
  "messages": [
    {
      "messageId": "xyz123",
      "body": "{...}",
      "sender": "<senderPublicKey>"
    }
  ]
}
```
________________________________________
### POST /acknowledgeMessage
Acknowledges (and deletes) a list of message IDs, confirming receipt.
- **Auth Required:** Yes
- **Request Body:**
```ts
{
  "messageIds": ["xyz123"]
}
```
- **Response:**
```ts
{
  "status": "success"
}
```
- Note: Acknowledged messages are deleted from the database. If no acknowledgment is received, the messages remain retrievable via /listMessages.
________________________________________
### WebSocket Support
The server supports **authenticated WebSocket connections** using identity keys. When connected:
- Messages sent to a user are **delivered instantly** via WebSocket
- The client does **not need to poll** using /listMessages
- Delivered messages are still persisted in the database until acknowledged

**Connection Flow:**
1. The client opens a WebSocket connection to your MessageBox Server, for example `wss://your-messagebox.example`.

2.	The client authenticates using a signature from its identity key (handled by MessageBoxClient)
3. Once authenticated, the server:
    - Subscribes the user to incoming messages
    - Delivers them in real time as they arrive

4. The client may choose to acknowledge each message to remove it from the server

________________________________________
**Example Message Flow**
1.	**Alice** sends an encrypted message to **Bob** via /sendMessage
2.	If **Bob** is connected via WebSocket, he receives the message instantly
3.	If **Bob** is not connected, he can later call /listMessages to retrieve it
4.	After successfully processing the message, **Bob** calls /acknowledgeMessage to delete it
________________________________________
**Deployment Notes**
To run your own instance of MessageBox Server:
1.	Clone the [MessageBox server repository](https://github.com/bsv-blockchain/message-box-server)
2.	Set the following environment variable:
`SERVER_PRIVATE_KEY=...`
This is the server’s private key used for cryptographic operations.
3.	Configure your database (MySQL or other Knex compatible) via `knexfile.js`
4.	Start the server using Node.js with your preferred process manager or Docker
________________________________________
**Architecture Notes**
- MessageBox uses knex for database access
 - Messages are scoped by:
   - recipient identity key
   - messageBox type (e.g. `payment_inbox`, `alerts`, etc.)
- Message delivery via WebSocket is **event-driven**, allowing apps to build real-time systems on top of it
________________________________________
**Next Steps**
- Read the MessageBoxClient Guide to see how to connect and send/receive messages from the client side
- See the PeerPayClient Guide to understand how MessageBox is used for real-time payment coordination
- Deploy your own message box server!