Contents show

Overview of the Problem

ColdFusion’s mail server Configuration allows your application to send email via an SMTP relay (e.g., Microsoft 365, Google Workspace, SES, or an on-prem Exchange/SMTP server). When this setup misbehaves, you might see emails stuck in the spool, Authentication errors, timeouts, TLS handshake failures, or messages that never arrive. These issues typically arise from misconfiguration (wrong host, port, SSL/TLS settings), network blocks (firewalls, cloud provider port restrictions), Authentication policy changes (modern auth, disabled SMTP AUTH), or certificate trust problems in the JVM that ColdFusion uses.

A clear understanding of how ColdFusion hands off email to an SMTP server—and how to read its logs and spool—makes Troubleshooting systematic and fast.

Symptoms You Might See

Emails stay in the ColdFusion mail spool (spool or undeliverable directories).
mail.log shows 4xx/5xx SMTP responses or JavaMail exceptions.
javax.mail.AuthenticationFailedException or 535/530 SMTP errors.
javax.net.ssl.SSLHandshakeException: PKIX path building failed.
Timeouts when connecting to smtp.example.com:587/465/25.
Messages “sent” from ColdFusion but never received (blocked, quarantined, or bounced).

Possible Causes

Network and Port Connectivity

Outbound port 25 blocked by ISP/cloud provider (common in AWS/GCP/Azure and some data centers).
Corporate firewall/proxy blocking 465/587 or STARTTLS negotiation.
DNS resolution fails or resolves to the wrong IP (split-brain DNS).

Authentication & Authorization

Wrong username/password, or the SMTP account lacks permission to relay.
SMTP AUTH disabled on the provider (e.g., Microsoft 365 tenant setting).
Conditional access or MFA preventing basic SMTP authentication.
Rate limits or sender throttles reached; relay IP not allow-listed.

TLS/SSL and Certificates

Using the wrong Security mode: implicit SSL on 465 vs STARTTLS on 587.
Server certificate not trusted by the ColdFusion JVM truststore.
TLS version/cipher mismatch; middleboxes doing TLS inspection.

DNS and MX/Domains

Misconfigured DNS for target SMTP host.
Sender domain without proper SPF/DKIM/DMARC causing rejections.
HELO/EHLO name reverse DNS mismatch causing spam blocks.

Application-Level and Configuration Issues

ColdFusion Administrator mail settings incorrect or overridden by attributes.
Spooler disabled or spool interval very high.
Anti-virus locking or quarantining files in the spool folder.
Using unsupported auth schemes (e.g., OAuth 2.0) in older ColdFusion versions.

Provider Policies and Spam Controls

Provider requiring modern auth or a special relay connector (Office 365).
Blacklisted IP/domain, content filters, or attachment restrictions.

Step-by-Step Troubleshooting Guide

1. Confirm Mail Server settings in ColdFusion Administrator

Navigate: ColdFusion Administrator > Server settings > Mail.
Verify:
- Server: smtp.example.com
- Port: 587 (STARTTLS) or 465 (implicit SSL). Avoid port 25 unless allowed.
- “Use SMTP Authentication”: enabled if required; set username/password.
- “Use SSL/TLS”: match your provider guidance. For 587, ensure STARTTLS is enabled; for 465, implicit SSL.
- Connection timeout: sensible value (e.g., 30 seconds).
- Spool Enable: enabled; Spool Interval: 1–5 seconds for testing.
If you specify server/port/auth in , note these override Admin settings.

Tip: Test with the provider’s official documentation for SMTP client settings.

2. Check the ColdFusion mail Spool Directories

Default paths (vary by version/install):
- [cfusion]/mail/spool
- [cfusion]/mail/undelivr
- [cfusion]/mail/outbox (temporary)
If files accumulate in spool: not yet processed; check if the mail service is running.
If files move to undelivr: delivery failed; review mail.log for reasons.

3. Review the Logs

ColdFusion logs:
- logs/mail.log — primary for SMTP send attempts.
- logs/exception.log — Java exceptions.
- application logs for cfcatch output, if any.

Example entries:

“INFO”,”Mail”,”Attempting to send mail to: user@domain.com via smtp.office365.com:587″
“ERROR”,”Mail”,”AuthenticationFailedException: 535 5.7.3 Authentication unsuccessful”
“ERROR”,”Mail”,”javax.net.ssl.SSLHandshakeException: PKIX path building failed: unable to find valid certification path to requested target”
“ERROR”,”Mail”,”Could not connect to SMTP host: smtp.gmail.com, port: 587, response: -1″

Use these to pinpoint whether it’s auth, TLS, or connectivity.

4. Test Network Connectivity and SMTP Handshake Outside ColdFusion

From the ColdFusion server:
- DNS:
  - nslookup smtp.office365.com
  - dig smtp.office365.com
- Port tests:
  - PowerShell (Windows): Test-NetConnection smtp.office365.com -Port 587
  - Linux: nc -vz smtp.office365.com 587
- STARTTLS handshake:
  - openssl s_client -starttls smtp -connect smtp.office365.com:587 -crlf
    - After “CONNECTED”, type: EHLO yourhost.example.com
- Implicit TLS (465):
  - openssl s_client -connect smtp.gmail.com:465 -crlf

If you cannot connect, fix firewall/network/DNS first.

5. Validate Credentials and Policy

Try authenticating via a desktop SMTP client (e.g., Thunderbird) using the same host/port/Security and credentials from the same network.
For Microsoft 365:
- Ensure SMTP AUTH is enabled for the mailbox.
- Consider an app password if MFA is enforced.
- Alternatively, configure a relay connector allowing your server’s IP.
For Google Workspace:
- Use smtp.gmail.com with OAuth2 or app passwords if 2FA is enabled.
- Basic auth may be blocked unless allowed by policy.

Typical errors:

535 5.7.3 Authentication unsuccessful — wrong creds or policy block.
530 5.7.57 Client not authenticated — authentication or relay requirement.

6. Verify TLS and Certificates (PKIX Issues)

If mail.log shows SSLHandshakeException or PKIX path building failed:

The SMTP server’s certificate chain might not be trusted by the ColdFusion JVM.
Export the server certificate chain and import into the JVM truststore used by ColdFusion.

Export and import example:

Get server cert chain

openssl s_client -starttls smtp -connect smtp.example.com:587 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > smtp-example-com.pem

Identify the ColdFusion JVM cacerts path:

Common locations:

[cfusion]/jre/lib/security/cacerts (CF2021+/CF2018+)

[cfusion]/runtime/jre/lib/security/cacerts (older)

Confirm with: {cf_home}/jre/bin/java -XshowSettings:properties -version | find “java.home”

Import certificate (default storepass: changeit)

{cf_home}/jre/bin/keytool -importcert -keystore {cf_home}/jre/lib/security/cacerts -storepass changeit -alias smtp-example-com -file smtp-example-com.pem

Restart ColdFusion after import. If a corporate proxy inspects TLS, import the proxy’s root CA.

7. Check DNS and Sender Reputation

Ensure your outbound hostname resolves correctly and has PTR (reverse DNS).
Validate SPF, DKIM, and DMARC for your sending domain to reduce spam filtering.
Use tools like mxtoolbox.com to check blocklists and DNS health.

8. Test with a Minimal Template

Use the simplest possible code to reduce variables:

<cfmail
to=”me@recipient.example”
from=”noreply@yourdomain.example”
subject=”SMTP Test”
server=”smtp.office365.com”
port=”587″
username=”smtpuser@yourtenant.onmicrosoft.com”
password=”app-or-smtp-password”
useTLS=”true” type=”text”>
Test message at #now()# from ColdFusion.

Note:

server/port/credentials attributes override Admin settings.
For implicit SSL on 465, use useSSL=”true” instead of useTLS=”true” (depending on CF version; consult your version’s documentation).

9. Bypass ColdFusion Temporarily to Isolate

Use curl’s SMTP mode or swaks (Swiss Army Knife for SMTP) to send a test mail from the same machine:

With swaks (install via package manager)

swaks –to you@domain.com –from noreply@yourdomain.example \
–server smtp.office365.com –port 587 –auth LOGIN \
–auth-user ‘smtpuser@yourtenant.onmicrosoft.com’ \
–auth-password ‘****‘ –tls –header “Subject: CF SMTP test”

If swaks works but CF doesn’t, focus on CF configuration and JVM truststore. If both fail, it’s network/policy/credentials.

10. Consider Environment-Specific Blocks

Cloud providers often block port 25; use 587 or a dedicated relay (SES/SendGrid).
Corporate AV/EDR can block outbound SMTP; allow-list the CF service or host.
Load balancers/proxies might not pass SMTP cleanly; route directly where possible.

11. Provider-Specific Notes

Microsoft 365:
- smtp.office365.com:587 STARTTLS with authenticated user, or configure an IP-based relay connector (port 25) if permitted.
- Ensure “Authenticated SMTP” is enabled for the mailbox.
Google Workspace:
- smtp.gmail.com:587 STARTTLS with user credentials and app password if using 2FA.
- Consider using a relay service with IP allow-listing.
Transactional services (SES, SendGrid, Mailgun):
- Follow their host/port/TLS and auth guidance; some require username=API key.

Quick reference: Causes and Solutions

Wrong port or TLS mode
- Solution: Use 587 with STARTTLS (useTLS=true) or 465 with implicit SSL (useSSL=true) per provider docs.
Authentication failed (535/530)
- Solution: Verify username/password, enable SMTP AUTH on the mailbox/tenant, use app passwords or relay connector.
Timeout or cannot connect
- Solution: Open outbound firewall; avoid port 25 if blocked; confirm DNS resolution.
SSLHandshakeException / PKIX path failed
- Solution: Import SMTP server/proxy certificate chain into ColdFusion JVM truststore; restart CF.
Emails stuck in spool/undelivr
- Solution: Check mail.log; fix root cause; ensure spooler enabled and AV not locking spool directory.
Messages sent but not received
- Solution: Check spam/junk, quarantine, and bounce reports; configure SPF/DKIM/DMARC; review content/attachments.

Common mistakes and How to Avoid Them

Mixing STARTTLS and implicit SSL settings
- Avoid by matching exact provider requirements: 587 + STARTTLS vs 465 + SSL.
Overriding Admin settings unintentionally
- attributes (server, port, username, password, TLS/SSL) override Admin values. Keep consistent or remove overrides during testing.
Ignoring the ColdFusion JVM truststore
- TLS failures require importing certs into the JVM ColdFusion runs on, not the OS store.
Testing from a different machine/network
- Always test connectivity from the ColdFusion server itself.
Using port 25 without verifying provider policy
- Many providers block 25; switch to 587 or a relay service.
Not checking mail.log
- mail.log often contains the exact SMTP/JavaMail error. Start there.

Prevention Tips / Best practices

Use a dedicated, documented SMTP relay that supports 587 STARTTLS or 465 SSL.
Keep ColdFusion and its bundled JVM updated to get modern TLS/cipher support.
Maintain a clean JVM truststore:
- Track imported certificates and expire/renew on schedule.
Configure SPF, DKIM, and DMARC for your sending domains.
Monitor logs proactively and alert on spikes in mail errors.
Store SMTP credentials securely (e.g., environment variables, secrets manager).
Avoid hardcoding mail settings in code; centralize in Admin where possible.
Rate-limit and queue emails; handle transient 4xx errors with retries.
Coordinate with security/network teams to allow outbound SMTP and TLS inspection exceptions if needed.
Use provider health dashboards (Office 365 Service Health, SES metrics) for quick visibility.

Diagnostic Snippets and Examples

Check SMTP with telnet-style commands via OpenSSL:

openssl s_client -starttls smtp -connect smtp.office365.com:587 -crlf
EHLO yourhost.example.com
AUTH LOGIN

then base64-encode username and password when prompted, or exit if just testing handshake.

Example mail.log snippet for successful send:

“INFO”,”Mail”,”Attempting to send mail to: user@domain.com via smtp.office365.com:587″
“INFO”,”Mail”,”Mail sent successfully to user@domain.com in 1123ms”

Example minimal ColdFusion code:

<cfmail to=”you@domain.com”
from=”noreply@yourdomain.example”
subject=”ColdFusion SMTP Connectivity OK”
server=”smtp.gmail.com”
port=”587″
username=”smtpuser@yourdomain.example”
password=”****”
useTLS=”true”>
The mail subsystem appears to be working.

Key Takeaways

Start with mail.log and the spool folders to identify the failure type.
Verify network connectivity and TLS handshake from the ColdFusion server first.
Align port and security: 587 with STARTTLS vs 465 with implicit SSL.
Fix authentication by matching provider policies (SMTP AUTH enabled, app passwords, relay connectors).
Resolve TLS trust by importing the server certificate chain into the ColdFusion JVM truststore.
Stabilize long-term with proper DNS (SPF/DKIM/DMARC), monitoring, and consistent Configuration management.

FAQ

How do I see why emails are stuck in the ColdFusion mail spool?

Check logs/mail.log for each send attempt. Files lingering in “spool” mean pending; files in “undelivr” indicate failed sends with reasons logged (auth errors, TLS failures, timeouts). Ensure the mail spooler is enabled and the interval is small during testing.

How do I fix “PKIX path building failed” when sending mail?

Import the SMTP server’s certificate chain into the ColdFusion JVM truststore (cacerts), not the OS store. Use openssl s_client to export the chain and keytool to import. Restart ColdFusion afterward and retest.

Can I use Microsoft 365/Google Workspace with ColdFusion?

Yes. Use smtp.office365.com:587 with STARTTLS (SMTP AUTH enabled) for Microsoft 365 or smtp.gmail.com:587 with STARTTLS for Google. For tenants enforcing MFA or blocking basic auth, use app passwords or set up a relay connector that authenticates by IP.

Why do emails “send” but never arrive?

They might be quarantined or filtered as spam. Check recipient quarantine, review bounce/NDR messages, and configure SPF/DKIM/DMARC. Also check content/attachments and ensure your sending IP/domain reputation is good.

Does override ColdFusion Administrator mail settings?

Yes, attributes like server, port, username, password, and TLS/SSL on override the Administrator configuration for that send. Keep settings consistent and remove overrides when diagnosing Admin-level configuration.