Configuration

# Copy this file to .mailfire.conf or a configuration location listed in README.md.
# Replace the required values below. On Linux/macOS, run chmod 600 on your copy.
# Optional settings are commented out and show their defaults unless noted.
#
# Environment overrides: each setting names its variable in an "Env:" line,
# MAILFIRE_<SECTION>_<KEY> with the section and key uppercased.
# Precedence: command-line options > nonempty MAILFIRE_* variables >
# this file > built-in defaults. Empty or whitespace-only variables count
# as unset and never clear a file value or default.
# Variable values use the setting's syntax without TOML quotes: booleans are
# true or false; durations and sizes are plain text such as 30s or 50M.
# Example (placeholder values; keep real keys in your CI secret store):
# export MAILFIRE_MAILGUN_API_KEY="<your-api-key>"
# export MAILFIRE_SENDING_DOMAIN="example.com"
# Details: https://mailfire.system42.io/reference/environment/

[mailgun]
# Required: your Mailgun API key.
# Env: MAILFIRE_MAILGUN_API_KEY
api_key = "<your-api-key>"

# Required: your Mailgun region, "us" or "eu".
# Env: MAILFIRE_MAILGUN_REGION
region = "eu"

# Optional per-request timeout for Mailgun API calls: connection setup,
# upload, and response reading. Go duration syntax, e.g. "15s" or "1m".
# --timeout overrides this setting. A resend retrying several messages
# may take longer than a single timeout.
# Env: MAILFIRE_MAILGUN_TIMEOUT
# timeout = "30s"

[sending]
# Sending provider: "mailgun" (default), "smtp", or "gmail". Only the
# selected provider's section must be complete. Deferred messages are always
# resent through the provider they were first sent through.
# Env: MAILFIRE_SENDING_PROVIDER
# provider = "mailgun"

# Sending domain. Required for Mailgun (the domain configured in Mailgun) and
# SMTP (it scopes notification deduplication); optional for Gmail.
# Env: MAILFIRE_SENDING_DOMAIN
domain = "example.com"

# Optional sender. If omitted, supply --from for each email.
# Accepts "user@example.com" or "My Name <user@example.com>".
# Env: MAILFIRE_SENDING_FROM
from = "My Name <user@example.com>"

# Template for --md and --html: card, card-serif, plain, or plain-serif.
# Either --template or --template-file overrides the configured default.
# send --preview reads only template or template_file; it needs no credentials.
# template and template_file are one selection: either variable replaces
# both file settings. Setting both variables is an error, even with
# --template or --template-file.
# Env: MAILFIRE_SENDING_TEMPLATE
# template = "card"

# Custom template path (no default). Mutually exclusive with template.
# Export editable built-ins with: mailfire export-templates ./my-templates
# Paths support ~; relative paths use the current working directory.
# Env: MAILFIRE_SENDING_TEMPLATE_FILE
# template_file = "./my-templates/card.html"

[smtp]
# Used with [sending] provider = "smtp": submission to an existing email
# provider or a local relay. No Mailgun settings are needed.

# Required: the submission server.
# Env: MAILFIRE_SMTP_HOST
# host = "smtp.example.com"

# Required: the port, usually 465 with security = "tls" and 587 with
# security = "starttls".
# Env: MAILFIRE_SMTP_PORT
# port = 587

# Required: "tls" (implicit TLS), "starttls" (STARTTLS required; never falls
# back to plaintext), or "none" (plaintext, only for a trusted local relay).
# Certificates and host names are always verified.
# Env: MAILFIRE_SMTP_SECURITY
# security = "starttls"

# Optional credentials; set both or neither (an unauthenticated relay).
# Never sent with security = "none". Many providers, Gmail included, need an
# app password; an ordinary account password is not a supported shortcut.
# Prefer MAILFIRE_SMTP_PASSWORD over storing the password in this file.
# Env: MAILFIRE_SMTP_USERNAME
# username = "submission-user"
# Env: MAILFIRE_SMTP_PASSWORD
# password = "<app-password>"

# Optional timeout for the whole connection: connect, TLS, authentication,
# and submission. --timeout overrides it.
# Env: MAILFIRE_SMTP_TIMEOUT
# timeout = "30s"

[gmail]
# Used with [sending] provider = "gmail" and by mailfire auth. Authorize once
# with: mailfire auth login --provider gmail (send-only access).

# Credential file, created owner-only by auth login. Defaults:
# Linux/macOS: ~/.config/mailfire/gmail-credentials.json
# Windows: %APPDATA%\mailfire\gmail-credentials.json
# Do not commit or share it: it contains the refresh token.
# Env: MAILFIRE_GMAIL_CREDENTIALS
# credentials = "~/.config/mailfire/gmail-credentials.json"

# Optional timeout for Gmail API and token requests. --timeout overrides it.
# Env: MAILFIRE_GMAIL_TIMEOUT
# timeout = "30s"

[logging]
# Logging is disabled unless logfile is set. Entries use JSON format.
# Example paths (no default):
# Env: MAILFIRE_LOGGING_LOGFILE
# logfile = "~/logs/mailfire.log"
# Windows: literal strings keep backslashes unescaped.
# logfile = 'C:\Users\me\AppData\Local\mailfire\mailfire.log'

# Levels: error, information, or debug.
# error: failed attempts only, with timestamp, message ID, recipients, and status.
# information: all attempts, also including the subject.
# debug: also includes sender, message size, and API response body.
# Env: MAILFIRE_LOGGING_LOGLEVEL
# loglevel = "information"

# Maximum log size. Oldest lines are removed when the limit is exceeded.
# Sizes accept bytes or a K, M, or G suffix (also used in [defer]).
# Env: MAILFIRE_LOGGING_MAX_SIZE
# max_size = "50M"

[defer]
# Store failed sends for retry with mailfire resend.
# --no-defer disables deferral for a single send; test sends are never deferred.
# Env: MAILFIRE_DEFER_DEFER (true or false)
# defer = true

# The directory is created automatically. Defaults:
# Linux/macOS: $HOME/.local/share/mailfire
# Windows: %LOCALAPPDATA%\mailfire
# Example override:
# Env: MAILFIRE_DEFER_DEFER_DIR
# defer_dir = "~/mailfire/deferred"

# Maximum total size. Oldest deferred messages are removed when exceeded.
# Env: MAILFIRE_DEFER_MAX_SIZE
# max_size = "50M"

# Wait after deferral before mailfire resend retries a message. Each failed
# retry doubles the wait, measured from the latest attempt, up to one hour
# (a cooldown above one hour is used unchanged).
# Use resend --force to ignore the wait for one run.
# Env: MAILFIRE_DEFER_RESEND_COOLDOWN
# resend_cooldown = "5m"

# Optional maximum message age; no default (messages are kept until sent or
# deleted, subject to max_size). Older messages are removed, and reported,
# whenever a message is deferred or mailfire resend runs.
# Env: MAILFIRE_DEFER_MAX_AGE
# max_age = "168h"

[dedup]
# Notification deduplication applies only to sends with --dedup-key; omit
# the flag to send a repeat anyway. Works with or without deferral.

# The state directory is created automatically. Defaults:
# Linux/macOS: $HOME/.local/share/mailfire/dedup
# Windows: %LOCALAPPDATA%\mailfire\dedup
# Inside defer_dir, only its subdirectory "dedup" may be used.
# Env: MAILFIRE_DEDUP_STATE_DIR
# state_dir = "~/mailfire/dedup"

# How long a delivered notification suppresses repeats with the same key,
# sending domain, and recipients. --cooldown overrides it per send.
# Env: MAILFIRE_DEDUP_COOLDOWN
# cooldown = "1h"