What this module does #
Plenty of things on the server notify you by email: a certificate about to expire, a disk filling up, the report from a nightly job. But a freshly installed server doesn't know how to send that mail — or it tries to deliver it directly and ends up in the spam folder, if it isn't rejected outright.
The smtp module solves that by configuring the host's outbound mail against a smarthost (a relay that is actually authorized to deliver: Amazon SES, a corporate mail server, your provider…). It adjusts postfix so it forwards all system mail to that smarthost, stores the password securely, rewrites the sender so it's a valid one, and lets you test the send to confirm it arrives — reporting the actual error if something fails.
Have your smarthost details ready: host, port (usually 587), and the credentials if it requires authentication. The password is not passed on the command line: it's read from stdin or from the secrets store, so it never lands in your history.
Common tasks #
Pick what you want to do. Each recipe comes with the command already written — just swap in your own smarthost and sender, and hit Copy.
1
Configure the mail relay
Point the server at your smarthost so mail actually goes out.
Connect to your server over SSH as the ubuntu user.
Run the command with your smarthost details. The password is prompted via stdin, so it never lands in your history:
$ sudo imaxe smtp configure \
--host email-smtp.eu-west-1.amazonaws.com \
--user AKIAIOSFODNN7EXAMPLE \
--from [email protected]If your smarthost doesn't require authentication, omit --user. For a different port or TLS mode, add --port or --no-tls.
[email protected]. Continue with the Send a test email recipe.2
Send a test email
Confirm a message goes out and arrives before you rely on alerts.
Send a test email to an address where you can check it:
$ sudo imaxe smtp test --to [email protected]If you omit --to, it's sent to the configured sender. Check your inbox (and the spam folder) to confirm delivery.
3
View mail status
Check at a glance whether the relay is configured and active.
A summary of the relay, the smarthost, the sender and the MTA status:
$ sudo imaxe smtp statusNeed it for a script or a dashboard? Add --json for machine-readable output:
$ sudo imaxe smtp status --json4
View the effective configuration
Check the active settings without exposing the password.
Shows the host, port, user, sender and TLS mode actually in use (the password is never printed):
$ sudo imaxe smtp show5
Remove the relay
Disable forwarding and return postfix to its previous state.
Disable the outbound mail relay and restore the base postfix configuration:
$ sudo imaxe smtp removeconfigure.The most common cause is that the sender isn't verified on the smarthost (SES requires verifying the domain or the --from address), or that the credentials are wrong. Run imaxe smtp test: it returns the actual MTA error so you know exactly what to adjust.
Synopsis #
imaxe smtp <subcomando> [--host HOST] [--from CORREO] [flags]All subcommands require root privileges (use sudo) because they touch the postfix configuration, write to /etc/imaxe/ and reload system services. The smarthost password is never passed as a flag: it's read from stdin or from the secrets store. Add --json to status or show for machine-readable output suitable for scripting.
Subcommands #
| Subcommand | What it does | Relevant flags |
|---|---|---|
| configure | Configures the outbound mail relay against a smarthost. The password is read from secrets/stdin. | --host, --port, --user, --from, --tls / --no-tls |
| test | Sends a test email and reports the actual MTA error if it fails. | --to |
| status | Status: relay configured, smarthost, sender and MTA active. | --json |
| show | Shows the effective configuration, without exposing the password. | --json |
| remove | Disables the relay and restores postfix. | — |
Arguments and flags #
| Flag | Type | Default | Description |
|---|---|---|---|
| --host req. | string | — | SMTP smarthost to forward mail to (e.g. email-smtp.eu-west-1.amazonaws.com). Required for configure. |
| --port | int | 587 | SMTP port of the smarthost. |
| --user | string | — | SMTP user for authentication. If omitted, the relay is configured without authentication. |
| --from | string | — | Rewrites the sender of all messages (sender_canonical). Useful for using an address verified on the smarthost. |
| --tls / --no-tls | bool | --tls | Forces TLS on the connection to the smarthost (the default). --no-tls disables it. |
| --to | string | remitente | In test: recipient of the test email. Defaults to the configured sender. |
| --json | bool | false | In status/show, emits the result as JSON on stdout. |
There is no --password option. The credential is read from stdin during configure or from the secrets store (password_secret, smtp by default), so it never appears in your history or in the process table.
Files and paths #
| Path | Contents |
|---|---|
| /etc/imaxe/smtp.yml | Module configuration: host, port, TLS, user, sender and a reference to the password secret. |
| /etc/postfix/main.cf | Postfix configuration that the module adjusts for forwarding (relayhost, sender canonical…). |
| /var/log/mail.log | Postfix log with every delivery attempt and the reason for rejections. |
Example smtp.yml:
enabled: true
host: email-smtp.eu-west-1.amazonaws.com
port: 587
tls: true
username: AKIAIOSFODNN7EXAMPLE
from: [email protected]
password_secret: smtpExit codes and logs #
Each run returns a code you can check with echo $? — handy for chaining in scripts:
test, the email was accepted for delivery.Follow the mail log live while debugging a send:
$ sudo tail -f /var/log/mail.log
$ sudo imaxe smtp test --to [email protected]Troubleshooting #
| Symptom | Likely cause | Fix |
|---|---|---|
| Returns AUTH (code 4) | Wrong smarthost user or password. | Check --user and run configure again, re-entering the password via stdin. |
| Returns SEND (code 5), sender rejected | The --from address is not verified on the smarthost (typical with SES). | Verify the domain or the address with the provider and retry the test. |
| Returns CONFIG (code 3) | The relay isn't configured on this host yet. | Run imaxe smtp configure with your smarthost details. |
| Mail goes out but lands in spam | SPF/DKIM alignment is missing on the sender's domain. | Set up the mail provider's records for the --from domain. |
Stuck with the Mail module?
Write to us with the output of «imaxe <module> status --json» and we'll get back to you fast.