Configuration

One JSON file.

There is no environment-only mode. Configuration lives in a file; the environment is only a source of secrets, referenced from that file.

Where it is read from

MAILGLASS_CONFIG: an explicit path
~/.config/mailglass/config.json
~/.mailglass/config.json

If none exists, the server refuses to start and prints both default paths.

Full schema

config.json

      {
  "defaultAccount": "work",

  "storage": { "dir": "~/.mailglass", "cache": true, "maxEmlBytes": 26214400 },
  "session": { "ttlSeconds": 60 },
  "proxy":   { "url": "socks5://proxy.internal:1080" },

  "providers": {
    "gmail": { "readOnly": true },
    "imap":  { "readOnly": true }
  },

  "accounts": [
    {
      "id": "work",
      "provider": "gmail",
      "label": "Work Gmail",
      "email": "me@company.com",
      "enabled": true,
      "auth": {
        "username": "me@company.com",
        "password": { "file": "~/.secrets/work_gmail_app_password" }
      }
    },
    {
      "id": "corp",
      "provider": "imap",
      "label": "Corporate IMAP",
      "email": "me@corp.example",
      "auth": {
        "username": "me",
        "password": { "env": "CORP_IMAP_PASSWORD" }
      },
      "connection": {
        "host": "mail.corp.example",
        "port": 993,
        "secure": true,
        "rejectUnauthorized": true
      }
    }
  ]
}
    

Unknown keys are rejected. A typo like "provder" fails loudly instead of silently falling back to defaults.

Secrets are references

Form	Example
Environment	`{ "env": "WORK_GMAIL_PASSWORD" }`
File (chmod 600)	`{ "file": "~/.secrets/work_gmail" }`

Never literals, so the config can be shared safely. App passwords are whitespace-stripped: Google shows them as abcd efgh ijkl mnop and the spaces are cosmetic.

Need a Gmail app password?

For Gmail, auth.password points at a Google app password. If you do not have one yet, see Create a Gmail app password, which covers 2-Step Verification, IMAP and where to store the value.

`email` vs `auth.username`

email is identity only: what gets displayed and masked. auth.username is what authenticates, and defaults to email when omitted. They differ on many IMAP servers, and for Gmail aliases.

The read-only gate

Resolved per account as account.readOnly ?? provider.readOnly ?? true. When true, write capabilities are withheld entirely; they cannot be registered. Defaulting to true means a config that says nothing can never send or delete mail.

Local storage

Key	Default	Meaning
`storage.dir`	`~/.mailglass`	Base directory; one subdirectory per account id
`storage.cache`	`true`	`false` performs no disk writes at all
`storage.maxEmlBytes`	26214400	Skip caching larger messages; `0` means unlimited
`session.ttlSeconds`	`60`	Keep an idle connection this long; `0` closes after each call
`proxy.url`	none	`http:`, `https:` or `socks*:` proxy for IMAP

Cached mail is plaintext on disk: directories are 0700 and files 0600. Purge with rm -rf ~/.mailglass/<account-id>.

Diagnostics

terminal

      mailglass --check                 # default account
mailglass --check --account corp     # one account
mailglass --check --all              # every enabled account
    

Exit codes: 0 ok, 1 config, 2 credentials rejected, 3 network. Email addresses are masked in every line.