# v2.0.0 Config Schema Reference

The v2 config is **per-backend tables** under each account. There is no more
generic `backend.*` / `message.send.backend.*` block. IMAP, SMTP, JMAP, Gmail
REST, Microsoft Graph, and Maildir each get their own dotted-key section under
`[accounts.NAME]`.

## Layout

```toml
[accounts.<name>]
default = true                # one account may be flagged default
email = "user@example.com"
display-name = "Your Name"

imap.server = "imaps://..."   # IMAP backend
imap.sasl.plain.username = "..."
imap.sasl.plain.password.raw = "..."

smtp.server = "smtps://..."   # SMTP backend
smtp.sasl.plain.username = "..."
smtp.sasl.plain.password.raw = "..."

mailbox.alias.inbox = "INBOX" # folder aliases (top-level or under account)
mailbox.alias.sent = "Sent"
mailbox.alias.drafts = "Drafts"
mailbox.alias.trash = "Trash"
```

## Server URLs

`server` accepts either a bare authority (`host[:port]`, defaulting to the
implicit-TLS scheme) or a full URL with `imap://`, `imaps://`, `smtp://`,
`smtps://`, `jmap://`. Quick picks:

| Backend | Implicit TLS | STARTTLS     |
|---------|--------------|--------------|
| IMAP    | `imaps://host:993` | `imap://host:143` |
| SMTP    | `smtps://host:465` | `smtp://host:587` |

## SASL mechanisms

Pick exactly one under `imap.sasl.*` or `smtp.sasl.*`:

- `anonymous` — `imap.sasl.anonymous.message = "himalaya"` (no auth)
- `login` — `imap.sasl.login.username` / `.password.raw`
- `plain` — `imap.sasl.plain.username` / `.password.raw` (most common)
- `oauthbearer` — OAuth 2.0 bearer token
- `xoauth2` — Google's pre-standard OAuth 2.0
- `scram-sha-256` — challenge-response

For each, the password may be set two ways:

```toml
# Inline (testing only)
imap.sasl.plain.password.raw = "your-password"

# External command (recommended for stored secrets)
imap.sasl.plain.password.command = "pass show email/imap"
```

## Folder aliases — detailed

The `mailbox.alias.X` keys map himalaya's canonical names to the server's
actual mailbox IDs. Aliases are case-insensitive on lookup and on storage.

| Canonical  | Typical real-world names                          |
|------------|---------------------------------------------------|
| `inbox`    | `INBOX` (always)                                  |
| `sent`     | `Sent`, `Sent Items`, `[Gmail]/Sent Mail`         |
| `drafts`   | `Drafts`, `[Gmail]/Drafts`                        |
| `trash`    | `Trash`, `[Gmail]/Trash`, `Deleted`               |

`inbox` is the implicit default mailbox when `-m/--mailbox` is not passed.

If the server uses no special-use role for sent messages (most IMAP servers
don't announce it), `mailbox.alias.sent` is **required** — otherwise
`himalaya template send` will succeed SMTP but fail to save to Sent, exit
non-zero, and any retrying caller will produce duplicate emails.

## Multiple accounts

```toml
[accounts.personal]
default = true
email = "me@example.com"
imap.server = "..."

[accounts.work]
email = "me@work.example.com"
imap.server = "..."
```

Switch with `--account`:

```bash
himalaya --account work envelope list
```

## Output formats

Most commands support `--output`:

```bash
himalaya envelope list --output json     # structured for scripts
himalaya envelope list --output plain    # plain text
```

`--output json` is the safe path for parsers — the table layout (columns,
box-drawing chars) is not stable.

## Command name changes (v1 → v2)

| v1 command                  | v2 command                         |
|-----------------------------|------------------------------------|
| `himalaya folder list`      | `himalaya mailbox list`            |
| `himalaya account configure`| bare `himalaya` (writes to stdout) |
| `himalaya template reply`   | `himalaya template reply` (same)   |
| `himalaya template send`    | `himalaya template send` (same)    |
| `himalaya message write`    | `himalaya message write` (same)    |

The `template` subcommand family is intact. Sending via stdin is still the
recommended non-interactive path from Hermes.