139 lines
3.3 KiB
Markdown
139 lines
3.3 KiB
Markdown
# Message Center
|
|
|
|
Unified API for messages from multiple sources (email, WhatsApp).
|
|
|
|
## Features
|
|
|
|
- **Unified Message Format**: All messages follow the same schema regardless of source
|
|
- **Connector Architecture**: Pluggable message sources
|
|
- **Cursor Tracking**: Track high-water mark per consumer for reliable processing
|
|
- **Replay Window**: Query messages from any time period with `?since=`
|
|
- **Actions**: Archive, delete, reply, and forward attachments to documents
|
|
- **Simple Webhooks**: Just notifies `{"event": "new"}` when new messages arrive
|
|
|
|
## API Endpoints
|
|
|
|
### Unified Messages
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/messages/new` | GET | Unseen messages from all sources |
|
|
| `/messages?since=24h` | GET | Messages from last 24 hours (supports h/d/w) |
|
|
| `/messages/{id}` | GET | Single message by ID |
|
|
| `/messages/ack` | POST | Advance cursor for a consumer |
|
|
| `/messages/{id}/archive` | POST | Archive message |
|
|
| `/messages/{id}/delete` | POST | Delete message |
|
|
| `/messages/{id}/reply` | POST | Reply to message |
|
|
| `/messages/{id}/to-docs` | POST | Save attachments to ~/documents/inbox/ |
|
|
| `/messages/{id}/attachments` | GET | List or download attachments |
|
|
|
|
### Message Format
|
|
|
|
```json
|
|
{
|
|
"id": "proton:12345",
|
|
"source": "proton",
|
|
"from": "sender@example.com",
|
|
"from_name": "Sender Name",
|
|
"to": "recipient@example.com",
|
|
"timestamp": "2026-02-02T10:30:00Z",
|
|
"subject": "Hello World",
|
|
"body": "Message content...",
|
|
"attachments": [
|
|
{"name": "doc.pdf", "mime": "application/pdf", "size": 12345}
|
|
],
|
|
"seen": false
|
|
}
|
|
```
|
|
|
|
### Cursor/Acknowledgment
|
|
|
|
```bash
|
|
# Acknowledge messages up to a timestamp
|
|
curl -X POST http://localhost:8025/messages/ack \
|
|
-d '{"consumer": "james", "timestamp": "2026-02-02T12:00:00Z"}'
|
|
```
|
|
|
|
### Reply
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8025/messages/proton:12345/reply \
|
|
-d '{"body": "Thanks for your message!"}'
|
|
```
|
|
|
|
### Forward to Documents
|
|
|
|
```bash
|
|
# All attachments
|
|
curl -X POST http://localhost:8025/messages/proton:12345/to-docs
|
|
|
|
# Specific attachments
|
|
curl -X POST http://localhost:8025/messages/proton:12345/to-docs \
|
|
-d '{"attachments": ["invoice.pdf"]}'
|
|
```
|
|
|
|
## Configuration
|
|
|
|
```yaml
|
|
server:
|
|
host: 127.0.0.1
|
|
port: 8025
|
|
|
|
data_dir: ~/.message-center
|
|
|
|
accounts:
|
|
proton:
|
|
host: 127.0.0.1
|
|
port: 1143
|
|
username: user@example.com
|
|
password: ${PROTON_BRIDGE_PASSWORD}
|
|
tls: starttls
|
|
watch:
|
|
- INBOX
|
|
smtp:
|
|
host: 127.0.0.1
|
|
port: 1025
|
|
|
|
connectors:
|
|
whatsapp:
|
|
enabled: true
|
|
name: whatsapp
|
|
base_url: http://localhost:8030
|
|
|
|
webhook:
|
|
enabled: true
|
|
url: http://localhost:18789/hooks/messages
|
|
```
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
./install.sh
|
|
# Edit ~/.config/message-center.env with your passwords
|
|
systemctl --user start message-center
|
|
```
|
|
|
|
## Connectors
|
|
|
|
### Email (IMAP)
|
|
|
|
- Supports multiple accounts
|
|
- IDLE for real-time notifications
|
|
- Full message fetch with attachments
|
|
- Archive, delete, reply actions
|
|
|
|
### WhatsApp
|
|
|
|
- Wraps message-bridge HTTP API (port 8030)
|
|
- Polls for new messages (10s interval)
|
|
- Supports media attachments
|
|
- Reply via WhatsApp API
|
|
|
|
## Legacy Endpoints
|
|
|
|
For backwards compatibility with existing mail-bridge clients:
|
|
|
|
- `GET /accounts` - List accounts
|
|
- `GET /accounts/{account}/mailboxes` - List folders
|
|
- `GET /accounts/{account}/messages` - List messages
|