Features

Everything in the box

Installation

One container, one volume, one port

Hmelj needs Node.js 24 or newer and nothing else — no database server, no Redis, no external services. The published image is built for linux/amd64 and linux/arm64, so it runs on a normal server and on a Raspberry Pi 4/5, a Synology or an ARM VPS alike.

Docker Compose (recommended)

services:
  hmelj:
    image: ghcr.io/thehijacker/hmelj:latest
    container_name: hmelj
    restart: unless-stopped
    ports:
      - "3000:3000"
    env_file: .env
    volumes:
      - hmelj-data:/data

volumes:
  hmelj-data:

PORT=3000
# Encrypts stored mailbox passwords. Leave it unset and Hmelj generates
# /data/secret.key on first start instead — either way, BACK IT UP.
# HMELJ_SECRET=a-long-random-string

docker compose up -d

Hmelj is now at http://localhost:3000. Go to First Run.

environment:
  - PUID=1000
  - PGID=1000
volumes:
  - /srv/hmelj/data:/data

Plain Docker

docker run -d \
  --name hmelj \
  --restart unless-stopped \
  -p 3000:3000 \
  --env-file .env \
  -v hmelj-data:/data \
  ghcr.io/thehijacker/hmelj:latest

The image runs as the non-root node user, keeps all state in the /data volume, and carries a healthcheck that polls /healthz every 30 seconds — so docker ps tells you whether it is actually serving, not merely running.

From source

git clone https://github.com/thehijacker/hmelj.git
cd hmelj
npm ci
cp .env.example .env      # read it through, then edit
npm start                 # → http://localhost:3000

There is no build step. public/ is served exactly as it is on disk, so an edit shows up on the next refresh.

To try it without a real mail server, Hmelj ships a mock IMAP + SMTP pair with sample messages:

npm run mock    # IMAP on 127.0.0.1:1143, SMTP on 127.0.0.1:1025
npm start       # in another terminal

Sign up, then in the account wizard choose IMAP + SMTP and enter 127.0.0.1 port 1143 for IMAP and 1025 for SMTP, user testuser, password testpass, TLS off, "allow self-signed" on.

Run the test suite with npm test — 19 suites, no framework, no network.

Reverse proxy & TLS

An nginx location block that works:

location / {
    proxy_pass         http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header   Host              $host;
    proxy_set_header   X-Real-IP         $remote_addr;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   Upgrade           $http_upgrade;
    proxy_set_header   Connection        "upgrade";

    # Attachments and uploads
    client_max_body_size 50m;

    # Server-Sent Events (/api/events) must not be buffered, or cross-device
    # updates arrive in delayed bursts instead of instantly. Hmelj already sends
    # X-Accel-Buffering: no, which nginx honours by itself — this is only needed
    # if something in front of nginx strips that header.
    # proxy_buffering off;
    proxy_read_timeout 3600s;
}

systemd (without Docker)

[Unit]
Description=Hmelj webmail
After=network.target

[Service]
Type=simple
User=hmelj
WorkingDirectory=/opt/hmelj
EnvironmentFile=/opt/hmelj/.env
ExecStart=/usr/bin/node --openssl-legacy-provider server/index.js
Restart=on-failure

[Install]
WantedBy=multi-user.target

Updating

docker compose pull
docker compose up -d

The volume is untouched, so accounts, settings, filters and the cache all survive. The browser picks up the new front end on the next load — Hmelj's service worker is network-first for the app shell, so there is no stale-cache dance. If a page looks half-updated, one hard refresh settles it.

Data Directory

Everything Hmelj knows, in one place

DATA_DIR (/data in the container, ./data from source) holds all persistent state. Back up this directory and you have backed up Hmelj.

/data
├── auth.json                   Hmelj login accounts (scrypt-hashed passwords, admin flag)
├── secret.key                  AES-256-GCM key for stored mailbox credentials (mode 600)
├── presets.json                account presets, editable in Settings → Admin
├── oauth.json                  OAuth client IDs (Google's secret encrypted), mode 600
├── fcm-service-account.json    optional: Firebase key for Android push (you add this)
├── cache.sqlite                message cache, analytics index and the per-user
│                               error log (+ its -wal and -shm sidecars)
└── users/
    └── <user>/
        ├── accounts.json       mail accounts; passwords and OAuth tokens encrypted
        ├── settings.json       that user's settings
        ├── identities.json     identities and signatures
        ├── contacts.json       address book
        ├── filters.json        filter rules
        ├── push-subscriptions.json  every device registered for notifications
        ├── accountOverrides.json    per-viewer tweaks to a shared account
        ├── refile-origins.json  where spam/archived mail came from, for the trip back
        ├── unsubscribed.json    newsletters already unsubscribed from
        ├── holiday-overrides.json / custom-holidays.json  scheduler calendar edits
        └── scheduled/           one file per queued scheduled send

Putting the cache somewhere else

cache.sqlite is written constantly by the background sync, and those writes are synchronous. If DATA_DIR sits on network-attached storage — NFS, SMB, a NAS mount — a slow write can block Node's event loop and stall completely unrelated work, including interactive requests. Point just the cache at fast local disk:

CACHE_DIR=/var/lib/hmelj-cache

The cache is disposable. Deleting it costs nothing but a re-sync.

First Run

From an empty container to reading your mail

The first user is the admin

There is no default account and no default password. Open Hmelj, click Sign up, and pick a username and password. That first account is automatically an admin: it gets a Settings → Admin tab where it can manage other users, control sign-ups, register OAuth clients, edit account presets and upload fonts.

Hmelj accounts are entirely separate from mail accounts. The password you choose here is a Hmelj password, hashed with scrypt in auth.json; it is never sent to any mail server.

Letting others sign up

By default anyone who can reach the page can create an account. Once your household or team have theirs, turn it off — either with ALLOW_SIGNUP=false in the environment, or at runtime in Settings → Admin → Sign-up. The very first user can always register, so you cannot lock yourself out of a fresh install.

Attaching a mailbox

A brand-new Hmelj account has no mail in it, because it has no mailbox yet. Open the user menu (your avatar, bottom left) → Mail accounts → Add mail account, and follow Accounts.

The wizard tests the connection before saving, so a typo in a hostname or a wrong password fails there and then rather than becoming a mysteriously empty inbox.

Accounts

Attaching mailboxes, and what each type needs

Account types

Mix them freely. Every type ends up in the same list, the same folder tree and the same unified inbox; the differences are noted where they exist.

The wizard, field by field

Shared by every type:

• Account name — what you call it: Home, Work, GMX. Shown on the account chip.
• E-mail address — the address this mailbox is; also the default IMAP username.
• Sender name — shown next to your address on outgoing mail.
• Colour — one of the swatches or a custom colour, used for this account's chip everywhere in the UI.

IMAP + SMTP only:

• Provider — an optional preset that prefills the server fields (see Account presets).
• Incoming (IMAP) — server and port, username (defaults to the e-mail address), password, Use TLS, Allow self-signed certificate.
• Outgoing (SMTP) — Same server as IMAP and Same credentials as IMAP are on by default and hide the fields they cover; untick either to set them separately.

Exchange (EWS) only: the full https://…/EWS/Exchange.asmx URL, the NTLM domain if your server requires one, username, password, and an Allow self-signed certificate option.

The two sign-in types have no server, port or password fields at all — signing in is the configuration. You pick a provider and press Sign in; the provider's own page opens in a separate window (or your browser, in the Android app). Hmelj never sees your password, only the token the sign-in hands back, encrypted like every other credential.

Finish with Test & save. Hmelj connects, verifies the credentials, and auto-detects the Sent, Drafts, Trash, Junk and Archive folders from the server's own IMAP SPECIAL-USE flags — including Gmail's [Gmail]/… names. Only then is anything saved.

Checking for new mail

Set per account, in the wizard's New mail section. This is the single biggest lever on how quickly mail appears and how much load Hmelj puts on the server.

Mix freely — watch your main mailbox live and check a low-traffic one every 15 minutes. Live accounts still run a slow background poll as a safety net, so a dropped watcher costs latency and nothing else. Accounts that say nothing default to SYNC_INTERVAL_MS.

A second connection

By default Hmelj holds one IMAP connection per account and every operation takes an exclusive lock on it, so opening a message can end up queued behind an in-flight background sync. Allow a second connection lets background sync use its own.

Sharing an account

Settings → Accounts → Share on an account you own, then type another Hmelj user's username. They see that mailbox in their own account list, badged 🔗 Shared by <your username>, and can read it and send through it.

What stays with the owner:

• Special-folder mapping, and creating, renaming, deleting or emptying folders — these touch the real mailbox.
• Which folders are synced. A folder the owner excluded has nothing cached, so the grantee cannot show it either.
• The credentials. A grantee never sees them and cannot edit the connection.

What the grantee gets of their own: which of the account's folders appear in their sidebar, and their own identities for sending through it. Revoking access (the ✕ on the grantee's chip) removes both.

Gmail

Two ways in, and the trade-off between them

Google stopped accepting an ordinary account password over IMAP years ago. Hmelj offers the two things it does still accept:

App password

Username is your full Gmail address; the password is the app password, with the spaces removed.

Sign in with Google

Choose the Gmail (sign in with Google) account type, press Sign in, and complete Google's own sign-in page in the window that opens. There is nothing else to fill in — Hmelj already knows Gmail's servers.

Google will warn that this app is not verified. That "app" is your own Hmelj server, registered by your own admin in their own Google Cloud project. Choose Advanced → Continue.

Creating the Google client ID (admin, once)

This is done once per Hmelj server by an administrator. It is free, and the client stays yours — Hmelj deliberately has no shared client to fall back on.

https://your-hmelj-host/oauth/callback

Settings → Admin → OAuth providers shows the exact string for your instance — copy it from there. It must match byte for byte.

Instead of the Admin UI you can set GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET in the environment; those win, and the Admin fields then show as read-only.

Microsoft / Outlook

Outlook.com, hotmail.com, live.com and Microsoft 365

Microsoft no longer accepts a password for IMAP or SMTP on these accounts — not even an app password. They sign in with OAuth2, and Hmelj then talks to the mailbox over Microsoft Graph. You complete the real Microsoft sign-in page once; Hmelj stores the resulting refresh token, encrypted with the same key as everything else.

Why Graph, not IMAP with a token

Microsoft does still support IMAP with an OAuth token — but IMAP has to be switched on for the mailbox itself, and it is off by default on personal Outlook.com accounts. The result is a sign-in that visibly succeeds followed by User is authenticated but not connected, a failure with no obvious cause and no fix inside Hmelj. Graph never touches that stack, so there is nothing to enable in your Outlook settings.

Creating the app registration (admin, once)

You need your own Microsoft app registration. It is free, takes a few minutes, and stays yours.

https://your-hmelj-host/oauth/callback

openid and email are also requested, purely so the token response carries an id_token Hmelj can read the signed-in address out of — that is what catches "you typed one address and signed in as another".

Telling Hmelj about it

The environment-variable equivalents are MS_OAUTH_CLIENT_ID and MS_OAUTH_TENANT.

Hmelj translates Microsoft's AADSTS… codes into what to change and where, while keeping the original text — it carries the trace IDs Microsoft support asks for.

What behaves differently

• New mail on Live monitoring is a 30-second poll of the Inbox counts, not true push (see Checking for new mail).
• "Replied to" markers are not tracked. Graph exposes that only as an extended MAPI property.
• Everything else — read, send, reply, flag, move, delete, drafts, search, attachments, filters, the unified inbox — behaves exactly as it does for an IMAP account.

Exchange (EWS)

On-premises Exchange, over NTLM

For an Exchange server on your own network that speaks Exchange Web Services. Tested against Exchange 2013; later versions use the same protocol.

Reading, sending, moving, deleting, flagging, search, contact import, calendars and meeting responses all work, and so does managing folders — create, rename, move, delete and empty. Live monitoring is a 15-second pull subscription: Exchange reports exactly what changed since the last watermark, which is more reliable than a timer on a busy mailbox.

Identities & Signatures

Who a message is from, and what it ends with

An identity is a from-address plus the details that travel with it. Every identity is linked to a sending account, so a reply from your GMX identity goes out through GMX's SMTP and lands in GMX's Sent folder. Aliases are just extra identities on the same account.

Settings → Identities. Each one has:

• Name and e-mail address — what recipients see
• Organization and Reply-To — optional headers
• Account — which mailbox actually sends it
• Default — the one preselected in a new message
• Signature, with its own policy: new messages only, new messages and replies, always, or never

The signature is placed above the quoted original on a reply or forward — where a person reads it — rather than at the very bottom under the whole thread.

Folders

The tree, the special ones, and what shows in the sidebar

Hmelj shows the account's full IMAP folder tree. Settings → Folders manages it, one account at a time.

Special folders

Five roles are mapped to real folders: Sent, Drafts, Trash, Junk/Spam and Archive. Hmelj auto-detects them from the server when the account is added — using IMAP SPECIAL-USE flags, which is what makes Gmail's [Gmail]/Sent Mail land in the right place. Fix the mapping here if sending or saving a draft ever files something in the wrong folder.

Junk and Archive may be set to (None), and that genuinely means none: Mark as spam and Move to Archive then stop appearing in the message menus for that account.

Managing folders

• Show in sidebar — per folder, per account. Hiding a folder does not delete anything.
• Create, rename, delete, empty — these act on the real mailbox.
• Mark all as read and Mute live on the folder's own right-click menu in the sidebar.
• Each folder shows its message and unread counts.

What gets synced

The background sync does not walk every folder. It covers the Inbox and its subfolders plus Sent — that is what the unified views and the fast lists are built from. Other folders are browsed live against the server when you open them, and are always fully reachable through Search everywhere.

The Message List

Everything you can do without opening anything

All inboxes vs one account

The account switcher at the top of the sidebar chooses between All inboxes — a merged Inbox and merged Sent across every account, with a coloured chip on each row naming its source — and one account's own full folder tree.

The unified view spans every folder of an account except Sent, Trash, Junk and Drafts, so mail your server filed into a subfolder still shows up there.

Right-click / long-press

Right-click a row on a desktop, long-press it on a phone:

• Mark as read / unread
• Mark as spam or Not spam, and Move to Archive or Move out of Archive — whichever the account has folders for
• Delete

Select mode

Ctrl+click (Cmd on a Mac) a row turns select mode on and ticks it; from then on an ordinary click keeps toggling. Then act on the whole selection at once — delete, move, mark read or unread. Desktop only: a touch screen has no modifier key, and long-press already means something on these rows.

Shift+click takes a whole run at once: click a message, hold Shift, click one further down, and everything between them is ticked, both ends included. It works before select mode is on and after, and it only ever adds — a second Shift+click extends the run rather than re-cutting it, so a mis-aimed click cannot quietly unpick messages you had already chosen.

Escape

Escape dismisses whatever is on top — a dialog, the theme picker, the attachment preview, compose (through its usual save-or-discard prompt), Settings, mailbox analytics — one layer per press, in the order they are stacked on screen. It is the keyboard's version of the phone's back key, which walks the same list.

It stops at the last overlay, deliberately. The back key carries on into the page itself — closing the message you are reading, then returning to All inboxes — and Escape doing that would be a surprise rather than a convenience.

Ticking a conversation row selects every message in it — but never the copies in Sent, so deleting an inbox thread never deletes your own replies.

Swipe gestures

On a phone, drag a row sideways. Past about a third of the width the action fires: read/unread one way, delete the other. Which direction does which is a setting, and the whole gesture can be turned off. A swipe-delete can be taken back from the message that appears afterwards.

Spam and Archive

Neither entry appears unless the account actually has that folder — the answer comes from the server's own folder list, so the menu can never offer something that then fails. Hmelj also stands in the server's real \Junk / \Archive folder if the stored name has gone stale.

On the way out, where each message came from is written down. On the way back, Not spam returns each message to the folder it actually left — one move per remembered folder, and the Inbox for anything unrecorded, which is the common case since most spam was filed by the server and was never anywhere else. Both directions are optimistic and offer an Undo.

Snooze

A message you cannot deal with now, back in front of you when you can. Right-click a row (long-press on a phone) → Snooze…, or press z. Pick Later today, Tomorrow morning, This weekend, Next week, or an exact date and time.

The message really moves, into a Snoozed folder created on the account the first time you use it, and comes back to where it was at the time you chose — marked unread, with a notification. It moves for a reason: hiding it only inside Hmelj would leave it sitting in the Inbox on your phone, in Thunderbird, and in your provider's own webmail.

• A 🕰️ Snoozed row appears in the sidebar with a count, listing what is waiting and when each one is due. The Snoozed folder itself is not shown there — it would be a second, worse entry for the same thing, saying that a message is gone without saying when it comes back. It is still a real folder on the server, visible from Outlook and from your phone, and it is listed in Settings → Folders marked as Hmelj's.
• Click one, or use its menu, to bring it back now or change the time.
• If Hmelj is not running when a message comes due, it comes back as soon as Hmelj is. Nothing is missed, it is just late.
• Moved a snoozed message somewhere yourself in the meantime? That is treated as your decision — Hmelj drops the reminder rather than dragging the message back out of where you filed it.

Sorting and filtering

The list header sorts by date, sender or subject. The toolbar filters to unread only or starred only. Note that a filter or a search switches conversation grouping off — a count that meant "matching messages" rather than "messages" would be misleading.

Reading a Message

What the reading pane does, and why

Message bodies are sanitised on the server and then rendered inside a sandboxed iframe with no same-origin access. A newsletter's own CSS therefore cannot reach out and restyle Hmelj, and its scripts never run at all. <style> blocks and inline styles are kept, because that is what makes newsletters look like themselves; @import, expression() and behavior are always stripped.

Every person in the header — From, To and Cc — is a chip showing both the display name and the address. Right-click or long-press one for Copy address and New message.

Is the sender who they say?

When a message arrives, the receiving mail server checks it against the rules the sender's domain publishes — SPF (was this server allowed to send for that domain), DKIM (is the signature intact) and DMARC (does the domain in the From line stand behind either result) — and writes the outcome into the message. Hmelj reads that verdict back out and shows it.

Only the topmost verification header is read — the one your own server wrote. Anything below it arrived with the message and was written by whoever's honesty is the question, and a convincing forged "everything passed" is trivial to include. If your mail passes through several of your own servers before reaching the mailbox, the account can be told which one to trust by name (authservId, settable through the accounts API; there is no field for it in Settings yet).

Turn the whole thing off with Show whether the sender is verified in Settings → Reading.

Dark mode and unreadable mail

A lot of HTML mail hard-codes its own colours — black text, a white panel — on the assumption that it will be read on white. In the dark theme that arrives as black text on a near-black background.

Hmelj repairs it, on two passes. Backgrounds an element sets for itself are dropped in favour of the theme's, except where doing so would strand that element's own text (white on grey is deliberate, and stripping the grey leaves white on white). Then every piece of text is measured against what it actually ends up sitting on, and only the ones that genuinely fail are repainted in the theme's own colour — the link colour, inside a link.

The test is contrast, not the theme, so the same pass fixes white-on-white in the light theme. Mail that was already readable is left exactly as its sender wrote it. Where it does step in, the sender's colour choice is replaced rather than nudged: keeping the hue would mean inventing a colour they did not pick either, and the result is at least the colour the rest of the message is in.

External images

Remote images are the standard way a sender learns you opened their mail. Settings → Reading offers four policies:

The banner also offers trust this sender's domain, which adds it to the list in one click. CSS url(...) loads follow exactly the same policy as <img> tags, so a tracking pixel cannot hide in a background image.

Collapsed quotes

A reply shows what was written this time; the quoted conversation underneath it sits behind a ⋯ button. Detection runs on the server, on the sanitised HTML, and plain-text messages split on the usual quote markers.

Unsubscribe

Newsletters that publish a List-Unsubscribe header get an Unsubscribe button under the header. Three ways out, preferred in this order:

1. An RFC 8058 one-click POST, sent by the server — a browser cannot POST cross-origin.
2. A mailto: unsubscribe message.
3. Opening the sender's page, done by the browser inside your click so no pop-up blocker eats it.

Most senders publish no header at all, so Hmelj falls back to finding the unsubscribe link in the message footer. A body link is a guess, so it is only ever opened — never posted to, never mailed — the banner says where it came from, and links inside a collapsed quote are ignored.

On by default, with a compact mode (also default) that folds the banner to just the 📭 icon and the button; clicking the icon unfolds the explanation for that message. Both in Settings → Reading.

Attachments

Attachments appear as chips under the message. Clicking one opens a preview overlay for images, PDFs, audio and video; anything else downloads.

• The download shows a progress bar with the real byte count, and can be cancelled.
• Video streams rather than buffering, so a large file starts playing immediately.
• Once fetched, an attachment is remembered by the browser and by the server, so a second look is instant.
• In the Android app, a non-previewable attachment is handed to whichever app can open it.
• From two attachments up, a Download all chip appears beside them and hands over the lot as a single .zip, named after the message.

The archive is built on the server, because that is where the parts are — each one is its own fetch from the mail server, through the same cache a single download uses, so bundling a message whose attachments you have already opened costs nothing extra. Embedded images (a newsletter's logo and spacers) are left out: they are part of the body, and the chips do not list them either. Two attachments that happen to share a filename both come out, numbered the way a file manager would — a .zip tolerates duplicate names and most unpackers silently keep only the last.

Find in message

Ctrl+F (Cmd+F on a Mac) over an open message, or ⋯ → Search in message. Live match count, ↑/↓ or Enter / Shift+Enter to step through, and each hit is scrolled clear of the floating bar. The search runs inside the sandboxed frame and highlights without modifying the message.

Calendar invitations

A message carrying a meeting invitation shows the event details and three buttons — Accept, Tentative, Decline. Each opens a small menu:

• Send the response now
• Edit the response first — add a message to the organiser
• Do not send a response — answer for your own records only

Read receipts

When a sender asks for a read receipt, Hmelj shows a banner and lets you decide. Nothing is confirmed automatically. You can also request one on your own outgoing mail — per message in the composer, or by default in Settings → Compose.

The ⋯ menu

Every open message has one, carrying:

• Reply, Reply all, Forward
• Mark as read / unread
• Move, and the Spam / Archive entries the account supports
• Search in message
• View headers — the full header block, copyable, and Save as EML next to it
• Print
• Open in new view (desktop only)
• Delete

Conversation View

A message and its replies as one row

Off by default — turn it on in Settings → General. With it on, a message and its replies collapse into a single list row carrying a count chip. Opening that row stacks the whole conversation in the reading pane, oldest at the top, newest at the bottom and scrolled to.

• Only the newest message is expanded; the rest are one-line headers you click to open. Expand every message in a conversation (Settings → General) changes that — at the cost of one fetch per message, so a long thread takes longer to open.
• The scope is the folder you are looking at, plus Sent, so your own replies appear inline between the incoming ones. Opened from All inboxes, the scope is the same set of folders that view spans, plus Sent.
• Actions on a conversation row never touch the copies in Sent.
• Each message is marked read as it is expanded — opening a 20-message thread does not silently mark all of it read.

How messages are grouped

By the root of the References chain, computed once for each message on its way into the cache. Every message in a chain therefore derives the same key independently of the order they arrive in. Microsoft Graph and Exchange use their own ConversationId instead, which is better than anything reconstructed from headers.

Subject-based merging is deliberately not done. It is what makes threading glue unrelated mail together; header threading covers the overwhelming majority.

Composing

Writing, quoting, scheduling, sending

The composer is a floating window, so you can keep reading while you write. Open it with the Compose button, or from Reply / Reply all / Forward on any message.

The editor

• Rich HTML or plain text, per message; the default is a setting.
• Font, size, text colour and highlight, B / I / U / S, bulleted and numbered lists, and links.
• From chooses the identity — and with it, which account actually sends.
• Cc and Bcc, revealed on demand.
• Priority — one button in the footer, whose arrow and colour say which of the three is set (↑ red, ↓ green, and an unremarkable ≡ for normal) — and Request a read receipt, per message.
• Attachments — pick files or drag them in. Forwarding carries the original's attachments.
• An emoji picker, with categories and a Recent row that fills up with the ones you actually use.
• The buttons light up for the formatting the cursor is inside, so the bar says what you are standing in rather than only what you can turn on.
• ⋯ holds everything used less often: quote, code block, indent and outdent, alignment, a horizontal line, clear formatting, templates, and which signature this message uses.
• Recipient fields autocomplete from your address book, from your contact groups, and from your own identity and account addresses (badged you, and never stored as contacts).

On a phone the toolbar scrolls sideways rather than wrapping onto three rows — the message is what matters on a small screen, and a swipe to reach the last two buttons costs less than two thirds of the writing area. The spell-check language and the Plain switch sit outside the scrolling part, because they say what the composer currently is and should not be able to scroll out of sight.

In plain text mode the formatting controls grey out, as there is nothing for them to do — except emoji, which stays available. An emoji is a character, not formatting.

On a desktop the composer remembers whether you keep it enlarged and opens that way next time. On a phone it is always full-page, which is not remembered and not negotiable — a 560px floating panel is unusable there.

Signatures

An identity can have several — a full one for new mail, a two-line one for replies, one for a different language. They are edited in Settings → Identities, on the identity they belong to: name each one, mark one Default, and add or remove them freely.

The default is what a message starts with. To use a different one, open ⋯ → Signature in the composer and pick it — the one already in the message is replaced, not added to, and None takes it out altogether. That choice applies to the message you are writing and is forgotten afterwards; it does not change the identity.

An identity that has always had a single signature keeps it, as its one entry, named Signature. Nothing needs migrating by hand.

The recipient fields

Start typing in To, Cc or Bcc and the suggestions appear: your own addresses first, then any matching group, then contacts. ↑/↓ move, Enter or Tab takes the highlighted one, Esc closes the list without leaving the field.

A group goes in as a single token — 👥 Družina — and is turned into real addresses when the message is sent.

Backspace takes a whole recipient, group or person, when the cursor sits just after one: the first press highlights it, the second removes it, exactly as it works with Outlook's chips. Typing instead simply replaces it. In the middle of an address Backspace still deletes one character, so correcting a typo works as it always did.

Delete is different on purpose: with the suggestion list open it means remove this contact from my address book, and it asks twice — one press arms the highlighted row, the second removes it. A right-click or long-press on a row offers the same thing as a menu. Neither works on a group or on a contact synced from another server; those are removed in Settings → Contacts, where the row says where it lives.

Where the quoted original goes on a reply — below your reply, above it, or not at all — is a setting. The signature goes above the quote either way.

Attachments and images

Three ways to put a file in a message, all of which do the same thing:

• the 📎 button
• drag files onto the composer — anywhere on it
• paste — Ctrl+V a screenshot straight from the clipboard

An image pasted or dropped into the message body appears where the cursor is, as part of the text. Dropped onto the header or the attachment strip instead, it is attached as a file. In plain-text mode there is no such thing as an inline image, so a pasted one is always attached.

Pasting ordinary text is unaffected, including from a spreadsheet or a web page — those put both an image and the real content on the clipboard, and Hmelj takes the content.

Drafts

Drafts autosave to the account's Drafts folder on an interval you choose (0 disables it), and can be saved by hand at any time. Open one from Drafts to carry on writing — with its attachments and inline images intact, fetched back from the server as the draft opens.

Scheduled sending

Instead of sending now, pick a time. The message is queued on the server, so it goes out whether or not your browser is open.

• Queued messages appear in a Scheduled view with their send time, account badge, and a click-to-read preview.
• Right-click or long-press one to Reschedule or Cancel and edit.
• A send that fails is retried with a growing backoff, and the reason is shown on the queued message and recorded in Settings → Log.

Undo send

Send holds the message back for a few seconds first, and the toast that appears offers Undo. Take it and the message comes straight back into the composer, exactly as you wrote it. Ignore it and the message goes out when the time is up.

Undo send window in Settings → Compose sets how long: ten seconds by default, up to two minutes, 0 to send immediately.

Before it goes out

Two checks, both optional, both in Settings → Compose.

• Warn about a missing attachment. If what you wrote mentions an attachment and nothing is attached, Hmelj asks before sending. It reads English and Slovenian, including forms typed without šumniki (prilozeno counts), and matches the stems rather than exact words, so priloga, prilogi and prilagam all trigger it.
• Offer Reply to all. Press Reply on a message that had other people on it and Hmelj offers to include them. A message addressed only to you never asks.

Templates

Text you send over and over — a standard reply, a set of directions to the office, a disclaimer. Write them in Settings → Templates, then insert one while composing from the ⋯ menu.

They are written with the composer's own toolbar — the same font, size, colour, lists, links, quote and code block — because a template is going into a message, so the options for writing one are the options for writing the other. The same editor is used for signatures, with two extra buttons those need: insert an image, and edit the HTML source.

A template lands where your text is — at the caret, above the signature and above the quoted message, never underneath your sign-off. Templates are yours alone: they are not shared with anyone you share a mailbox with.

Spell checking

On by default. Slovenian and English, detected automatically from what you are writing. Spelling only — no grammar. Turning it off hands the job back to your browser's own spellchecker.

Search

Gmail-style syntax, and an honest answer about what was searched

Syntax

An unrecognised word: prefix — a URL like http://example.com, or a time like 10:30 — is not treated as a field scope at all. It is kept as plain text exactly as typed, rather than silently losing everything before the colon.

Search box autocomplete (Settings → General) finishes words as you type, suggested from your own mail history. The suggestion appears as selected text, so just keep typing to ignore it — or Tab to accept.

What actually gets searched

By default, the local cache: each folder's newest messages, indexed by subject, sender and recipients. That is fast, and on a small mailbox it is also complete — but on a mailbox with tens of thousands of messages and a 250-message-per-folder window, "two results" can look like the whole truth when it is not.

So Hmelj says so. Under the results is a line naming what was searched, with a Search everywhere link. That asks the server instead: every folder of the account — including All Mail where the provider has one, which is the only place archived Gmail lives — and message bodies too. It is a live search per folder and can genuinely take seconds, so it says that while it runs.

Raise the cached window with Messages kept per folder in Settings → General if you would rather have more of it answered instantly.

Searching inside messages

Hmelj can keep a full-text index of the message bodies it has already cached, so body: searches — and bare words — are answered from disk in milliseconds instead of by asking the mail server one folder at a time.

It is off by default and turned on per account, in Settings → Accounts, on the account's own row. That is deliberate: most people search two mailboxes constantly and the rest almost never, and there is no reason to spend disk on the rest.

Accented and unaccented spellings match each other, both ways — racun finds račun and račun finds racun — and a word matches from its start, so prilog finds prilogi and priloge.

A body search only ever reaches what has been cached. Search everywhere is still there, and still the way to reach a ten-year-old message in an archive folder.

Saved searches

A search you keep retyping can be pinned. Run it, then click Save this search in the line under the results and give it a name. It appears in the sidebar under a 🔎, below your folders.

A saved search stores the question, not the answer: opening one re-runs it, so it is always current. Rename, reorder and delete them in Settings → Saved searches.

Unread counts

Each pinned search carries the same unread badge as the folders above it, so anything new in Invoices? is answered without opening it. The number is worked out on the server, from the local cache, in the same request that already feeds the folder badges — it costs no extra round trip and never asks your mail server.

That has one visible consequence, and it is deliberate. The count reaches exactly as far as the cache does — the newest messages of each folder, the same window every folder badge already uses. A search Hmelj cannot answer from the cache on its own, meaning a body: term over an account with no full-text index, shows no badge at all rather than a number that would be wrong. Opening it still searches properly.

Keyboard Shortcuts

Gmail's letters and Outlook's combinations, both

Press ? anywhere in the mail view for the whole list without leaving the page. Shortcuts do nothing while you are typing in a field, and never fight a browser or system shortcut — anything with Alt or Cmd held is left alone.

The cursor is not the open message. j and k move an outline around a row without opening it, and that outlined row is what the next Del or e acts on. Acting on a row moves the cursor to the next one, so a run of mail can be cleared without looking back at the screen. If you have not moved the cursor at all, the shortcuts act on whatever is open.

They work with the caret inside a message body too, even though that body is a sandboxed frame with a document of its own — keystrokes are handed back out to the app.

Nothing here fires while you are typing in a field, so Backspace in the composer's To, Cc and Bcc means something else entirely — it takes a whole recipient rather than deleting a message.

The calendar has its own small set, listed under The views: ← → to page, t for today, and m w d a to switch view.

Filters

Rules that run on the server

Settings → Filters. Each filter belongs to one account, has a name, can be enabled or disabled, and combines conditions with actions.

Matching

Three modes: All rules must match, At least one rule matches, or All messages (no conditions at all).

Actions

• Move to folder / Copy to folder — a dropdown of that account's real folders
• Redirect to address — forwards the message on
• Reply with message — an auto-reply; each sender is answered once
• Mark as read / Mark as unread
• Star
• Delete

A filter can carry several actions, and switching a filter to a different account swaps its folder dropdowns to that account's tree — a folder target the new account does not have is dropped rather than silently retargeted.

When they run

• Automatically, as the background sync finds new mail. This is the main path.
• On Inbox open, if Run filters when opening Inbox is on (Settings → General).
• On demand — Run filters in the user menu.

A filter that fails — an unreachable server, a folder that no longer exists — is recorded in Settings → Log with the reason, rather than failing silently.

Mail that arrived while Hmelj was off

It gets filtered anyway. Hmelj remembers, per folder, how far its filters have got, and on the first check after a restart it works through everything that arrived since — however long the gap was, up to 30 days, saying so in Settings → Log if it ever has to stop at that ceiling.

Nothing is filed twice. Each message is recorded against each filter that acted on it, so an overlapping catch-up run recognises what it has already done — a filter that forwards a message does not forward it again, and an auto-reply is not sent a second time.

Contacts

An address book that mostly maintains itself

Settings → Contacts, or Contacts in the user menu. Contacts feed the composer's recipient autocomplete.

Learned automatically

Two opt-out behaviours, deliberately asymmetric:

• People you send to are added. Only the ones you typed — a reply's prefilled recipients ride along and are subtracted, so replying to a mailing list does not swallow the whole list into your address book.
• Incoming mail only ever fills in a missing name. It never adds anyone. Receiving mail is not consent to be in someone's address book.

Both can be turned off in Settings → Contacts. A contact can also be deleted straight from the composer's autocomplete list.

Groups

A group is a name for a set of addresses — Družina, the board, the team. Type that name into To, Cc or Bcc, pick it from the suggestions, and the field holds one short token instead of eight addresses:

To:  👥 Družina, 

Hmelj puts the people in when the message is actually sent. The addresses appear in the message that goes out and in the copy saved to Sent, exactly as if you had typed them — everyone still sees who else got it, so a group is a shortcut for you, not a way to hide the recipient list. Put the group in Bcc if that is what you want.

Making one

Settings → Contacts, in the Groups card at the top:

• + New group, then give it a name. The name is what you will type, so it has to be unique — Hmelj adds a number if you reuse one rather than leaving two groups answering to the same word.
• Click the N people button to open a group and search the address book for people to put in it. You can also type an address that is not a contact at all.
• Or go the other way: tick contacts in the list below and use Add to group.
• ✉ starts a message to a group. ✕ removes the group — never the contacts in it.

Groups are saved with the rest of the tab, by Save. A group you have just made cannot be written to until then: the token is resolved by the server, and it has not been told about the group yet.

Things worth knowing

• A group holds addresses, not contacts. Renaming or re-syncing a contact does not disturb any group they are in, and a group can mix people from your own address book with people from a synced one.
• Sending to a group that no longer exists is refused, by name, rather than quietly going to fewer people than you meant. So is sending to an empty one.
• A draft is never refused. Drafts save on their own whenever a composer closes, so an unresolvable name is simply left in the field for you to fix.
• A scheduled or held-back message keeps the membership the group had when you pressed Send. Editing the group afterwards does not change who that message goes to.
• Groups are yours, like filters and saved searches — two people sharing a mailbox do not share them — and they are included in the settings export.

Importing

• Google CSV / vCard — a .csv, .vcf or .txt export
• Import from Microsoft — pulls the contacts of a Microsoft account you have attached (needs the Contacts.Read permission)
• Import from Exchange — the same, for an EWS account

Hmelj also suggests people you correspond with who are not contacts yet, with how many messages you have exchanged, so you can add them in a batch.

Calendar

Your calendars, in one place — and shared back out again

Hmelj shows calendars from CalDAV servers, Google, Microsoft 365 and Exchange, all together, in month, week, day and agenda views. It can create and change events on the ones that allow it, remind you before an event starts, and publish calendars of its own for a phone or another app to subscribe to.

Adding a calendar

Settings → Calendars → + , then pick where it comes from.

Making a new calendar

Settings → Calendars → New calendar, on the source you want it in. It is created on that provider's own server, so it turns up in their apps too — a calendar made in a Gmail source is a real Google calendar, on your phone as well.

Everywhere except Exchange. Exchange can do it, but Hmelj has no folder-management code for EWS yet, so the button is not offered there.

If you rename a calendar on the server

Syncing a calendar reads its events, not its name — so a calendar renamed in Google Calendar, Outlook or any other client keeps its old name in Hmelj until the calendar list itself is re-read. That happens on Sync now (Settings → Calendars) straight away, and by itself about once an hour otherwise. The same goes for a calendar's colour and for a calendar that has become read-only. It works the same way for every kind of calendar — CalDAV, Google, Microsoft 365 and Exchange.

A calendar you have given a colour of your own keeps it — the server's colour does not overwrite your choice. Calendars that are new on the server still need the source's Edit → discover step, deliberately: a work server routinely shares a dozen nobody asked for.

Colours

Every calendar has one, and every event takes its calendar's — until you give the event a colour of its own, which then wins. That is what lets one Bins calendar carry paper in blue, plastic in yellow and everything else in brown, instead of needing three calendars to say the same thing.

• A calendar's colour — the little square beside it in Settings → Calendars. Your choice sticks: it is not overwritten the next time the calendar list is re-read from the server. Double-click the square to hand it back to the server's own colour.
• An event's colour — the swatch strip in the event form. Set it once on a repeating event and every occurrence follows. The first swatch (✕) means "same as the calendar".

Turning calendar sync on for a Google or Microsoft account asks you to sign in once more. That is not a bug: the sign-in you already have covers mail, and reading a calendar needs permission you have not granted yet. Only the account you switch it on for is affected.

The views

Month, Week, Day and Agenda, with ‹  Today › to move. On a keyboard, ← and → page, t jumps to today, and m w d a switch views. On a phone, swipe left and right.

A phone gets two deliberate differences. Agenda is what opens by default, and the month grid shows a coloured dot per event rather than a title — seven columns at 380 pixels leaves about 45 each, which is not enough to read. Tap a day to open it. Week shows three days at a time rather than seven.

Each calendar in the sidebar can be switched off to hide it without unsubscribing. Settings → Calendars is where you choose which ones are synced at all.

Time zones. An event that carries one is shown at the moment that zone names, whoever is looking. An all-day event is on the same date everywhere. Anything written with no zone at all follows yours, which you can set in Settings → Calendars → Time zone (empty means "follow this device").

Creating and editing

＋ in the calendar toolbar, or Add to calendar in a message's ⋯ menu, which fills in the subject and offers everyone the message was addressed to as attendees.

Anyone you list as an attendee is emailed an invitation when you save — unless the calendar is on Google, Microsoft or Exchange, which send their own. Hmelj deliberately does not send a second one; two invitations from two addresses is how replies end up going to the wrong place.

Repeats

The Repeats dropdown has the usual ones — daily, weekly, fortnightly, monthly, yearly — plus two worth knowing about:

• The last day of the month lands on the 28th, 30th or 31st as that month requires. Not the same as "every month on the 30th", which silently skips February.
• Custom… reveals Every [n] [days / weeks / months / years], for any interval at all. Two events four days apart, each repeating every four days, is how you get one thing on Monday-Friday-Tuesday and another on Wednesday-Sunday-Thursday.

An event whose rule says more than these controls can — a rule written by another client, with several weekdays or an end date — is left alone: the dropdown offers Keep the existing repeat rule rather than quietly simplifying it on the next save.

Which repeats each kind of calendar can hold

Hmelj, CalDAV and Google store the repeat rule exactly as written and work the dates out locally, so they hold anything the iCalendar standard allows — including rules Hmelj's own dropdown cannot express, which is why "Keep the existing repeat rule" exists.

Microsoft 365 and Exchange do not store a rule. They store one of six named patterns, and Hmelj translates. Most things map exactly; a few have no pattern at all and are refused rather than approximated — saving a near-miss would produce an event that is wrong on almost every occurrence and looks like it saved fine.

A refusal names what it could not express and leaves the event unsaved, so nothing is lost. If you need one of those, keep the event on a Hmelj, CalDAV or Google calendar.

One more difference worth knowing: Microsoft and Exchange also only know their calendars over a rolling window of dates (see the environment settings), while the other three know a repeating event for all time — so scrolling to 2031 works on a Google calendar and may show nothing on an Exchange one.

If somebody else changes an event while you have it open, saving gives you a conflict rather than quietly overwriting them. Reopen the event to see their version.

Reminders

Set per calendar in Settings → Calendars, and per event in the event form. An event that carries its own reminder always wins over the calendar's default — if you set 45 minutes on one meeting, that is what you get.

Reminders arrive through the same notification channel as new mail, so they work with Hmelj closed as long as notifications are set up (Notifications). They do not follow your mail quiet hours by default: a 07:00 meeting reminder is usually wanted even when mail is silent until 08:00. There is a per-calendar switch if you disagree.

A reminder that came due while the server was off is not delivered late. Starting Hmelj in the morning does not replay the night.

Sharing from Hmelj

Hmelj can act as a CalDAV and CardDAV server, so a phone, Thunderbird or Apple Calendar can subscribe to a calendar or address book it holds. Two steps.

"Busy only" is the useful one for sharing with somebody else. A source set to busy contributes the time and nothing else — the title becomes "Busy", and the place, the notes and the attendees are gone. A household calendar can then show that Thursday afternoon is taken without showing what for.

A merged collection is always read-only. There is no honest answer to which of its calendars a change would belong to, so it refuses rather than guessing. A single Hmelj calendar published on its own is read-write: events added on your phone appear in Hmelj straight away.

Anything published from another server — a mirror of your work calendar, say — is read-only too. Change it where it lives.

Mailbox Analytics

Where the quota went, and what is safe to delete

Mailbox analytics in the user menu. It answers questions the ordinary message list cannot: how many messages there really are, who sends the most of them, and which ones are eating the space.

It needs its own index, so it starts with an explicit Scan you press. The ordinary message cache deliberately holds only each folder's newest few hundred messages; a 35,000-message inbox has a couple of hundred rows in it. The analytics scan builds a second, complete-but-thin index — sender, subject, date, size, two flags, and no bodies at all. It runs in the background, shows progress, and can be stopped.

Notifications

New mail on your desktop and phone, on your schedule

Turn them on per device in Settings → General → Notifications. Where the browser supports it, they arrive even with Hmelj fully closed, with the sender and subject. On Android and desktop the notification itself carries Mark as read and Delete; tapping it opens straight to the message.

Send test notification pushes to every device you have enabled, not just the one you are on — so you can trigger it from a laptop while watching your phone, without waiting for real mail.

Web Push (VAPID)

Real browsers and installed PWAs use Web Push. The server needs a VAPID key pair; until it has one, notifications stay off. Generate a pair once:

npm run vapid-keys

…then put both halves in the environment:

VAPID_PUBLIC_KEY=…
VAPID_PRIVATE_KEY=…
VAPID_SUBJECT=mailto:you@example.com

VAPID_SUBJECT must be a mailto: or https: address identifying you; some push services use it to reach you if your server misbehaves, and reject requests without one.

Devices

Settings → General lists every device currently registered for this Hmelj account, with what it is. Enabling notifications on one device does not register any other, so a phone you no longer use can be removed here without needing to sign in from it.

Android app devices are listed too — they go through Firebase instead of Web Push, since Android's WebView has no Push API at all. See Android App.

Quiet hours & the scheduler

Settings → Scheduler, per account. An account-wide schedule applies to all its folders, and any folder can override it.

• Always — notify whenever mail arrives
• Never — mail still syncs, you are simply not told
• Scheduled — a time window and the weekdays it applies to
• Skip public holidays — see below

Per-folder rows show whether they Inherit the account setting or carry their own, and an override can be cleared to go back to inheriting.

Muting a folder

Right-click or long-press a folder in the sidebar → Mute: for a set period, until tomorrow morning, or until a time you pick. A muted folder shows a 🔕 marker, and the mute can be lifted from the sidebar or from the Scheduler tab — which is also where a mysteriously quiet folder gets explained.

Settings Reference

Every tab, every option

Settings are per Hmelj user. A few — marked this device below — are stored in the browser instead, because they describe the screen you are looking at rather than the account.

General

The theme is not here — it lives in the user menu's Theme picker, which previews each theme live and applies it the moment you pick one, and can also set custom background and foreground colours.

Reading

Compose

Identities

See Identities & Signatures.

Filters

See Filters.

Subject

Rules that shorten long subjects in the message list and in notifications. Machine-generated mail often buries the useful half behind a fixed prefix, so every row on a phone reads identically; a rule strips the prefix, and the next one can shorten a word inside what is left. Rules run top to bottom, each on the previous one's output, matching plain text or a regular expression with $1, $2 for what it captured.

Nothing is changed on the mail server. Search still matches what the sender actually wrote, opening the message shows the real subject, and a reply goes out quoting the real one. A Test a subject box at the bottom shows what any subject would come out as, using the rules exactly as edited — saved or not.

Saved searches

Rename, reorder and delete them — see Saved searches, which also covers the unread count each one carries in the sidebar.

Templates

Reusable snippets, inserted while writing with the 📋 toolbar button — see Templates.

Folders

See Folders.

Scheduler

See Quiet hours & the scheduler.

Contacts

See Contacts. This tab carries the address book itself, the two learn-as-you-go switches, synced address books, and groups.

Calendars

See Calendar — which calendars are synced, their colours, the time zone, and sharing them back out of Hmelj.

Accounts

See Accounts. This tab also carries Share, the entry into the Folders tab for a given account, and each account's Search inside messages switch with its live index size.

Login

Your Hmelj credentials — not any mailbox's. Change password asks for the current one. Change username signs you out on every device, since the login name is what sessions are tied to; changing only the capitalisation of your own name is a display change and does not. App passwords live here too — one per device, for subscribing a phone or another app to Hmelj's CalDAV/CardDAV server.

Log

Problems with your accounts, in plain language: filters that failed, mail that could not be sent, servers that could not be reached. Filter by Errors / Warnings / Info, expand an entry for the detail, and clear the whole log when you have dealt with it. Debug noise, per-poll timings and internal state stay in the server's own log and never appear here.

Admin

The tab only administrators see

The first user to sign up is an admin. The Admin tab is hidden entirely for everyone else.

Users

Every Hmelj login account, with its admin and disabled state. Each can be disabled (kept, but unable to sign in) or removed.

Sign-up

Allow new users to sign up — the runtime equivalent of ALLOW_SIGNUP. Turn it off once everyone who needs an account has one.

OAuth providers

Registers the client IDs that let users add a mailbox by signing in with the provider instead of storing a password — required for Outlook.com and Microsoft 365, and the alternative to an app password for Gmail.

Each provider card shows the exact redirect URI to register — click it to select it — and a line saying precisely how that provider expects the app to be registered, because the two disagree:

• Microsoft — a public client (Mobile and desktop applications platform), client ID only, no secret. Tenant defaults to common.
• Google — a Web application client, which is confidential and needs its secret as well.

The stored secret is never sent back to the browser: the field shows only whether one exists, and blank means "keep the one you have" — the same rule as every password field in Hmelj. Setting the matching environment variables instead makes the card read-only and say so.

Full walkthroughs: Google · Microsoft.

Account presets

Named server configurations that prefill the account wizard — IMAP and SMTP host, port and TLS, plus optional help text and a help link shown to the user. Instance-wide, so adding one for your own mail provider saves every user on the server from typing it.

Custom fonts

Upload .ttf, .otf, .woff or .woff2 files and they appear in every user's App font and Message font pickers. Select several at once — the family name and style (Regular / Bold / Italic / Bold Italic) are detected from each filename, so Bookerly-Regular.ttf and Bookerly-BoldItalic.ttf land in the right slots by themselves.

Exporting Your Data

Both halves, in the format that can actually be read back

Settings → General → Export your data. It comes out in two shapes, because one shape cannot do both jobs.

Export settings

One zip, small, containing:

• your settings, identities and signatures
• filters, subject rules, saved searches and templates
• contacts — as JSON and as vCard, so any address book can import them
• contact groups
• calendars that live in Hmelj, as .ics

Everything is the same JSON Hmelj stores on the server, so restoring is copying a file back into DATA_DIR/users/<your user>/ with the server stopped. A README.txt inside the zip says so, and says what is missing.

Export mail

One folder at a time, as an mbox file — the format Thunderbird, Apple Mail and every migration tool import. Pick the account, the folder, and optionally "only messages since…".

The file streams as it is read, a message at a time, so a folder of any size uses the same small amount of memory and there is no size ceiling. A big folder takes a while and the download appears when the whole thing has been read — the toast says as much when it starts.

Messages are exported exactly as they arrived, headers and all, so signatures still verify and nothing has been re-encoded on the way out.

Environment Variables

Everything Hmelj reads from the environment

All of these are optional — every one has a working default. In Docker they go in the .env file named by env_file:, or straight into environment:. The repository's .env.example is the same list with the reasoning attached.

Core

Sync and caching

Notifications

OAuth clients

The environment alternative to Settings → Admin → OAuth providers. Set here, these win, and the Admin fields become read-only.

Languages

English and Slovenščina

The interface language is per user, in Settings → General. The login page has its own selector, since you have not signed in yet.

Translation is keyed on the English source string and applied by a MutationObserver, so static HTML and dynamically rendered content translate alike and no template needs marking up. Message content is never translated — the reading pane, editors and input fields are excluded.

Adding a language

Copy public/i18n/sl.json to your language code, translate the values (the keys are the English source strings and must stay exactly as they are), and add the code to the language list in public/js/i18n.js. Nothing else needs touching.

The Android shell has its own strings, already translated into English, Slovenian, German, Spanish, French, Italian and Portuguese — but those only cover the native chrome: the server-URL screen and the notification action buttons. Everything else a user sees is the web app.

Security & Privacy

What is stored, where, and who can see it

Credentials

• Hmelj passwords are scrypt-hashed in auth.json and never stored in a recoverable form.
• Mailbox passwords and OAuth refresh tokens are encrypted at rest with AES-256-GCM, using HMELJ_SECRET or the auto-generated secret.key (mode 600).
• Google's OAuth client secret is encrypted with the same key and is never sent back to the browser.
• Sessions are httpOnly cookies backed by in-memory state — a restart signs everyone out. Login attempts are rate-limited per IP.

Message rendering

• HTML is sanitised server-side, then rendered in a sandboxed iframe with no same-origin access. Scripts never run.
• @import, expression() and behavior are always stripped.
• CSS url(...) loads obey the same external-image policy as <img>, so a tracker cannot hide in a background.
• Read receipts are never confirmed automatically.

The network

Hmelj connects out to the mail servers you configure, to the push services your browsers and devices use (Mozilla's autopush, Google's FCM, Apple's relay), and to Google or Microsoft when someone signs in with OAuth. Nothing else. There is no telemetry, no analytics, no ads, and no Hmelj-operated service of any kind — the project's authors never receive, see or store any of your data.

The full statement, in the form Google Play asks for, is on the Privacy Policy page.

Install as an App (PWA)

Hmelj in its own window, on any platform

Hmelj is a Progressive Web App. Installing it gives you a window with no browser chrome, a launcher icon, and a "Compose" shortcut on the icon's context menu.

The service worker is network-first for the app shell, so you always get the current version and a local edit shows up on refresh. It deliberately does not cache /api/*: mail is cached, but by the app itself rather than by the service worker — see Working Offline, which explains why.

Working Offline

Reading and answering mail with no server

Hmelj keeps a copy of your newest mail on each device, so it opens and works with no connection at all — on a plane, on the underground, or simply when the server is down. It is on by default and needs no setup.

What you can read

While you are online and the app is idle, Hmelj quietly downloads the newest 300 messages of each account (adjustable), including the images inside them. So offline you can open mail you had never opened before, not only what you happened to read earlier. If you read mail in a custom font, that font file is saved too, so a message offline is set the way it is online rather than dropping to a fallback face. Your folder list, contacts, identities, settings and the calendar weeks you have looked at are saved with it, which is what lets the app start at all with the server unreachable.

A message whose body was not saved — older than the limit, or dropped to stay under the storage cap — says so plainly when you open it, and opens normally once you are back.

Searching offline

The search box keeps working; it searches what is saved on the device rather than asking the server, and the results say so. from:, to:, subject:, is:unread, is:starred and has:attachment all work, as do plain words, which also match the text of any message whose body is saved.

The Outbox

Anything you do offline is queued rather than refused: marking read or unread, starring, deleting, moving, archiving, marking spam, saving a draft and sending. The list updates immediately, an Outbox row appears in the sidebar with a count, and the queue survives closing the app. When the connection returns it is sent in the order you did it.

Right-click (or long-press) anything in the Outbox to retry it, edit it — a queued message reopens in the composer — or discard it.

Storage, and what it costs

Settings › Offline is per device — a phone and a desktop sharing one Hmelj account keep their own answers. It sets whether to keep mail offline at all, how many messages per account, whether to include attachments (off by default; inline images are kept either way), and a storage ceiling (250 MB by default). When the ceiling is reached the oldest messages are dropped first. The same panel shows what is stored right now and can delete all of it.

On Android

The native app works offline too. Because it usually points at a plain-http LAN address — which browsers do not treat as a secure context, so there is no service worker there — it loads the app from the WebView's own cache when there is no network, instead of the "no connection" screen. That screen still appears if the app has never been loaded on that device.

Android App

A native shell around the same web app

The Android app is a full-screen WebView pointed at your Hmelj server. It contains no mail code. On first launch it asks for the server URL and remembers it; press back twice on the main screen to change it.

Installing it

Download the APK from GitHub Releases and install it. Android will ask you to allow installing from that source; that is the normal sideloading prompt, not a warning about the app.

Each release carries a release APK (what you want) and a debug APK (larger, unoptimised, for diagnosing a problem). Both are signed, so an update installs over the previous version.

Google Play distribution is planned but not live yet.

Why it exists

Android's WebView implements no Web Notification or Push API at all — on every Android version, in every WebView build. It is a platform gap, not a permission you can grant. So a Hmelj PWA on Android cannot receive push while it is closed, and the native shell exists to fill exactly that hole, using Firebase Cloud Messaging.

What the shell adds over the PWA:

• Push while fully closed, with Mark as read and Delete buttons on the notification
• An unread badge on the launcher icon
• OAuth sign-in in a real browser tab — Google rejects OAuth started inside a WebView outright
• Attachment hand-off to whichever installed app can open the file
• Keep the screen on, and correct padding for notches and gesture bars
• Battery-optimisation exemption prompt, so background delivery is not killed by Doze

Firebase setup

Android push needs a Firebase project. Two pieces, on two sides:

1. In the app — google-services.json

2. On the server — the service-account key

The startup log says which it found, or that it found none and Android push is therefore off — everything else is unaffected either way.

Building & Releasing

Docker images, signing keys, and cutting a release

Everything here is automated by GitHub Actions in the repository. This section is for whoever maintains it — or for anyone building their own fork.

Docker images

.github/workflows/docker.yml runs the test suite, then builds a multi-arch image (linux/amd64 and linux/arm64) with QEMU and Buildx and pushes it to GitHub Container Registry.

Building locally instead is one command — but note that an emulated arm64 leg compiles better-sqlite3 from source under QEMU and is slow:

docker buildx build --platform linux/amd64,linux/arm64 -t hmelj:local .

Android signing keys

Android will only install an update over an existing app if the new APK carries the same signing certificate. That makes the signing key a long-lived commitment, and it is why Hmelj keeps two of them apart:

Create the dev / sideload keystore — do this once, and keep the file somewhere you will still have it in five years:

keytool -genkeypair \
  -keystore dev-release.jks \
  -alias hmelj-release \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -dname "CN=Your Name, OU=Hmelj, O=Hmelj, L=City, ST=State, C=SI"

Create the Play upload keystore — only when you are ready to publish:

keytool -genkeypair \
  -keystore play-upload.jks \
  -alias hmelj-upload \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -dname "CN=Your Name, OU=Hmelj, O=Hmelj, L=City, ST=State, C=SI"

keytool prompts for a store password and a key password. They may be the same. Write both down.

GitHub secrets

Repository → Settings → Secrets and variables → Actions → New repository secret. Keystores and the Firebase config are binary or multi-line, so they go in base64-encoded:

base64 -w0 dev-release.jks                  # Linux
base64 -i dev-release.jks                  # macOS
certutil -encode dev-release.jks out.txt   # Windows

Paste the whole result, newlines and all. The workflows strip line breaks and the -----BEGIN/END----- wrappers certutil adds, so output from any of the three works as-is.

Building in Android Studio

Requires JDK 17 and the Android SDK with API 35. Open the Android/ directory as the project.

To produce an APK that installs over a CI-built one, sign it with the same key. Create Android/keystore.properties — it is git-ignored — next to build.gradle:

storeFile=keystore/dev-release.jks
storePassword=your-store-password
keyAlias=hmelj-release
keyPassword=your-key-password

storeFile is resolved relative to the Android/ directory, so putting the .jks in Android/keystore/ (also git-ignored) works as written. Then:

gradlew.bat assembleDebug      :: app\build\outputs\apk\debug\
gradlew.bat assembleRelease    :: app\build\outputs\apk\release\
gradlew.bat bundleRelease      :: app\build\outputs\bundle\release\  (Google Play)

…or Build → Generate Signed App Bundle / APK in the IDE. Drop google-services.json into Android/app/ first if you want push in your local build.

Cutting a release

git tag -a v1.0.0 -m "Hmelj 1.0.0"
git push origin v1.0.0

That one push starts both release workflows:

• Docker — pushes :latest, :1.0.0 and :1.0.
• Android — builds the debug and release APKs and attaches them to the GitHub Release, and builds the AAB as a run GitHub Actions artifact. The AAB is deliberately not attached to the public Release: download it from the run and upload it to Play Console yourself, to the Internal testing track first.

Publishing these docs

Repository → Settings → Pages → Source: Deploy from a branch, branch main, folder /docs. The site is plain static files with no build step, so it goes live within a minute or two at https://<user>.github.io/hmelj/.

Screenshots live in docs/screenshots/. They ship as blank placeholders so nothing 404s; replace them one at a time with real captures. docs/screenshots/README.md lists what each one should show, and node scripts/gen-placeholder.mjs regenerates any that go missing.

Troubleshooting

The failures that actually happen

Look here first

Settings → Log records the problems that concern your accounts in plain language — a filter that failed, mail that could not be sent, a server that could not be reached. Most questions are answered there before the server log is worth opening.

For the server side, docker compose logs -f hmelj, and LOG=debug when you need every IMAP round trip and HTTP request.

Starting the cache over

The message cache is disposable. If it has drifted from the server, stop Hmelj, delete cache.sqlite and its -wal / -shm sidecars, and start again — it rebuilds on the next sync. Nothing else in DATA_DIR is safe to delete this way.

To rule the cache out of a problem entirely, run with CACHE_ENABLED=false: no background polling and no local cache, with everything fetched live.