mail-status/README.md

Mail Stats - Postfix Summary Tool (v2026.1.1)

---

📋 Table of Contents

1. Overview
2. Features
3. Requirements
4. Installation
5. Usage
6. Options
7. Examples
8. Security & Hardening
9. Notes
10. License
11. Author

---

🌟 Overview

Mail Stats is a secure, hardened, memory-safe Bash tool for summarizing Postfix mail logs. It provides:

• Filtering by sender, recipient, queue ID, and date
• Concise summary tables or detailed per-message views
• Automatic processing of compressed logs (.gz)
• Color-coded terminal output for easier readability

This tool is ideal for server administrators who need fast insights into sent, rejected, or deferred emails.

---

✨ Features

• Color-coded output for quick status recognition

• Filter by:

  • Sender (from)

  • Recipient (to)

  • Queue ID (id)

  • Date (date)

    • Use -d "" to search across all logs

• Summary or detailed per-message view

• Handles .gz compressed logs automatically

• Excludes local deliveries (127.0.0.1) unless filtered

• Limits CPU, memory, and file usage for safety

---

🖥 Requirements

• Linux/Unix system
• Bash 4.x+
• Postfix logs in /var/log/ (e.g., maillog*, mail.log*)
• awk, zcat, grep, find, sed installed

---

⚡ Installation

Copy or clone the script:

sudo cp mail-stats /usr/local/bin/mail-stats
sudo chmod +x /usr/local/bin/mail-stats

No additional dependencies required.

---

🛠 Usage

mail-stats [OPTIONS]

By default, it displays the last 10 mail log entries for today.

---

🔧 Options

Option	Description
-h, --help	Show help message
-l, --list NUMBER	Number of records (default 10, max 1000)
-f, --from EMAIL/DOMAIN	Filter by sender
-t, --to EMAIL/DOMAIN	Filter by recipient
-i, --id QUEUE_ID	Show detailed view of specific queue ID
-d, --date "MMM DD"	Filter by date (e.g., "Mar 27")

---

📝 Examples

Show last 20 emails:

mail-stats -l 20

Filter by sender:

mail-stats -f "example@domain.com"

Filter by recipient:

mail-stats -t "recipient@domain.com"

Detailed view for Queue ID:

mail-stats -i 3F2A4B1C0

Filter by date:

mail-stats -d "Mar 27"

Search all logs:

mail-stats -d ""

---

🛡 Security & Hardening

1. Resource Limits

ulimit -t 15        # CPU time
ulimit -v 500000    # Virtual memory (kB)
ulimit -f 102400    # Max file size

2. Single Instance Locking

• Prevents simultaneous executions via /tmp/mail-stats.lock

3. Temporary File Safety

• Uses mktemp and cleans files on exit

4. Safe Argument Handling

• Limits input length and validates required arguments

5. Memory-Safe Log Parsing

• Skips overly long/short lines

6. Old Temp File Cleanup

• Deletes stale files older than 10 minutes

---

⚠ Notes

• Ignores local Postfix deliveries (127.0.0.1) by default

• Supports .gz compressed logs

• Detailed view (--id) shows:

  • Date/Time
  • Client IP
  • Sender
  • Recipient
  • Status
  • Reason

---

📜 License

MIT License – free to use, modify, and distribute

---

👤 Author

robott – GitHub