GoAdmio

undelivered

List bounce messages (undeliverable emails) in mailboxes, or permanently delete them for one domain or the whole server

On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also


Overview

When a message can't be delivered, the mail server sends a bounce message ("Undelivered Mail Returned to Sender") back to the sender's mailbox. On busy accounts these pile up. /go/undelivered has two modes:

Mode Command What it does
Report /go/undelivered Scans the mailboxes, lists the bounce messages it finds, and saves the failed addresses to a database. Deletes nothing.
Delete /go/undelivered <domain> Permanently deletes matching messages in one domain's mailboxes, or on all domains.

The command doesn't need sudo. If you aren't root, it runs itself again with sudo.

[!WARNING] Delete mode removes files for good. There is no trash and no confirmation. It matches words anywhere in a message, so it can also delete normal emails. Read Delete mode and take a backup first.


Quick start

# See which bounce messages exist
/go/undelivered

# Delete them for one domain
/go/undelivered example.com

Syntax

/go/undelivered                 # report
/go/undelivered <domain>        # delete in one domain
/go/undelivered all             # delete on every domain

[!CAUTION] all is not a special word. Any value that isn't a domain with a folder at /home/<domain>/mail deletes on every domain on the server. A mistyped domain name does the same.


Options

Argument Required Default Notes
<domain> No Report mode A hosting account's domain, with a mail folder at /home/<domain>/mail.

Anything else you pass after the first argument is ignored.


Output

Report mode

A table with one row for each bounce message found:

  │ # │ Email Account    │ To                │ Date
  │ 1 │ info@example.com │ missing@other.com │ 2026-11-18
  │ 2 │ info@example.com │ old@example.org   │ 2026-11-19
Column Meaning
# A running number.
Email Account The mailbox that received the bounce.
To The address the original message was sent to, taken from the To: headers. It shows - or is empty when no address could be found.
Date The date of the file in the mailbox.

If nothing is found, only the header is printed.

Delete mode

Deleting undeliverable emails on domain example.com
/home/example.com/mail/info/cur/1731923456.M123P456.host,S=4521:2,S
...

The first line is Deleting all undeliverable emails when it runs on every domain. After it, the command prints the path of each file it deleted.

Exit status

Outcome Exit status
Report finished 0
Delete finished 1 (even on success)

Every run is logged to /var/log/go/undelivered.log with a timestamp and the arguments used.


Examples

# Report: which bounces are in the mailboxes?
/go/undelivered
# Delete bounces on one domain
/go/undelivered example.com
# Delete bounces on every domain
/go/undelivered all
# Take a backup of a domain's mail first (see the backup command)
/go/backup

Troubleshooting

Symptom Likely cause Fix
Messages were deleted on all domains, not one The domain name was misspelled, or has no /home/<domain>/mail folder. Restore the mail from a backup (see restore and snapshot). Check the spelling before every run.
Normal emails were deleted They contain one of the search words, such as "returned mail" or "delivery failed" (shipping notices often do). Restore them from a backup. Use the report to review what is there first.
The report is empty but bounces exist The report only recognizes messages containing Undelivered Mail, only scans each mailbox's main folder (cur and new), and stops after 1,000 messages per mailbox. Check by hand, or run delete mode if you are sure.
The report finds fewer messages than delete mode removes Delete mode searches for more words than the report does. See Delete mode.
The To column shows - or is empty No address could be read from the To: headers. Open the message to see which address failed.
The report is slow Several commands run for every message, up to 1,000 per mailbox. Run it at a quiet time.
Exit status 1 after deleting By design. Don't treat it as an error.

Details

Report mode

  1. Deletes /usr/local/goadmio/tmp/undelivered.db (a text file) and starts a new one.
  2. Goes through every mailbox in /home/<domain>/mail/<mailbox> and reads the files in its cur and new folders. Subfolders such as .Sent or .Junk are not scanned.
  3. Reads at most 1,000 files per mailbox, usually the oldest first, because the file names start with a time stamp.
  4. Treats a file as a bounce when it contains Undelivered Mail (case-sensitive).
  5. Works out the failed address from the To: lines, leaving out the mailbox's own address.
  6. For each bounce, adds a row to the table, appends the failed address to the text file, and adds (Domain, Email, Date) to the Undelivered table in /var/lib/sqlite/undelivered.db. Rows that would repeat an existing one are skipped.

So although the report doesn't delete anything, it does write to those two files.

Delete mode

flowchart TD
    A["/go/undelivered arg"] --> B{"arg given?"}
    B -- "No" --> R["Report mode"]
    B -- "Yes" --> C{"/home/arg/mail exists?"}
    C -- "Yes" --> D["Delete matching files in that domain"]
    C -- "No" --> E["Delete matching files on ALL domains"]

A file is deleted when it contains any of these phrases, in any letter case:

The search covers every file under the mail folder, not only the inbox: all folders (Sent, Trash, and so on), the body of each message, and any other file stored there. Messages that merely mention these phrases are deleted too.

Files and requirements

Item Used for
/home/<domain>/mail The mailboxes searched.
/var/lib/sqlite/undelivered.db The Undelivered table: Domain, Email, Date.
/usr/local/goadmio/tmp/undelivered.db A text list of failed addresses from the last report.
/var/log/go/undelivered.log The command log.
sqlite3, column Saving results and printing the table.

See also

Command Description
deletemailqueue Delete all emails in the Postfix mail queue
troubleshoot Troubleshoot email problems in GoAdmio
mailtop Check the most active email accounts in GoAdmio
spam Track spam email accounts in GoAdmio
outgoing Report today's outbound mail sessions
backup Create a backup for all GoAdmio accounts (local and remote)
snapshot Restic-based per-domain snapshot backup and restore
restore Restore a GoAdmio backup from the command line