Troubleshooting

Common Issues

Emails Not Being Sent

Symptom: send() returns true but no email is received.

Solutions:

Check spam/junk folder — emails from WordPress often land in spam
Install an SMTP plugin — WordPress's default mail() function is unreliable
Verify SMTP settings — check your SMTP plugin's connection test feature
Check email logs — use Post SMTP or WP Mail SMTP's logging feature

// Debug: verify wp_mail is working
$result = wp_mail('[email protected]', 'Test', 'Testing wp_mail directly');
var_dump($result); // Should be true

`send()` Returns `false`

Symptom: The send() method returns false.

Solutions:

Check recipients — ensure to() was called with valid email addresses
Check wp_mail errors — hook into wp_mail_failed:

add_action('wp_mail_failed', function (WP_Error $error) {
    error_log('wp_mail failed: ' . $error->get_error_message());
});

Verify PHP mail configuration — check php.ini for sendmail_path

HTML Content Shows as Plain Text

Symptom: Email recipients see raw HTML tags instead of formatted content.

Solutions:

The Content-Type: text/html; charset=UTF-8 header is automatically set when using html(), view(), or component body methods. If it's still showing as plain text:

Check for conflicting plugins — some plugins override the content type
Verify headers in build output:

$built = $mail->build();
var_dump($built['headers']); // Should contain Content-Type header

View Templates Not Rendering

Symptom: view() returns empty content.

Solutions:

Check the template path:

$mail->templatePath('/absolute/path/to/templates');
// Template file should be at: /absolute/path/to/templates/{name}.php

Verify the file exists:

$templateFile = '/path/to/templates/my-template.php';
var_dump(file_exists($templateFile)); // Should be true

Check for PHP errors in the template — syntax errors will cause ob_get_clean() to return empty

MailManager Not Resolving from Container

Symptom: $app->make(MailManager::class) throws an error.

Solutions:

Register the ServiceProvider:

$app->register(new MailServiceProvider());

Ensure registration happens before resolution — register in plugin bootstrap, not in a hook that fires later

Attachments Not Included

Symptom: Email sends successfully but attachments are missing.

Solutions:

Use absolute paths:

// Good: Absolute path
$mail->attach('/var/www/html/wp-content/uploads/invoice.pdf');

// Bad: Relative path — may not resolve correctly
$mail->attach('uploads/invoice.pdf');

Verify file exists:

$path = '/path/to/file.pdf';
if (file_exists($path)) {
    $mail->attach($path);
}

Check file permissions — WordPress process needs read access

From Address Being Overridden

Symptom: The from address set via from() is ignored.

Solutions:

Some SMTP plugins force the from address. Check:

Your SMTP plugin's "Force From Email" setting
WordPress filters on wp_mail_from and wp_mail_from_name

// Debug: check what filters are active
var_dump(has_filter('wp_mail_from'));
var_dump(has_filter('wp_mail_from_name'));

Getting Help

Security

WPZylos MCP