mbrts/README.md

# 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 too 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.

## 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
```