sms-inbox-manager

SMS Inbox Manager

Context

Manage a lightweight SMS inbox served by sms_request_logger.py. The service receives forwarded SMS requests, persists them to JSON Lines, renders a password-protected list UI, highlights verification codes, linkifies URLs, and updates the browser in real time with Server-Sent Events (SSE).

Core Files

• App source: sms_request_logger.py
• Service unit example: sms-request-logger.service
• nginx example: nginx.example.conf
• Contributor guide: AGENTS.md
• Default local message store: ./data/sms_messages.jsonl
• Default local raw/debug log: ./data/sms_requests.log

Production data/log paths should be configured with environment variables, not hard-coded.

Runtime Shape

• App listens on 127.0.0.1:18080.
• nginx should proxy all site paths to http://127.0.0.1:18080.
• The service uses only the Python standard library and ThreadingHTTPServer; there is no framework or database.
• The frontend subscribes to /api/stream with EventSource; if SSE repeatedly fails, it falls back to polling /api/messages.

Routes And Auth

• /: password-protected SMS list page.
• /login: POST endpoint for password login.
• /logout: clears the auth cookie.
• /add?msg=...: legacy ingest endpoint for URL-encoded multi-line SMS text.
• /add?sender=...&message=...&timestamp=...: newer ingest endpoint. Optional fields include local_number, network_addr, and remark.
• /api/messages: authenticated JSON snapshot of inbox stats and pre-rendered message list HTML.
• /api/stream: authenticated SSE stream. It sends a messages event when the inbox signature changes and : keepalive comments periodically.
• /?token=<password>: authenticates via URL parameter, writes the login cookie, and redirects to /.

Authentication is controlled by SMS_INBOX_PASSWORD. Treat passwords, domains, phone numbers, and message content as sensitive.

Data Model

The JSONL store has one object per line. Important fields:

• server_at: server receive time in ISO format.
• sender: SMS sender.
• content: SMS body shown in the UI.
• code: detected verification code, usually 4-8 digits.
• is_code: boolean derived from whether code exists.
• sim, sub_id, sms_at, device: parsed metadata when available.
• raw: original forwarded SMS payload.
• source_ip: requester IP when available.
• network_addr, remark: optional fields for ESP32-style payloads.

The UI formats timestamps as YYYY-MM-DD HH:MM:SS. Keep JSONL storage unchanged unless explicitly doing a migration.

Common Commands

Check runtime state:

systemctl is-enabled sms-request-logger.service
systemctl is-active sms-request-logger.service
systemctl show sms-request-logger.service -p MainPID -p ActiveState -p SubState --no-pager
ss -ltnp | rg ':18080\b'

Compile and restart after edits:

python3 -m py_compile sms_request_logger.py
sudo systemctl restart sms-request-logger.service
systemctl is-active sms-request-logger.service

Local development:

SMS_INBOX_PASSWORD=change-me python3 sms_request_logger.py

Validate/reload nginx after vhost edits:

sudo nginx -t
sudo nginx -s reload

Inspect configured data and logs:

tail -n 20 ./data/sms_messages.jsonl
tail -f ./data/sms_requests.log
sudo tail -n 80 /var/log/nginx/realtime_sms_inbox.error.log

Local HTTP tests:

curl -sS -i 'http://127.0.0.1:18080/'
curl -sS -i 'http://127.0.0.1:18080/?token=change-me'
curl -sS -i 'http://127.0.0.1:18080/add?msg=10086%0Acode%3A%20123456'
curl -sS -i 'http://127.0.0.1:18080/add?sender=10086&message=code%3A%20123456&timestamp=2026%2F06%2F28+13%3A42%3A59'

Authenticated API/SSE checks:

AUTH_HASH=$(python3 - <<'PY'
import hashlib
password = b"change-me"
print(hashlib.sha256(b"sms-inbox:" + password).hexdigest())
PY
)
curl -sS -i -H "Cookie: sms_auth=$AUTH_HASH" 'http://127.0.0.1:18080/api/messages'
curl -sS -N -H "Cookie: sms_auth=$AUTH_HASH" 'http://127.0.0.1:18080/api/stream' | sed -n '1,4p'

Maintenance Guidance

• Before editing data, back up the configured JSONL file.
• Use apply_patch for source edits.
• Keep nginx routing broad: all paths for the public host should proxy to 127.0.0.1:18080 unless changing architecture.
• When changing the password, update SMS_INBOX_PASSWORD, restart the service, and ask users to refresh/login again.
• If requests do not arrive, check DNS, nginx access logs, nginx error logs, service status, and port 18080 in that order.
• If the UI shows stale data, check whether new lines were appended to the JSONL store, then verify /api/stream returns text/event-stream and /api/messages returns fresh JSON with an authenticated cookie.
• For real-time UI issues, remember that /api/stream is the primary path and /api/messages is a fallback; do not reintroduce meta refresh unless explicitly requested.
• Avoid deleting request logs; they are useful for debugging forwarding issues.