Troubleshooting OpenCart 4.x SMTP Mail: Resolving Connection Refused & SSL Errors
Setting up SMTP mail in OpenCart, especially with self-hosted VPS mail servers, can often be a frustrating experience. The OpenCart community forum frequently sees discussions around "Connection refused," "Connection timed out," and "SSL wrong version number" errors. This insight article analyzes a recent forum topic where a user, mr_webshop_manager, struggled with SMTP configuration in OpenCart v4.x, ultimately finding a workaround. We'll delve into the common pitfalls and provide actionable troubleshooting steps.
Common OpenCart 4.x SMTP Mail Challenges
The discussion highlights several recurring themes when OpenCart struggles to connect to an SMTP server:
- SSL/TLS Protocol Mismatches: The initial error encountered by mr_webshop_manager,
error:0A00010B:SSL routines::wrong version number, is a classic sign that the OpenCart client (via PHP'sfsockopen()) and the mail server cannot agree on a common SSL/TLS protocol version. - Incorrect Port & Prefix Combinations: Using the wrong port for a given encryption type (e.g., SSL on port 25) or incorrect prefix (
ssl://,tls://, or none) is a frequent misconfiguration. - Server-Side Firewall vs. Mail Server Configuration: An open firewall port (as shown by
firewall-cmd) does not automatically mean the mail server is listening on that port or configured to accept connections from the OpenCart application. - Connection Refused/Timed Out: These errors (
Connection refused (111),Connection timed out (110)) typically indicate that while the OpenCart application might be able to reach the server's IP, the mail server itself is not responding to the connection attempt on the specified port. - PHP
fsockopen()Behavior: Differences in how PHP's underlying network functions interact with mail servers compared to dedicated mail clients (like an iPhone's mail app or a desktop client) can lead to unique issues.
Detailed Troubleshooting Steps for OpenCart 4.x SMTP
Based on the community discussion and common best practices, here’s a guide to diagnosing and resolving your OpenCart 4.x SMTP issues:
1. Verify Mail Server Configuration and Listening Ports
Do not rely solely on firewall rules. You need to confirm your mail server (e.g., Postfix, Exim, Sendmail) is actively listening on the ports and protocols you intend to use. For example, if you plan to use SSL on port 465, ensure the mail server is configured for it. The forum user ADD Creative rightly pointed out that "That just your firewall, doesn't mean your mail server is listening."
You can use commands like netstat -tulnp | grep -E '465|587|25' on your VPS to see if services are listening on these ports.
2. Correct Port and Encryption Protocol Mapping
Ensure your OpenCart mail settings align with your mail server's configuration:
- SSL (Secure Sockets Layer): Typically uses Port 465 with the
ssl://prefix in the hostname (e.g.,ssl://mail.mysite.nl). This is often deprecated in favor of TLS. - TLS (Transport Layer Security): Typically uses Port 587 with the
tls://prefix in the hostname (e.g.,tls://mail.mysite.nl). This is the modern, recommended approach for authenticated SMTP. - Unencrypted/Legacy: Uses Port 25 with no prefix. This port is often blocked by ISPs or hosting providers due to spam concerns and should generally be avoided for outgoing mail. mr_webshop_manager initially tried
ssl://mail.mysite.nl:25, which is an incorrect combination.
3. Address SSL/TLS Version Compatibility Issues
The error error:0A00010B:SSL routines::wrong version number indicates a mismatch. This is usually a server-side issue. Your mail server might be configured to use older or newer TLS versions that OpenCart's PHP environment doesn't support by default, or vice versa. You might need to:
- Update PHP's OpenSSL libraries on your server.
- Configure your mail server to support a wider range of TLS protocols (e.g., TLSv1.2, TLSv1.3) that are compatible with your PHP version.
- Test your server's SSL/TLS capabilities with
openssl s_client -connect mail.mysite.nl:465 -tls1_2or-tls1_3to diagnose.
4. Increase Connection Timeout
When encountering "Connection timed out" errors, increasing the connection timeout can sometimes help, especially if the server is slow to respond or there's network latency. ADD Creative suggested this, advising to "Try making your timeout 30 or 60."
While the exact line might vary, you'd typically look for the fsockopen() call within system/library/mail/smtp.php and modify its timeout parameter. The default is often 5 seconds.
2026-05-07 19:46:45 - PHP Warning: fsockopen(): Unable to connect to mailserver:25 (Connection timed out) in /var/www/www.mysite.nl/www/public/system/library/mail/smtp.php on line 143
2026-05-07 19:46:45 - Error: Error: Connection timed out (110)File: /var/www/www.mysite.nl/www/public/system/library/mail/smtp.php
Look for a line similar to:
$this->socket = fsockopen($hostname, $port, $errno, $errstr, $this->timeout);And ensure $this->timeout is set to a higher value (e.g., 30 or 60 seconds) in your OpenCart administration settings or by modifying the class if necessary (though modifying core files is generally discouraged).
5. Test with External SMTP Delivery Services
As mr_webshop_manager discovered, sometimes the most efficient solution is to offload mail delivery to a dedicated third-party SMTP service. "After filling in some details and adapting the dns record for the domain (adding some CNAMES forwarding to their servers I guess) it worked in a split second." Services like SendGrid, Mailgun, or even a properly configured Gmail SMTP can be more reliable and easier to set up, circumventing complex self-hosted mail server issues.
Conclusion
Troubleshooting OpenCart SMTP issues, particularly with self-managed mail servers, requires a systematic approach, checking both OpenCart's configuration and the mail server's setup. While resolving server-side SSL/TLS and port listening issues is ideal, leveraging robust third-party SMTP services often provides a quick and reliable solution, saving valuable time and ensuring critical store communications are delivered.