# Mail Stats - Postfix Summary Tool (v2026.1.1)

![License](https://img.shields.io/badge/license-MIT-green)
![Bash](https://img.shields.io/badge/Bash-4.x+-blue)
![Postfix](https://img.shields.io/badge/Postfix-Logs-lightgrey)

---

## 📋 Table of Contents

1. [Overview](#overview)
2. [Features](#features)
3. [Requirements](#requirements)
4. [Installation](#installation)
5. [Usage](#usage)
6. [Options](#options)
7. [Examples](#examples)
8. [Security & Hardening](#security--hardening)
9. [Notes](#notes)
10. [License](#license)
11. [Author](#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.

![Postfix Mail Summary](https://via.placeholder.com/900x200.png?text=Mail+Stats+Overview)

---

## ✨ 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:

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

No additional dependencies required.

---

## 🛠 Usage

```bash
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:

```bash
mail-stats -l 20
```

Filter by sender:

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

Filter by recipient:

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

Detailed view for Queue ID:

```bash
mail-stats -i 3F2A4B1C0
```

Filter by date:

```bash
mail-stats -d "Mar 27"
```

Search all logs:

```bash
mail-stats -d ""
```

---

## 🛡 Security & Hardening

1. **Resource Limits**

```bash
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

![Detail View](https://via.placeholder.com/900x200.png?text=Detailed+Mail+View)

---

## 📜 License

MIT License – free to use, modify, and distribute

---

## 👤 Author

**robott** – [GitHub](https://git.robott.sk/robott)