Themes

Mailbox ships four built-in themes and treats everything beyond them as a small text file you can write, generate, import, browse for, or share. This page is the reference, and the honest words about community themes.

The two rules

A built-in theme is always a full return to stock. User themes are separate files layered over a built-in; applying a theme rebuilds every colour from scratch; picking a theme in Options gives you exactly that theme with no leftover edits riding along. If switching back ever looks different from a fresh install, that is a bug — report it.

Content stays readable. The surfaces you read mail on are never recoloured by anything automated. A contrast check runs on every user theme as it is applied, and anything hard to read is named in the log.

What you can do

• Mailbox Background — a shipped pattern or your own image behind the title bar's controls, dragged into alignment by hand.
• Palettes — a theme built from a curated colour scheme (vendored from the tinted-theming project, MIT, each with its author), your desktop's own colours, or a scheme sampled off your background image.
• The editor — every token the theme is made of, applied live; point at a part of the window and the editor scopes to what paints it.
• Import — a Firefox static theme (.xpi), read for exactly what a mail client can use: the caption strip, the left panes, the header image. Nothing else is guessed at.
• The theme browser — search addons.mozilla.org's community themes from inside the application and preview each one as Mailbox would wear it before installing.
• Sharing — a theme is one json file; a theme with images travels as a zip pack.

Community themes, plainly

Themes on addons.mozilla.org are made and uploaded by their authors — not by Mailbox, and not by Mozilla in most cases. Before installing one, Mailbox tells you this and names the theme's licence, and it is worth taking seriously:

• A Firefox static theme contains colours and images only — no code runs. Mailbox additionally re-encodes every image through its own decoder before anything touches disk — animated themes included, frame by frame, and they keep their animation — refuses archives that are oversized or try to escape their folder, and maps only a small, fixed set of colours. That limits what a hostile file can do, but no download from the internet is ever entirely without risk — install only themes you trust, exactly as you would any other file you download.
• Licences vary: many themes are Creative Commons, some reserve all rights. Installing a theme for your own use on your own machine is ordinary use of a file you lawfully obtained; Mailbox never redistributes it anywhere.
• Network: the browser talks to addons.mozilla.org only while you have it open. Nothing else in Mailbox's theming — importing, applying, palettes, backgrounds — touches any network at all.

Where theme files live

~/.config/mailbox/themes — one .mailbox-theme.json per theme, images under images/<id>/. The directory is watched: dropping a file in applies it live. Removing a theme from Options deletes its file and images; deleting the file by hand works too.