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

{
  "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

# Acknowledge messages up to a timestamp
curl -X POST http://localhost:8025/messages/ack \
  -d '{"consumer": "james", "timestamp": "2026-02-02T12:00:00Z"}'

Reply

curl -X POST http://localhost:8025/messages/proton:12345/reply \
  -d '{"body": "Thanks for your message!"}'

Forward to Documents

# 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

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

./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