himalaya/config.sample.toml

# ================================================================================
# `himalaya` configuration file.
#
# Loaded from the first valid path among:
#   - $XDG_CONFIG_HOME/himalaya/config.toml
#   - $HOME/.config/himalaya/config.toml
#   - $HOME/.himalayarc
#
# Override with `himalaya -c <PATH>` or `HIMALAYA_CONFIG=<PATH>`. Multiple paths
# can be passed at once, separated by `:`; the first one is the base and the
# rest are deep-merged on top of it.
#
# Run `himalaya` once with no config file to launch the wizard, which discovers
# IMAP/SMTP/JMAP defaults via PACC, Thunderbird Autoconfiguration and RFC 6186
# SRV, then writes the result here. `himalaya account configure <name>` can be
# used afterwards to edit (or add) an account through the same wizard.
# ================================================================================

# --------------------------------------------------------------------------------
# Global config
# --------------------------------------------------------------------------------

# Default download directory for attachments. Falls back to `$TMPDIR`.
#downloads-dir = "~/downloads"

# https://docs.rs/comfy-table/latest/comfy_table/presets/index.html
#table.preset = "││──╞═╪╡┆    ┬┴┌┐└┘"

# https://docs.rs/comfy-table/latest/comfy_table/enum.ContentArrangement.html
#table.arrangement = "dynamic"
#table.arrangement = "dynamic-full-width"
#table.arrangement = "disabled"

# `chrono` strftime format used to render the DATE column of `envelopes list`.
# Defaults to `"%F %R%:z"`, e.g. `2026-05-06 14:30+02:00`.
#envelope.list.datetime-fmt = "%F %R%:z"

# Convert each envelope's `Date` header offset to the system's local timezone
# before formatting. Defaults to `false`, which preserves the wire offset.
#envelope.list.datetime-local-tz = false

# Default page size for `envelopes list`. The `-s/--page-size` CLI flag wins
# when passed; otherwise the merged account/global value wins; otherwise the
# hard fallback is 25.
#envelope.list.page-size = 50

# --------------------------------------------------------------------------------
# Table rendering — envelopes list
# --------------------------------------------------------------------------------

# Per-column foreground colors for the `envelopes list` table. Each value is
# a crossterm-style color: a named variant (`"red"`, `"dark-magenta"`,
# `"reset"`, …), or a `{ Rgb = { r, g, b } }` / `{ AnsiValue = N }` table.
# Applied to both shared `envelopes list` and the protocol-specific
# `imap`/`jmap`/`maildir` envelope listings so a single key affects every
# backend. The values below are the v1.2.0 defaults and are used when the
# key is left unset.
#envelope.list.table.id-color = "red"
#envelope.list.table.flags-color = "reset"
#envelope.list.table.att-color = "reset"
#envelope.list.table.subject-color = "green"
#envelope.list.table.from-color = "blue"
#envelope.list.table.to-color = "blue"
#envelope.list.table.date-color = "dark-yellow"
#envelope.list.table.size-color = "reset"

# Single-character glyphs used inside the FLAGS / ATT columns of the
# envelopes table. Defaults match v1.2.0.
#envelope.list.table.unseen-char = "*"      # FLAGS slot 1, when `\Seen` is absent
#envelope.list.table.replied-char = "R"     # FLAGS slot 2, when `\Answered` is set
#envelope.list.table.flagged-char = "!"     # FLAGS slot 3, when `\Flagged` is set
#envelope.list.table.attachment-char = "@"  # ATT column, when the message carries an attachment

# --------------------------------------------------------------------------------
# Table rendering — mailboxes list
# --------------------------------------------------------------------------------

# The `name-color` default matches v1.2.0 (`folder.list.table.name-color`);
# the other columns are new in v2 and default to the terminal foreground.
#mailbox.list.table.id-color = "reset"
#mailbox.list.table.name-color = "blue"
#mailbox.list.table.total-color = "reset"
#mailbox.list.table.unread-color = "reset"

# --------------------------------------------------------------------------------
# Table rendering — attachments list
# --------------------------------------------------------------------------------

# No v1 precedent; every column defaults to the terminal foreground.
#attachment.list.table.id-color = "reset"
#attachment.list.table.filename-color = "reset"
#attachment.list.table.type-color = "reset"
#attachment.list.table.size-color = "reset"
#attachment.list.table.inline-color = "reset"
#attachment.list.table.path-color = "reset"

# --------------------------------------------------------------------------------
# Table rendering — account list
# --------------------------------------------------------------------------------

# Defaults match v1.2.0.
#account.list.table.name-color = "green"
#account.list.table.backends-color = "blue"
#account.list.table.default-color = "reset"

# --------------------------------------------------------------------------------
# Mailbox aliases
# --------------------------------------------------------------------------------

# Map a friendly name to a backend-native mailbox id. Alias names are
# case-insensitive on lookup AND on storage, so `INBOX`, `Inbox` and `inbox`
# all hit the same entry. Ids are stored verbatim.
#
# The entry named `inbox` (case-insensitive) is the implicit default mailbox:
# shared commands fall back to this id when `-m/--mailbox` is not passed.
#
# Account-level entries override same-named global entries.
#[mailbox.alias]
#inbox = "INBOX"
#sent = "[Gmail]/Sent Mail"
#drafts = "[Gmail]/Drafts"
#trash = "[Gmail]/Trash"

# --------------------------------------------------------------------------------
# User-defined composers and readers
# --------------------------------------------------------------------------------

# Composers produce a MIME draft on stdout. They are invoked by the
# `messages compose-with` / `reply-with` / `forward-with` subcommands.
# Each entry declares one shell command per operation: `compose` (for blank
# drafts and `mailto`), `reply`, and `forward`. Stdin carries the source MIME
# bytes for `reply` / `forward` and is empty for `compose`; stderr is inherited
# so the composer can prompt the user.
#
# Pick one with `compose-with <name>`, or let himalaya use the entry flagged
# `default = true` when no name is passed.
#
# Example using https://github.com/pimalaya/mml:
#[message.composer.mml]
#compose = "mml compose"
#reply = "mml reply"
#forward = "mml forward"
#default = true

# Readers consume a MIME message on stdin and emit human-readable bytes on
# stdout. They are invoked by `messages read-with`.
#
#[message.reader.mml]
#command = "mml read"
#default = true

# --------------------------------------------------------------------------------
# Account config
# --------------------------------------------------------------------------------

# Declare one section per account. Pick one with `-a/--account <NAME>` or let
# himalaya use the entry flagged `default = true`.
[accounts.example]

# Use this account when `-a/--account` is not passed.
default = true

# Per-account overrides for the global options above.
#downloads-dir = "~/downloads/example"
#table.preset = "││──╞═╪╡┆    ┬┴┌┐└┘"
#table.arrangement = "dynamic"
#envelope.list.datetime-fmt = "%F %R%:z"
#envelope.list.datetime-local-tz = false

# --------------------------------------------------------------------------------
# IMAP config
# https://www.iana.org/go/rfc9051
# --------------------------------------------------------------------------------

# IMAP server. Either a bare authority (`host[:port]`, treated as
# `imaps://<authority>` by default), or a full URL with `imap://` (cleartext,
# optionally upgraded via STARTTLS) or `imaps://` (implicit TLS) scheme.
imap.server = "example.com"
#imap.server = "imap.example.com:143"
#imap.server = "imap://example.com:143"
#imap.server = "imaps://example.com:993"

# TLS provider, defaults to the first available at runtime.
#imap.tls.provider = "rustls"
#imap.tls.provider = "native-tls"

# Crypto provider for rustls, defaults to the first available at runtime.
#imap.tls.rustls.crypto = "ring"
#imap.tls.rustls.crypto = "aws"

# Custom TLS certificate (extra root, PEM-encoded).
#imap.tls.cert = "/path/to/custom/cert.pem"

# Enable STARTTLS (only valid when the server resolves to `imap://`).
#imap.starttls = false

# Pick exactly one SASL mechanism among `anonymous`, `login`, `plain`,
# `oauthbearer`, `xoauth2`, `scram-sha-256`. Omit the whole `imap.sasl` table
# to skip authentication entirely (no `AUTHENTICATE` command sent).

# SASL ANONYMOUS
# https://datatracker.ietf.org/doc/html/rfc4505
#imap.sasl.anonymous.message = "himalaya"

# SASL PLAIN
# https://datatracker.ietf.org/doc/html/rfc4616
imap.sasl.plain.authcid = "user@example.com"
imap.sasl.plain.passwd.raw = "***"
#imap.sasl.plain.passwd.command = "pass show example"
#imap.sasl.plain.passwd.command = ["mimosa", "password", "read", "example"]

# SASL LOGIN
# https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00
#imap.sasl.login.username = "user@example.com"
#imap.sasl.login.password.raw = "***"

# SASL OAUTHBEARER (host/port echoed in the GS2 header; usually mirror the
# server you actually connect to).
# https://datatracker.ietf.org/doc/html/rfc7628
#imap.sasl.oauthbearer.username = "user@example.com"
#imap.sasl.oauthbearer.host = "imap.example.com"
#imap.sasl.oauthbearer.port = 993
#imap.sasl.oauthbearer.token.raw = "***"
#imap.sasl.oauthbearer.token.command = ["ortie", "token", "read", "example"]

# SASL XOAUTH2 (Google's pre-standard OAuth 2.0 SASL).
# https://developers.google.com/gmail/imap/xoauth2-protocol
#imap.sasl.xoauth2.username = "user@example.com"
#imap.sasl.xoauth2.token.raw = "***"

# SASL SCRAM-SHA-256.
# https://datatracker.ietf.org/doc/html/rfc7677
#imap.sasl.scram-sha-256.username = "user@example.com"
#imap.sasl.scram-sha-256.password.raw = "***"

# RFC 2971 ID extension. Some providers (mail.qq.com, fastmail) require an `ID`
# exchange straight after authentication; set `auto = true` to opt in.
# https://www.rfc-editor.org/rfc/rfc2971.html
#imap.id.auto = false

# Per-field policy for the auto-ID command. Keys not listed here are NOT sent.
# `true` substitutes himalaya's canned value for the well-known keys (name,
# version, vendor, support-url); unknown keys with `true` fall back to NIL with
# a warning. `false` always sends NIL. An empty map sends `ID NIL`.
#imap.id.fields = { name = true, version = true, vendor = true, support-url = true }

# --------------------------------------------------------------------------------
# JMAP config
# https://www.iana.org/go/rfc8620
# https://www.iana.org/go/rfc8621
# --------------------------------------------------------------------------------

# JMAP server address. Either a bare authority (auto-discovered via
# `GET /.well-known/jmap`) or a full session URL.
#jmap.server = "fastmail.com"
#jmap.server = "https://api.fastmail.com/jmap/session"

# JMAP TLS provider (mirrors the imap.tls block above).
#jmap.tls.provider = "rustls"
#jmap.tls.rustls.crypto = "ring"
#jmap.tls.cert = "/path/to/custom/cert.pem"

# Pick exactly one of `header`, `bearer`, `basic`.

# Raw `Authorization` header value, used verbatim.
#jmap.auth.header.raw = "Bearer eyJhbGciOiJ..."
#jmap.auth.header.command = "pass show fastmail-token"

# OAuth 2.0 / API token bearer.
#jmap.auth.bearer.token.raw = "***"
#jmap.auth.bearer.token.command = ["mimosa", "password", "read", "fastmail-api"]

# HTTP Basic.
#jmap.auth.basic.username = "user@example.com"
#jmap.auth.basic.password.raw = "***"
#jmap.auth.basic.password.command = "pass show fastmail"

# Identity to send as. Required only for `messages send` over JMAP; can be
# discovered with `himalaya jmap identity get`.
#jmap.identity-id = "I0123abc"

# Drafts mailbox id used to stage outgoing messages before submission.
# Required only for `messages send` over JMAP; can be discovered with
# `himalaya jmap mailbox query --role drafts`.
#jmap.drafts-mailbox-id = "M0123abc"

# --------------------------------------------------------------------------------
# Maildir config
# --------------------------------------------------------------------------------

# Root directory containing one subdirectory per mailbox (Maildir++ layout).
#maildir.root = "~/Mail/example"

# --------------------------------------------------------------------------------
# SMTP config
# https://www.iana.org/go/rfc5321
# --------------------------------------------------------------------------------

# SMTP server. Either a bare authority (`host[:port]`, treated as
# `smtps://<authority>` by default), or a full URL with `smtp://` (cleartext,
# optionally upgraded via STARTTLS) or `smtps://` (implicit TLS) scheme.
smtp.server = "example.com"
#smtp.server = "smtp.example.com:587"
#smtp.server = "smtp://example.com:587"
#smtp.server = "smtps://example.com:465"

# TLS provider, defaults to the first available at runtime.
#smtp.tls.provider = "rustls"
#smtp.tls.provider = "native-tls"

# Crypto provider for rustls, defaults to the first available at runtime.
#smtp.tls.rustls.crypto = "ring"
#smtp.tls.rustls.crypto = "aws"

# Custom TLS certificate (extra root, PEM-encoded).
#smtp.tls.cert = "/path/to/custom/cert.pem"

# Enable STARTTLS (only valid when the server resolves to `smtp://`).
#smtp.starttls = false

# Pick exactly one SASL mechanism among `anonymous`, `login`, `plain`,
# `oauthbearer`, `xoauth2`, `scram-sha-256`. Omit the whole `smtp.sasl` table
# to skip authentication entirely.

# SASL ANONYMOUS
#smtp.sasl.anonymous.message = "himalaya"

# SASL PLAIN
smtp.sasl.plain.authcid = "user@example.com"
smtp.sasl.plain.passwd.raw = "***"
#smtp.sasl.plain.passwd.command = "pass show example"
#smtp.sasl.plain.passwd.command = ["mimosa", "password", "read", "example"]

# SASL LOGIN
#smtp.sasl.login.username = "user@example.com"
#smtp.sasl.login.password.raw = "***"

# SASL OAUTHBEARER
#smtp.sasl.oauthbearer.username = "user@example.com"
#smtp.sasl.oauthbearer.host = "smtp.example.com"
#smtp.sasl.oauthbearer.port = 465
#smtp.sasl.oauthbearer.token.raw = "***"

# SASL XOAUTH2
#smtp.sasl.xoauth2.username = "user@example.com"
#smtp.sasl.xoauth2.token.raw = "***"

# SASL SCRAM-SHA-256
#smtp.sasl.scram-sha-256.username = "user@example.com"
#smtp.sasl.scram-sha-256.password.raw = "***"