undelivered
List bounce messages (undeliverable emails) in mailboxes, or permanently delete them for one domain or the whole server
- Command:
/go/undelivered - Category: Email
- Required option: None
- Output: A table of bounce messages (report) or the paths of deleted files (delete)
- Last updated: 2026-11-20
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]
allis not a special word. Any value that isn't a domain with a folder at/home/<domain>/maildeletes 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
- Deletes
/usr/local/goadmio/tmp/undelivered.db(a text file) and starts a new one. - Goes through every mailbox in
/home/<domain>/mail/<mailbox>and reads the files in itscurandnewfolders. Subfolders such as.Sentor.Junkare not scanned. - Reads at most 1,000 files per mailbox, usually the oldest first, because the file names start with a time stamp.
- Treats a file as a bounce when it contains
Undelivered Mail(case-sensitive). - Works out the failed address from the
To:lines, leaving out the mailbox's own address. - For each bounce, adds a row to the table, appends the failed address to the text file, and adds
(Domain, Email, Date)to theUndeliveredtable 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:
UndeliveredUndeliverabledelivery failedDELIVERY FAILURE:delivery problemsReturned mailfailure notice
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 |