GoAdmio

mail

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

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:

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 add to 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

  1. Runs postmap on each of these files that exists: custom_replies, vmail_domains, vmail_mailbox, vmail_aliases, vmail_relay, vmail_sasl_passwd (all in /etc/postfix/), and vmail_ssl (as an LMDB table).
  2. Restarts postfix, postfwd, dovecot, saslauthd, opendkim, and opendmarc.
  3. Exits with status 1.

What add does

  1. Checks the address, and that its domain is hosted on this server.
  2. Adds a row to the Mail table in /var/lib/sqlite/mail.db, with the password and settings you gave.
  3. Creates /home/<domain>/mail/<user>, with mode 700, owned by vmail.
  4. Removes any rejection entry for the address from /etc/postfix/custom_replies.
  5. Prints the connection settings as JSON.
  6. If IMAPAlert is 1, emails the settings to the new address.
  7. Starts /go/vmail in the background, unless --norestart 1 was given.

Dovecot's password file isn't edited by add. The new login is created by vmail.

What edit does

  1. Saves the new password in the Mail table.
  2. Replaces the account's line in /etc/dovecot/passwd with the SHA1 hash of the new password.
  3. 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


Security


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