mbrts

Real-time mail delivery for maildirs via Fastmail's JMAP push API.

Connects to Fastmail's JMAP EventSource stream and delivers new messages directly to a local Maildir the moment they arrive without polling.

How it works

On first run, or when the saved JMAP state is stale, mbrts falls back to mbsync for a full sync, then takes over from that point.

Setup

Create a Fastmail API token at Settings → Security → API Tokens.

Config file

By default mbrts reads $XDG_CONFIG_HOME/mbrts/config.yaml (e.g. ~/.config/mbrts/config.yaml):

accounts:
  - name: Personal
    maildir_path: /home/you/.mail/Personal
    password_command: "pass show fastmail/api-token"

Each account requires exactly one token source:

Field	Description
`password_command`	Shell command that prints the token to stdout
`token_file`	Path to a file containing the token
`token_env`	Name of an environment variable containing the token

Optional fields: mbsync_account (mbsync channel/group name; defaults to name), log_level (top-level: debug, info, warn, error).

CLI flags

Every config file option has an equivalent flag. Flags override the config file. A single account can be configured entirely on the command line without a config file:

mbrts --name Personal \
      --maildir-path ~/.mail/Personal \
      --password-command "pass show fastmail/api-token"

Run mbrts --help for the full flag list, or mbrts --version to print the version.

Nix

Add mbrts as a flake input:

inputs.mbrts = {
  url = "git+https://code.adriano.fyi/me/mbrts";
  inputs.nixpkgs.follows = "nixpkgs";
};

The flake exposes:

Output	Description
`packages.*.default`	The `mbrts` binary
`overlays.default`	Adds `pkgs.mbrts`
`homeManagerModules.default`	The `services.mbrts` home-manager module

home-manager module

Add the overlay and module to your home-manager configuration, then configure the service:

# in your flake outputs
overlays = [ inputs.mbrts.overlays.default ];

# in your home-manager module list
inputs.mbrts.homeManagerModules.default

# in your home-manager config
services.mbrts = {
  enable = true;
  accounts = [
    {
      name = "Personal";
      maildirPath = "/home/you/.mail/Personal";
      passwordCommand = "pass show fastmail/api-token";
    }
  ];
};

The module generates a config file and runs mbrts as a systemd user service. Logs are available via journalctl --user -u mbrts -f.

Module options:

Option	Type	Default	Description
`enable`	bool	—	Enable the service
`package`	package	`pkgs.mbrts`	Package to use
`logLevel`	enum	`"info"`	`debug`, `info`, `warn`, or `error`
`accounts`	list	`[]`	List of account submodules (see config file fields above)

Build

CGO_ENABLED=0 go build -o mbrts .

aerc

Configure the account source as maildir:// so aerc picks up delivered messages immediately via inotify:

source = maildir:///home/you/.mail/Personal

3 KiB Raw Blame History