Configuration Reference

Config File Location

By default, Mailgator looks for mailgator-config.toml in the current working directory. You can specify a different path with the -c or --config flag:

mailgator serve -c /etc/mailgator/config.toml

Secrets File

Mailgator automatically creates a companion secrets file alongside your config. If your config is named mailgator-config.toml, the secrets file will be mailgator-config-secrets.toml.

The secrets file stores sensitive values that should not be committed to version control:

• license_token -- your license JWT (saved by mailgator license login)
• encryption_key -- AES-256-GCM key for encrypting credentials in the ask flow (auto-generated)

The secrets file is created with 0600 permissions (owner read/write only). Back it up safely -- if you lose the encryption key, pending approval emails cannot be replayed.

# mailgator-config-secrets.toml (auto-managed, do not edit manually)
license_token = "eyJhbGciOi..."
encryption_key = "base64-encoded-key..."

[imap] Section

Configures the IMAP proxy -- where to listen and which upstream server to forward traffic to.

[imap]
listen_addr = "127.0.0.1:1993"
upstream_addr = "imap.gmail.com:993"
upstream_tls = "tls"
upstream_tls_skip_verify = false

[smtp] Section

Same structure as the IMAP section, but for SMTP connections:

[smtp]
listen_addr = "127.0.0.1:1587"
upstream_addr = "smtp.gmail.com:587"
upstream_tls = "starttls"
upstream_tls_skip_verify = false

All options work exactly the same as the IMAP section above.

TLS Modes

The upstream_tls option controls how Mailgator connects to your mail server. There are three modes:

If you omit upstream_tls, Mailgator auto-detects the mode based on the port:

Complete Config Example

Here is a full configuration file with every section filled in:

[smtp]
upstream_addr = "smtp.gmail.com:587"
listen_addr = "127.0.0.1:1587"

[imap]
upstream_addr = "imap.gmail.com:993"
listen_addr = "127.0.0.1:1993"

[[rules]]
name = "Read everything"
action = "allow"
operations = ["read"]

[[rules]]
name = "Send to company"
to = "*@mycompany.com"
action = "allow"
operations = ["mail:send"]

[[rules]]
name = "Ask before external sends"
action = "ask"
operations = ["mail:send"]
ask_groups = ["managers"]

[[rules]]
name = "Deny the rest"
action = "deny"

# Required for ask rules
[database]
path = "mailgator.db"

[web]
listen_addr = "127.0.0.1:8080"

[ask]
timeout_in_minutes = 30
retention_days = 30
base_url = "https://mailgator.example.com"
reply_domain = "approve.example.com"

[ask.groups.managers]
recipients = ["manager@mycompany.com", "lead@mycompany.com"]

Environment Variables

Mailgator recognizes these environment variables: