Skip to content

Quick Start

Jump to bottom
OCEANOFANYTHING edited this page Sep 3, 2026 · 1 revision

Quick Start

MailGrab has two ways to tell it what to crawl: answer its prompts interactively, or hand it everything up front via flags/a seed file. Both end up calling the same crawl engine — see Architecture if you're curious how that's wired.

Interactive mode

Just run it:

python MailGrab.py

It will:

  1. Print its banner and check you're connected to the internet.
  2. Ask for a URL to scan (http:// is added automatically if you don't type a scheme).
  3. Ask for a search depth — the maximum number of pages to fetch in total (not how many links deep to follow; see Smarter Discovery for the distinction). Interactive mode caps this at 500.
  4. Crawl, printing each page it processes and a running Progress: X/depth Pages Crawled line.
  5. List every email it found, then save everything to _emails.txt, _scrappedUrls.txt, _emails.csv, and _results.json (see Output Files).

Batch mode (many seed URLs)

Create a file named _inputUrls.txt in the same directory, one URL per line:

https://example.com
https://another-site.org
https://a-third-site.net

Run MailGrab with no arguments and it auto-detects the file and crawls every URL in it, one after another, sharing dedup state across all of them — a page found while crawling the first URL won't be re-fetched if a later seed links to it too. You'll be asked for one depth value that applies to every seed (batch mode caps it at 200).

Non-interactive / scripted mode

Every prompt has a matching CLI flag. Give both --url and --depth (or --depth plus a ready _inputUrls.txt file) and MailGrab runs start-to-finish with no prompts at all — safe for cron jobs and CI:

python MailGrab.py --url https://example.com --depth 30

If you give only one of --url/--depth with no way to satisfy the other, MailGrab fails fast with a clear error instead of hanging on a prompt that will never be answered — see CLI Reference for the exact rule.

A more realistic example

Crawl a site, staying on its own domain, keeping the run polite, filtering out placeholder addresses and undeliverable domains:

python MailGrab.py \
  --url https://example.com \
  --depth 100 \
  --same-domain \
  --delay 0.5 \
  --user-agent "MyCompanyBot/1.0 (+https://mycompany.com/bot)" \
  --verify-mx

Run it again later and pick up where you left off, keeping everything already found:

python MailGrab.py --url https://example.com --depth 100 --resume

See CLI Reference for the full flag list, or the feature pages linked from Home for what each one is actually doing.

Clone this wiki locally