Manage GoAdmio email accounts from the command line: add an address, change its password, suspend, unsuspend, or delete it, set a domain's default (catch-all) address, restore accounts from mail folders, and restart the mail services
- Command:
/go/mail - Category: Mail
- Required option:
--action(and--emailfor every action exceptcreate) - Output: JSON for
add; a short message for the other actions - Log:
/var/log/go/mail.log - Last updated: 2026-11-20
On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · Security · See also
Overview
/go/mail creates and manages the email accounts of hosted domains. Depending on --action, it can:
- add a new email account and print its connection settings
- edit an account's password
- suspend or unsuspend an account
- delete an account
- default: choose which address receives all mail sent to addresses that don't exist (a catch-all)
- create: rebuild the account list from the mailbox folders on disk
- restart the mail services
Most actions end by starting /go/vmail in the background, which rebuilds the mail maps for Postfix and Dovecot. A change usually takes effect a few seconds after the command finishes.
If you aren't root, the command re-runs itself with sudo.
Quick start
# Add an address
/go/mail --action add --email info@example.com --domain example.com --pass 'S3cure-Pass9'
# Change its password
/go/mail --action edit --email info@example.com --pass 'N3w-Pass-42'
[!WARNING] Always pass
--action addto create an account, and always pass--pass. Without--action add, nothing is created. Without--pass, the account is created with an empty password. Passwords are also written to the log in plain text. See Security.
Syntax
# Manage accounts
/go/mail --action <action> --email <address> [options]
# Restart the mail services
/go/mail restart
| Form | Behavior |
|---|---|
/go/mail --action ... [options] |
Every setting is passed as an --option value pair. An option without a value isn't allowed, even --norestart (use --norestart 1). |
/go/mail restart |
Rebuilds the Postfix lookup tables and restarts the mail services. There is no -- before restart. |
An unrecognized option stops the command with MAIL: Unknown parameter: <option>. Nothing is changed.
The email address is converted to lower case.
Options
Actions
--action |
What it does | Needs |
|---|---|---|
add |
Creates the account, its mailbox folder, and prints the connection settings. | --email, --pass, and --domain |
edit |
Sets a new password. | --email, --pass |
suspend |
Marks the account as suspended. | --email |
unsuspend |
Removes the suspension. | --email |
delete |
Removes the account. See Known limitations for the mailbox files. | --email, --domain |
default |
Makes the address the catch-all of its domain. | --email, --domain |
create |
Creates accounts for the mailbox folders found under /home/<domain>/mail. |
--domain |
If --action is missing or isn't one of these, the command only checks the address and the domain, clears any rejection entry for the address, and rebuilds the mail maps. It creates nothing and prints no error.
Settings
| Option | Used by | Notes |
|---|---|---|
--email |
All actions except create |
The full address, such as info@example.com. For add, it must be a valid address on a domain hosted on this server. |
--pass |
add, edit |
The password. Avoid single quotes (') in it. |
--domain |
add, delete, default, create |
The hosted domain. For add, it is used to look up the account's system username, so pass it even though the domain also appears in the address. |
--forwardto |
add |
Forwarding address. Stored with the account. |
--keepcopy |
add |
Stored with the account, normally used with --forwardto. |
--reject |
add |
Stored with the account. |
--rejectmessage |
add |
Stored with the account. |
--defaultaddress |
add |
Stored with the account. |
--suspend |
add |
Stored with the account. |
--admin |
add |
Stored with the account. |
--description |
add |
A note about the account. |
--norestart |
All actions that rebuild the maps | 1 skips the background vmail rebuild. |
--timestamp |
None | Accepted, but ignored. The current time is always used. |
Settings you don't pass are stored as empty values.
Output
add
A single line of JSON with the connection settings for the new account. It prints "success": true whenever the command reaches this point, so don't rely on it to prove that the account exists.
{
"success": true,
"title": "creating_email_account",
"result": {
"incoming_mail_server_imap": "",
"account_type": "IMAP",
"imap_username": "info@example.com",
"imap_hostname": "imap.example.com",
"imap_port": "993",
"imap_encryption": "SSL",
"null": "",
"outgoing_mail_server_smtp": "",
"smtp_username": "info@example.com",
"smtp_hostname": "smtp.example.com",
"smtp_port": "465",
"smtp_encryption": "SSL"
}
}
The real output is one line; it is formatted here for readability. The password is not included.
The host names and ports depend on the SSL certificates on the server:
| Condition | IMAP | SMTP |
|---|---|---|
| The domain has a Let's Encrypt certificate | imap.<domain>, port 993, SSL |
smtp.<domain>, port 465, SSL |
| Otherwise, the server hostname has one | The IMAP hostname (from /etc/imap, or the server hostname), port 993, SSL |
The server hostname, port 465, SSL |
| Neither | imap.<domain>, port 143, no encryption |
smtp.<domain>, port 25, no encryption |
If the server setting IMAPAlert is 1, the new address also receives its configuration by email, sent in the background with outlook.
Other actions
| Action | Message |
|---|---|
default with --email |
GoAdmio will forward all unrouted email for <domain> to <email>. |
default without an address |
GoAdmio will forward all unrouted email for <domain> to 'Recipient address rejected: User unknown.' (see Known limitations) |
delete |
<email> has been deleted. |
suspend |
<email> has been suspended. |
unsuspend |
<email> has been unsuspended. |
edit |
<email> Password has been modified successfully. The line written to Dovecot's password file is also printed. |
Errors and exit status
| Message | Meaning | Exit status |
|---|---|---|
MAIL: Unknown parameter: <option> |
A misspelled or unsupported option. | 1 |
Invalid Email Address <email>. |
The address isn't valid. | 1 |
Account <domain> not exists |
The domain isn't hosted on this server. | 1 |
restart and edit always exit with status 1, even when they work. Read the output, not the exit status.
Examples
# Add an address
/go/mail --action add --email info@example.com --domain example.com --pass 'S3cure-Pass9'
# Add an address that forwards to another one
/go/mail --action add --email sales@example.com --domain example.com --pass 'S3cure-Pass9' \
--forwardto owner@example.org
# Add several addresses, then rebuild the mail maps once
/go/mail --action add --email a@example.com --domain example.com --pass 'Pass-One-1' --norestart 1
/go/mail --action add --email b@example.com --domain example.com --pass 'Pass-Two-2' --norestart 1
/go/vmail
# Change a password
/go/mail --action edit --email info@example.com --pass 'N3w-Pass-42'
# Suspend and unsuspend an address
/go/mail --action suspend --email info@example.com
/go/mail --action unsuspend --email info@example.com
# Delete an address
/go/mail --action delete --email info@example.com --domain example.com
# Send all mail for unknown addresses to info@example.com
/go/mail --action default --email info@example.com --domain example.com
# Recreate accounts from the folders under /home/example.com/mail
/go/mail --action create --domain example.com
# Restart the mail services
/go/mail restart
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
MAIL: Unknown parameter: --restart |
restart is a word, not an option. |
Run /go/mail restart. |
| Nothing was created | --action add was missing. |
Add --action add. |
| The account was created but the password is empty | --pass wasn't given. |
Set it with --action edit --pass .... |
Invalid Email Address ... |
The address isn't valid. | Check for spaces and missing parts. |
Account <domain> not exists |
The domain isn't hosted here. | Create the account with create first. |
| The new address can't log in yet | The mail maps are rebuilt in the background. | Wait a minute, or run vmail. If you used --norestart 1, run vmail yourself. |
An add or edit with a password fails or does something odd |
The password contains a single quote ('). |
Use a password without '. |
The Username of a new account is empty |
--domain wasn't passed with add. |
Pass --domain. |
The mailbox folder is still on disk after delete |
The folder removal doesn't run. See Known limitations. | After checking that it isn't needed, remove /home/<domain>/mail/<user>. Errors go to /var/log/go/background/<user>.log. |
Passwords of existing accounts changed after create |
create sets a new random password for every folder it finds. |
Set known passwords with --action edit. |
Password has been modified successfully appears while adding |
Dovecot's password file already has an entry for this address. | Check that the account doesn't already exist. |
A script reports failure after edit or restart |
They always exit with status 1. |
Ignore the status for these two, and read the output. |
Details
How it works
flowchart TD
A["mail ..."] --> B{"Root?"}
B -- "No" --> C["Re-run with sudo"]
B -- "Yes" --> D{"Arguments contain --?"}
C --> D
D -- "Yes" --> E["Read options, stop on unknown"]
D -- "No" --> F["No options"]
E --> G{"restart?"}
F --> G
G -- "Yes" --> R["Rebuild tables, restart services, exit 1"]
G -- "No" --> H{"Action"}
H -- "edit" --> I["Change password, then restart, exit 1"]
H -- "default / delete / suspend / unsuspend / create" --> J["Update the Mail database"]
H -- "add or other" --> K["Validate address and domain"]
K --> L["add: insert, create mailbox folder, print JSON"]
J --> M{"--norestart 1?"}
L --> M
M -- "No" --> N["Run vmail in the background"]
M -- "Yes" --> O["Done"]
What restart does
- Runs
postmapon each of these files that exists:custom_replies,vmail_domains,vmail_mailbox,vmail_aliases,vmail_relay,vmail_sasl_passwd(all in/etc/postfix/), andvmail_ssl(as an LMDB table). - Restarts
postfix,postfwd,dovecot,saslauthd,opendkim, andopendmarc. - Exits with status
1.
What add does
- Checks the address, and that its domain is hosted on this server.
- Adds a row to the
Mailtable in/var/lib/sqlite/mail.db, with the password and settings you gave. - Creates
/home/<domain>/mail/<user>, with mode700, owned byvmail. - Removes any rejection entry for the address from
/etc/postfix/custom_replies. - Prints the connection settings as JSON.
- If
IMAPAlertis1, emails the settings to the new address. - Starts
/go/vmailin the background, unless--norestart 1was given.
Dovecot's password file isn't edited by add. The new login is created by vmail.
What edit does
- Saves the new password in the
Mailtable. - Replaces the account's line in
/etc/dovecot/passwdwith the SHA1 hash of the new password. - Runs
/go/mail restart, which restarts every mail service.
What create does
For each folder under /home/<domain>/mail, create adds an account for <folder>@<domain> if it isn't in the database. If /home/<domain>/mail/<folder>.conf exists, its saved settings are loaded first. It then gives the account a new random 8-character password. This is meant for rebuilding the account list after a restore. See also restoremail.
Files used
| File | Purpose |
|---|---|
/var/lib/sqlite/mail.db |
The Mail table: all accounts and their settings. |
/var/lib/sqlite/site.db |
Used to check that the domain is hosted, and to find its username. |
/var/lib/sqlite/config.db |
Provides the IMAPAlert setting. |
/etc/dovecot/passwd |
Dovecot logins, edited by edit and delete. |
/etc/postfix/custom_replies |
Per-address rejection replies. |
/home/<domain>/mail/<user> |
The mailbox folder. |
/var/log/go/mail.log |
A log of every call, with its arguments. |
Known limitations
deletedoesn't remove the mailbox files. The folder removal is started in the background, but the command is quoted as one word, so it can't run. The account is removed from the database and from Dovecot, but/home/<domain>/mail/<user>stays on disk.createresets passwords. It sets a new random password for every folder it finds, including accounts that already exist, and doesn't show it. Values loaded from one folder's.conffile can also carry over to the next folder.createneeds the mail folder to exist. If/home/<domain>/mailis missing, the folder change fails and the command looks at the folders in the directory you ran it from.defaultwithout an address changes nothing. It prints the "User unknown" message, but doesn't clear the existing default address.adddoesn't check for duplicates or empty passwords.addprints"success": trueregardless of whether the database insert worked.--actionhas no validation. A missing or misspelled action runs the short validation path described under Options.- Values aren't escaped. Single quotes in a password, description, or other setting break the database statement.
--timestampis ignored.
Security
- Passwords are logged in plain text. Every call is written to
/var/log/go/mail.logwith its arguments, so--passand its value are stored there. The password also appears in the process list and your shell history while the command runs. - Passwords are stored in plain text in the
Mailtable of/var/lib/sqlite/mail.db. Dovecot's password file holds an unsalted SHA1 hash. editprints the hash. The line written to/etc/dovecot/passwdis also shown in your terminal.createruns saved settings as code. The<folder>.conffile is loaded as a shell script with root privileges, so only trusted files should be in the mail folders.- Keep
/var/log/go/and/var/lib/sqlite/readable by root only.
See also
| Command | Description |
|---|---|
vmail |
Rebuild the Postfix/Dovecot vmail maps |
mailpwd |
Bulk-change passwords for all email accounts of a single domain |
restoremail |
Recreate mail accounts from folders on disk |
outlook |
Send IMAP/SMTP configuration to email accounts |
forward |
Configure per-domain email forwarding |
responder |
Create or delete an email autoresponder |
troubleshoot |
Troubleshoot email problems in GoAdmio |
mailtop |
Check the most active email accounts in GoAdmio |
create |
Create a GoAdmio account from the command line |