Viewing Mail Logs
The Admin → Logs page provides a browser-based interface for reading and searching Postfix mail logs. Rather than SSHing into the server and tailing /var/log/mail.log, you can filter, search, and colour-code log entries directly from the admin panel.
Log Source
Opterius Mail reads logs from:
- Ubuntu / Debian:
/var/log/mail.log - CentOS / AlmaLinux / RHEL:
/var/log/maillog - Systemd-journal only systems:
journalctl -u postfix(used as fallback when log file is not present)
The log file path can be overridden in .env:
MAIL_LOG_PATH=/var/log/mail.log
Opterius Mail reads logs live — it does not import logs into the database. The log viewer streams file content directly. Log history is limited to what is currently on disk (see log rotation below).
Log Table
Each log entry is displayed as a table row with colour coding:
| Color | Status | Meaning |
|---|---|---|
| Green | status=sent |
Message delivered successfully |
| Yellow | status=deferred |
Temporary delivery failure; Postfix will retry |
| Red | status=bounced |
Permanent delivery failure; bounce sent to sender |
| Grey | Other | Postfix housekeeping, connection entries, etc. |
Columns:
| Column | Source | Example |
|---|---|---|
| Timestamp | Log line date/time | Apr 12 14:23:01 |
| Queue ID | Postfix message ID | 3F4B12345A |
| From | Envelope sender | user@example.com |
| To | Recipient | recipient@other.com |
| Status | Delivery result | sent, deferred, bounced |
| Details | Full Postfix status message | relay=smtp.gmail.com, status=sent (250 OK) |
Filters
Use the filter bar above the log table to narrow results:
| Filter | Description |
|---|---|
| Email address | Shows only log lines mentioning this address (as sender or recipient). Partial match supported. |
| Domain | Shows only log lines for a specific domain (e.g., example.com). |
| Status | Select: All / Sent / Deferred / Bounced. |
| Time range | From / To datetime pickers. Defaults to the last 6 hours. |
| Queue ID | Enter a specific Postfix queue ID to trace a single message's entire journey. |
Tracing a Single Message
The most common use case is diagnosing why a specific message was not delivered:
- Ask the user for the approximate send time and recipient address.
- Set the Email address filter to the recipient or sender address.
- Set the Time range to the relevant window.
- Find the log entries for that message using the queue ID.
- Click the log row to see full detail including relay host, TLS status, and response codes.
A typical successful message produces entries like:
Apr 12 14:23:00 mail postfix/pickup[1234]: 3F4B12345A: uid=33 from=<user@example.com>
Apr 12 14:23:00 mail postfix/cleanup[1235]: 3F4B12345A: message-id=<uuid@example.com>
Apr 12 14:23:00 mail postfix/qmgr[1236]: 3F4B12345A: from=<user@example.com>, size=2048, nrcpt=1
Apr 12 14:23:01 mail postfix/smtp[1237]: 3F4B12345A: to=<recipient@other.com>,
relay=smtp.other.com[203.0.113.2]:25, delay=0.5, status=sent (250 2.0.0 OK)
Click to Expand
Click any log row to expand it and see the raw log line. This is useful when the parsed columns omit detail, such as the full bounce reason or the TLS certificate fingerprint.
Exporting Logs
Click Export as CSV to download the currently filtered log view as a .csv file. The CSV includes all columns and is compatible with Excel, Google Sheets, or any log analysis tool.
The export is based on the current filter settings — if no filters are applied, the export may be very large. Apply time range and address filters before exporting for targeted analysis.
Log Rotation
Mail logs are managed by the system's logrotate daemon, not by Opterius Mail. The default rotation is typically:
- Daily rotation
- 7 days of compressed archives kept
- Files named
mail.log,mail.log.1,mail.log.2.gz, etc.
The log viewer reads only the active log file (mail.log). To search historical logs, use the server CLI:
# Search compressed archives for a specific address
zgrep "recipient@example.com" /var/log/mail.log.*.gz
# Or with journalctl for a date range
journalctl -u postfix --since "2026-04-10" --until "2026-04-11"
Common Log Patterns to Know
# Successful local delivery
status=sent (delivered to maildir)
# Successful relay delivery
status=sent (250 2.0.0 OK)
# Temporary failure (will retry)
status=deferred (connection refused)
status=deferred (host not found)
# Permanent bounce — bad recipient address
status=bounced (user unknown in virtual mailbox table)
# Permanent bounce — rejected by recipient server
status=bounced (550 5.1.1 The email account does not exist)
# Message blocked as spam by recipient
status=bounced (550 5.7.1 Message rejected as spam)
# Sender authentication issue
SASL LOGIN authentication failed