checksmtp
Check that the server's SMTP service accepts a login on port 587 by sending a test email, try to repair it automatically, and alert the administrator when it keeps failing
- Command:
/go/checksmtp - Category: Email
- Required option: None
- Output: A message only when something is wrong or was repaired
- Last updated: 2026-11-20
On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also
Overview
/go/checksmtp makes sure that people can send email through your server. It:
- checks that the server host name is valid and points to this server
- logs in to the server's SMTP service on port 587 with a real mailbox and sends a test email
- if the test fails, rebuilds the mail configuration and tries again, up to three attempts in total
- alerts the administrator by email and WhatsApp when the host name or DNS is wrong, or when all attempts fail
The command does not check the SSL certificate. To check the certificates for SMTP and IMAP, use checkmail and checkimap.
[!WARNING] Each test sends a real email to a fixed address,
gbp.uae@gmail.com, written in the script, from the mailbox of one of your users. A single run can send up to three. See Known issues.
Quick start
/go/checksmtp
Syntax
/go/checksmtp
The command takes no options or arguments. Run it as root. It needs curl and dig.
Options
None. Any arguments you pass are ignored.
Output
The command prints nothing when the first test succeeds. Other results:
| Message | Meaning |
|---|---|
Invalid Hostname (<hostname>), A hostname should consist of a name and a domain name. All valid hostnames should have 2 dots in them. |
The server host name has fewer than 2 dots. The administrator is alerted and the command stops. |
Please Point <hostname> to A Record: <server-ip> |
The host name does not resolve to this server's public IP. The administrator is alerted and the command stops. |
SMTP failed. Our system is trying to fix it automatically. |
The first test failed. The mail configuration was rebuilt, and the test is run again. |
SMTP error was automatically corrected. |
The second test succeeded. |
CHECKSMTP: SMTP Server <hostname> is not working. |
All three tests failed. The administrator is alerted. |
Each run also adds a line to /var/log/go/checksmtp.log.
The command ends with status 1 even when the test succeeds. Do not use its exit status to detect errors.
When nothing is tested
The command stops without any message, and without sending a test, in these cases:
| Case | Why |
|---|---|
| An outgoing SMTP relay is configured | There is at least one entry in the SMTP relay list (/var/lib/sqlite/smtp.db), so the command assumes the relay is used. |
| The public IP of the server cannot be found | The IP lookup returned nothing. |
| No mailbox has sent mail today | There is no account to test with. In this case the command only rebuilds the mail maps with vmail. |
Examples
# Run the check
/go/checksmtp
# Test the login on port 587 yourself
curl -v --url smtp://127.0.0.1:587 --user 'user@example.com:password' --mail-from user@example.com --mail-rcpt you@example.net -T /dev/null
# Check that the host name points to this server
dig $(cat /etc/hostname) +short
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Invalid Hostname |
The server host name is not a full name such as server.example.com. |
Change it with hostname. |
Please Point ... to A Record |
The A record is missing or points to another IP. | Point the A record to the IP shown. If the record is proxied by Cloudflare, set it to DNS only. See proxy. |
| Nothing is printed, and you expect a test | A relay is configured, or no mailbox has sent mail today. | See When nothing is tested. |
CHECKSMTP: SMTP Server ... is not working. |
Postfix, Dovecot, or the SSL certificate is broken, or port 587 is blocked. | Check the firewall with checkfirewall, the certificates with mailssl, and see troubleshoot. |
| Test emails arrive at an address you do not know | The recipient is written in the script. | See Known issues. |
| No alert arrives | The administrator's email or WhatsApp settings are missing. | Check them with config and email. |
Details
What it does, in order
- Logs the run to
/var/log/go/checksmtp.log. - Reads the server host name from
/etc/hostname. If it has fewer than 2 dots, prints the message, alerts the administrator, and stops. - Gets the server's public IPv4 address. If that fails, stops.
- Looks up the host name's A record with
digand compares the last answer with the server IP. If they differ, prints the message, alerts the administrator, and stops. - If the SMTP relay list is not empty, stops.
- Chooses the mailbox that has sent the most mail today and reads its password from the mail database. If there is none, goes to the last step.
- Test 1. Logs in to port 587 of the server's public IP and sends a test email. If the reply contains
250,252, or235, stops. - If test 1 failed, runs the internal
postconfhelper andvmailto rebuild the Postfix configuration and mail maps, and printsSMTP failed.... - Test 2. Same test. If it succeeds, prints
SMTP error was automatically corrected.and stops. If not, runsinstallmailto configure Postfix and Dovecot again. - Test 3. Same test. If it succeeds, stops. If not, prints
CHECKSMTP: ... is not working.and alerts the administrator by email and WhatsApp. - Rebuilds the mail maps with
vmail.
Known issues
- Fixed recipient. Every test email goes to
gbp.uae@gmail.com, with the subjectTest. Change the address in the script to one you control. - A user's mailbox is used. The test logs in with the stored password of a real user, which is also passed to
curlon the command line and can be seen in the process list while the command runs. - Loose success check. A test counts as successful when the output of
curlcontains250,252, or235anywhere, including inside other numbers.235only means that the login worked. - A relay hides problems. With an outgoing relay configured, the command does nothing. See
smtpandbrevo. - Repairs are not reported. After a successful third test the command ends silently, and the administrator is not told that repairs were needed.
- Plain SMTP on port 587. The test does not ask for an encrypted connection, so it does not prove that the certificate is valid.
See also
| Command | Description |
|---|---|
checkimap |
Check the IMAP port and SSL certificate |
checkmail |
Check if your server provider supports mail port 25 (SMTP) |
mailssl |
Install SSL certificates for SMTP and IMAP |
installmail |
Install and configure webmail services (Postfix and Dovecot) |
vmail |
Rebuild the Postfix/Dovecot vmail maps |
smtp |
Manage the SMTP port: block, unblock, and change it |
troubleshoot |
Troubleshoot email problems in GoAdmio |