Configuration File

Configuration File

--config <path.json> lets you save a setup you use repeatedly instead of retyping flags every time.

How it works

A config file is a flat JSON object whose keys are the same names as the environment variables, just lowercase and without the MAILGRAB_ prefix. MailGrab loads it very early — before it reads any of the actual settings — and for each key does the equivalent of:

os.environ.setdefault("MAILGRAB_" + key.upper(), str(value))

setdefault is the important part: it only fills in an environment variable that isn't already set. A config file value never overrides a real environment variable, and a CLI flag always wins over both (CLI flags are read directly, not through the environment). This is deliberate — there's exactly one precedence system in MailGrab (environment variables), and --config is just a convenient way to pre-populate it rather than a second, competing configuration mechanism.

Example

{
  "concurrency": "20",
  "delay": "0.5",
  "same_domain": "1",
  "user_agent": "MyCompanyBot/1.0"
}

python MailGrab.py --url https://example.com --depth 50 --config myconfig.json

This is equivalent to setting MAILGRAB_MAX_WORKERS=20 MAILGRAB_DELAY=0.5 MAILGRAB_SAME_DOMAIN=1 MAILGRAB_USER_AGENT=MyCompanyBot/1.0 in your shell before running the same command — except real environment variables you've already set, or CLI flags you pass alongside --config, still take priority.

Values are always strings

Because config values just get shoved into os.environ as strings, write numbers and booleans as JSON strings ("20", not 20; "1", not true) to match what the environment-variable parsing expects. A bare JSON number or boolean will be coerced to a string too (str(20) → "20"), so it happens to work for plain values, but keeping them as strings avoids surprises.

Errors

A missing file or invalid JSON exits immediately with a clear error message and exit code 1, rather than crashing with a raw Python traceback:

Error: Could Not Load --config File 'myconfig.json': [Errno 2] No such file or directory: 'myconfig.json'

YAML?

Only JSON is supported. YAML support was considered and deliberately skipped — JSON needs no extra dependency and covers exactly the same need (a flat key/value settings file). If you maintain configs by hand a lot and want YAML's more forgiving syntax, that's a reasonable thing to add — see the repo's TODO.md.