This documentation covers Poweradmin 4.x. Some sections are still being expanded.

Mail Configuration

This document describes how to configure email settings in Poweradmin.

Overview

Poweradmin supports sending emails for various purposes: - User registration confirmations - Password reset requests - DNS zone changes notifications - System alerts

Configuration Options

The mail settings are configured in the config/settings.php file under the mail section:

  • enabled: Enable email functionality. Default: true
  • from: Default "from" email address. Default: poweradmin@example.com
  • from_name: Default "from" name. Default: empty
  • return_path: Default "Return-Path" address for bounce handling. Default: poweradmin@example.com
  • transport: Transport method. Options: 'smtp', 'sendmail', 'php'. Default: php

SMTP Settings

SMTP settings live as flat keys under mail (they are not nested in an smtp subarray):

  • host: SMTP server hostname. Default: smtp.example.com
  • port: SMTP server port. Default: 587
  • username: SMTP authentication username. Default: empty
  • password: SMTP authentication password. Default: empty
  • encryption: Encryption method. Options: 'tls', 'ssl', empty. Default: tls
  • auth: Whether SMTP requires authentication. Default: false

Sendmail Settings

  • sendmail_path: Path to sendmail binary. Default: /usr/sbin/sendmail -bs

Example Configuration

return [
    'mail' => [
        'enabled' => true,
        'from' => 'dns@example.com',
        'from_name' => 'DNS Administrator',
        'return_path' => 'dns@example.com',
        'transport' => 'smtp',
        // SMTP settings (flat, not nested under 'smtp')
        'host' => 'smtp.example.com',
        'port' => 587,
        'username' => 'smtp_user',
        'password' => 'smtp_password',
        'encryption' => 'tls',  // 'tls', 'ssl', or ''
        'auth' => true,
    ],
];

Troubleshooting

Email Debug Logging

To troubleshoot email delivery without touching SMTP, set transport to logger. Outgoing messages are then written to the PHP error log and Poweradmin's application log instead of being sent over the network - useful for inspecting password reset content during development:

'mail' => [
    'transport' => 'logger',
],

For server-side errors during real SMTP delivery, raise the global log level under logging.level (see Logging) and check your web server error log or PHP error log for output from MailService.

TLS/STARTTLS Issues (Fixed in v4.1.0)

Problem: Email sending fails with TLS/STARTTLS errors in versions prior to v4.1.0.

Solution: Upgrade to v4.1.0 or later, which includes proper TLS/STARTTLS connection handling.

If you're experiencing issues with TLS encryption:

  1. Verify encryption setting:
'encryption' => 'tls',  // For STARTTLS on port 587
// or
'encryption' => 'ssl',  // For SMTPS on port 465
// or
'encryption' => null,   // For unencrypted connections (not recommended)
  1. Common port and encryption combinations:
  2. Port 587 with 'encryption' => 'tls' (STARTTLS) - Most common
  3. Port 465 with 'encryption' => 'ssl' (SMTPS) - Older systems
  4. Port 25 with 'encryption' => null - Not recommended

Email Rejection Due to Long Lines (Fixed in v4.0.3)

Problem: Some SMTP servers reject emails with lines longer than 998 characters (RFC 5322 limit).

Solution: Upgrade to v4.0.3 or later, which implements proper line wrapping for email content.

This particularly affects: - Long DKIM signatures - Extensive HTML email templates - Large text blocks in password reset emails

Common SMTP Authentication Issues

Problem: SMTP authentication fails even with correct credentials.

Troubleshooting steps:

  1. Verify credentials: Double-check username and password
  2. Test SMTP connectivity:
telnet smtp.example.com 587
  1. Check firewall rules: Ensure outbound SMTP ports are open
  2. Review server logs: Raise logging.level to debug (see Logging) for detailed MailService output
  3. Try alternative ports: Test port 465 (SSL) or 25 if 587 fails

Email Not Being Delivered

Common causes:

  1. Incorrect "from" address: Some SMTP servers require matching authentication username
  2. SPF/DKIM issues: Ensure your server's IP is authorized to send from the domain
  3. Blacklisted IP: Check if your server's IP is on spam blacklists
  4. Rate limiting: SMTP server may be throttling connections

Debugging steps:

  1. Raise logging.level to debug and check the application log (see Logging)
  2. Check mail server logs
  3. Verify email appears in sent items (if using external SMTP)
  4. Test with a simple mail client using same credentials

Version History

v4.1.0

  • Fixed: TLS/STARTTLS connection handling (issue #861)
  • Properly handles different encryption modes
  • Resolves connection failures with certain SMTP servers

v4.0.3

  • Added: Comprehensive debug and operational logging
  • Detailed SMTP transaction logging
  • Authentication process visibility
  • Error message improvements
  • Fixed: Email rejection due to long lines (issue #798)
  • Implements RFC 5322 compliant line wrapping
  • Prevents SMTP server rejections

v4.0.2

  • Fixed: Invalid SMTP headers causing server rejections (issue #774)
  • Removed non-standard headers
  • Improved RFC compliance
  • Fixed: SMTP authentication and response parsing issues
  • Better error handling
  • More reliable authentication

v4.0.0

  • New Twig-based email template system
  • Support for custom email templates
  • Dark mode email templates
  • Plain text body support
  • Template preview functionality
  • Multiple transport options (SMTP, sendmail, PHP mail)