MODX sends mail with PHPMailer, but by default in PHP mail() mode — and on most hosts there is no working mail server behind that function. Switching to SMTP is done entirely in System Settings, with no extra packages. The one trap is that the encryption setting has a different name in MODX 2 and MODX 3.
| Setting | Value |
|---|---|
| SMTP host | smtp.postwing.app |
| Port | 587 |
| Encryption | STARTTLS (the connection is upgraded to TLS before login) |
| Username | The login of an SMTP token for your domain |
| Password | The password of that token — shown once, when the token is created |
Open System Settings (the gear menu in MODX 3, System → System Settings in Revolution 2.x), pick the core namespace and filter by the Mail area:
| Setting | Value |
|---|---|
mail_use_smtp | Yes |
mail_smtp_hosts | smtp.postwing.app |
mail_smtp_port | 587 |
mail_smtp_secure (MODX 3)mail_smtp_prefix (MODX 2.x) | tls |
mail_smtp_auth | Yes |
mail_smtp_user | The login of an SMTP token for your domain |
mail_smtp_pass | That token's password |
mail_smtp_helo | Your site's host name, e.g. your-domain.com |
emailsender | noreply@your-domain.com — on your verified domain |
mail_smtp_secure; Revolution 2.x reads mail_smtp_prefix. Use tls with port 587 or ssl with port 465 — any other pairing fails the handshake. emailsender is the From address MODX uses for its own messages, such as password resets. Save, then clear the site cache: system settings are cached, and the old mailer keeps running until you do.
The most common mistake in MODX forms is putting the visitor's address in emailFrom. Your DKIM signature and SPF record do not cover someone else's domain, so such a message fails DMARC. Do it this way:
[[!FormIt?
&hooks=`email,redirect`
&emailTpl=`ContactEmailTpl`
&emailTo=`sales@your-domain.com`
&emailFrom=`noreply@your-domain.com`
&emailFromName=`Acme website`
&emailReplyTo=`[[+email]]`
&emailSubject=`New enquiry from the website`
&redirectTo=`5`
&validate=`name:required,email:email:required,message:required`
]] Submit your contact form, or request a password reset from the manager login screen — both go through the configured mailer. Errors land in Reports → Error Log; for more detail, temporarily raise log_level to debug.
| Symptom | Cause and fix |
|---|---|
| Settings saved, nothing changed | The site cache was not cleared. |
| Port 465 fails on MODX 3 | mail_smtp_prefix was set on MODX 3. Use mail_smtp_secure. |
SMTP connect() failed | Wrong encryption for the port, or a blocked outbound port — try 8587 with tls. |
Could not authenticate | Wrong token login or password, or mail_smtp_auth is off. |
| Form submits, no email | emailFrom holds the visitor's address. Move it to emailReplyTo. |
| Mail goes to spam | emailsender or emailFrom is not on your verified domain. |
In System Settings — the gear menu in MODX 3, System → System Settings in 2.x. Filter by the core namespace and the Mail area, set mail_use_smtp to Yes and fill in mail_smtp_hosts, mail_smtp_port, mail_smtp_auth, mail_smtp_user and mail_smtp_pass, plus the encryption setting. Clear the site cache afterwards.
It depends on the version. MODX Revolution 2.x calls the encryption setting mail_smtp_prefix; MODX 3 renamed it to mail_smtp_secure. Both take the same values: tls for STARTTLS on port 587, ssl for implicit TLS on port 465. On MODX 3, mail_smtp_prefix is simply not read — which is why a 2.x guide followed on MODX 3 fails on port 465.
With mail_use_smtp off, MODX sends through PHP's mail(), and most hosts have no working mail server behind it. Turn SMTP on. If it already is, check that mail_smtp_auth is Yes too — without it the token's login and password are never sent.
Check emailFrom. If it is filled with the visitor's own address from the form, the message fails DMARC, because your DKIM and SPF say nothing about someone else's domain. Keep your own address in emailFrom and pass the visitor's in emailReplyTo.
No. Messages sent through the relay are DKIM-signed with the key published on your verified domain. Signing them again in MODX adds nothing and is one more thing to keep in sync when the key rotates.
In the error log: Reports → Error Log (under the gear menu in MODX 3). For more detail, temporarily raise the log_level system setting to debug and send again.