114 lines
3 KiB
Markdown
114 lines
3 KiB
Markdown
# 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`):
|
|
|
|
```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:
|
|
|
|
```nix
|
|
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:
|
|
|
|
```nix
|
|
# 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:
|
|
|
|
```ini
|
|
source = maildir:///home/you/.mail/Personal
|
|
```
|