Reliable offline-first radio mail above an unmodified JS8Call instance.
JS8Mail is intended for dependable comms when Internet access is unavailable, including emergency and disaster scenarios. It keeps the mailbox, observations, routing decisions, retries, and audit history locally, then uses JS8Call for the actual RF modem and transmission. A message can be sent direct, relayed through stations suggested by observed RF evidence, or stored with a custodian for later collection.
Long messages are split into numbered JS8Mail parts for compatible peers. The receiver displays a useful partial message, marks missing parts, and can request only those parts again. Duplicate parts and receipts are safely ignored. A standard JS8Call recipient still receives readable ordinary text; enhanced JS8Mail framing is used only after the peer capability exchange proves support.
When an enhanced client later collects a message from a custodian, it can return a rate-limited JS8Mail capability and delivery-control notification toward the original sender using the recorded reverse path when available. These automatic exchanges are shown separately in the Outbox and are not themselves final delivery proof.
The project is early development and experimental. Delivery status is therefore carefully qualified: submission to JS8Call, a hop acknowledgement, custodian storage, and end-to-end JS8Mail delivery are different facts. Routing is progressive: a short direct reachability probe comes first, then current RF evidence, selective path discovery, alternative routes, bounded retries, and time-aware backoff. An optional, separate JS8Mail route-hints service can enhance local decisions with short-lived band-scoped reports from other stations. It is enabled by default and can be switched off in the UI. It never carries message content and is never required for RF operation.
See the changelog for release notes, including the
current 0.1.1 outbox, custody-route, scheduler, stored-message collection,
and network route-hints safeguards.
Each Outbox row has an Open action for the complete sent or in-progress message. The detail view includes its full subject and body, priority, sending mode, delivery evidence, timestamps, retry state, attempted routes, radio outcomes, and recent delivery history. View route graph closes the detail view and jumps directly to that message's graph.
Python 3.12 or newer is required.
From the repository directory, run:
./js8mailThe launcher creates or repairs the local .venv and asks before installing
the JS8Mail runtime. It then checks the usual JS8Call API endpoint and starts
the daemon with sensible defaults: automatic RF handoff, API 127.0.0.1:2442,
and web UI http://127.0.0.1:8765. Open that address in a browser. If JS8Call
is not running or its API is not enabled, the launcher gives setup guidance;
the daemon still starts and will reconnect when JS8Call becomes available.
Useful launcher commands:
./js8mail --check-only # validate Python, the environment, and API access
./js8mail --yes # allow first-run installation without prompting
./js8mail --tx-mode observe # receive/observe only; no RF handoff
./js8mail --no-install # never create or modify the local environmentTo make the command available from anywhere, optionally put a symlink to this
checkout's js8mail script in a directory on your PATH, such as ~/bin.
For development and tests, install the extra test dependencies explicitly:
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[test]'
pytestThe local mailbox can also be started directly with explicit options:
./js8mail --host 127.0.0.1 --port 2442 --ui-port 8765 --tx-mode automaticNetwork-assisted route discovery uses the JS8Mail route-hints service by
default. It can be switched off in the web UI, or pointed at another service
with --route-hints-url; the client remains usable if the service is
unavailable:
./js8mail --route-hints-url http://js8mail.oh3spn.fi:8787The web UI provides the final on/off switch. Route hints are advisory,
band-scoped, short-lived evidence used to wake discovery; they are not proof
of a usable route or delivery. No personal messages, mailbox contents,
message identifiers, or delivery receipts are shared—only short-lived
observations about heard stations and observed paths. Useful local claims are
published every 10 minutes. Network-only paths in an outgoing-message graph
are shown as purple dashed NET edges; local RF evidence takes priority.
Automatic submission hands text to JS8Call; the UI reports only delivery evidence actually observed. JS8Mail is suitable for supervised on-air use. The code is still at an early stage, so operators should monitor transmissions, use sensible power and radio settings and be ready to pause automation if anything behaves unexpectedly. Extensive testing has not revealed unexpected transmit loops, but future changes or unforeseen glitches cannot be guaranteed. Follow local licensing and band-plan rules.
JS8Call setup: enable its documented local TCP/JSON API on loopback (normally
port 2442), ensure JS8Call has the correct audio input/output devices, and
enable the heartbeat, relay, inbox/store-and-forward, and decode facilities
you want to use. JS8Mail does not edit unknown JS8Call configuration files;
the UI should be treated as setup guidance and the operator remains in control
of RF transmission. Intermediate stations may not have these facilities, so
the routing logic degrades to the strongest standard JS8Call behavior available.
For unattended operation, first confirm that it is permitted by your local
licence conditions and band plan. Always observe those conditions. If permitted,
disable JS8Call's operator-idle timeout (also called My Station Idle Time or, in
some builds, TxIdleWatchdog) and operating-system suspend on AC power; TCP
polling cannot reset that JS8Call safety timer.
Linux is the current development platform. A portable Windows bundle can be
built with PyInstaller on Windows; users of that bundle do not need to install
Python or manage a virtual environment. See builds/README.md
and the Windows bundle GitHub Actions workflow. The workflow produces a
downloadable JS8Mail.exe artifact using the standard API and web UI ports.
Windows packaging is experimental and not yet validated end-to-end with
Windows JS8Call, audio devices, or a radio.
For the complete operator guide—including JS8Call setup, TCP/API configuration, the end-to-end message lifecycle, path discovery, route scoring, custody, multipart recovery, groups, airtime protection, and troubleshooting—see the JS8Mail user and operator guide.
Also see the versioned JS8Mail protocol specification,
the API capability matrix, and
docs/IMPLEMENTATION_PLAN.md for protocol,
compatibility, and staged implementation boundaries.