Magento 2 Laminas mail 'Invalid header value' error when email name contains German characters

Magento 2 Laminas mail 'Invalid header value' error when email name contains German characters

August 1, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento 2 Laminas mail 'Invalid header value' error when email name contains German characters

Debugging Magento 2: Solving the ‘Invalid header value’ Email Sending Issue

If you’re facing an email sending problem in your Magento 2 admin panel, where emails aren’t sent correctly due to invalid header values caused by special German or Danish characters in customer names, this guide will help you resolve the issue.

Understanding the Problem: Invalid Header Values

The error you encountered is a runtime exception thrown by Laminas HTTP Header library when it encounters an invalid header value while preparing to send an email. The specific function causing the problem is Laminas\Http\Header\HeaderValue::assertValid, which throws an Exception\InvalidArgumentException for any non-valid header values.

public static function assertValid($value)
{
    if (! self::isValid($value)) {
        throw new Exception\RuntimeException('Invalid header value');
    }
}

This validation is triggered by Laminas Mail’s Header classes during the email preparation process. Specifically, it occurs in the AbstractAddressList class when preparing the recipient list for the email.

// Quote name if it contains a comma or semicolon
if (! empty($name) && (false !== strpos($name, ',') || false !== strpos($name, ';'))) {
    $name = sprintf('"%s"', $name);
}

// MIME encode the name if not ASCII and format is encoded
if ($format === HeaderInterface::FORMAT_ENCODED && 'ASCII' !== $encoding) {
    if (! empty($name)) {
        $name = HeaderWrap::mimeEncodeValue($name, $encoding);
    }
}

if (empty($name)) {
    $emails[] = $email;
} else {
    $emails[] = sprintf('%s <%s>', $name, $email);
}

The Challenge: Replacing Special Characters

Magento provides a filter to remove accents from strings, located in Magento\Framework\Filter\RemoveAccents. However, this class is not easily accessible or customizable due to the static nature of the relevant functions and the abstract nature of the parent classes.

$this->filterManager->getFilterInstance('remove_accents')->filter($customerName);

The Solution: Customizing Laminas Mail

To resolve this issue, you’ll need to customize the Laminas Mail library used by Magento. You can do this by creating a custom wrapper class for the AbstractAddressList and replacing the problematic header value assertion.

First, create your custom address list class in the following directory:

app/code/YourCompany/Magento2 Fixes/etc/module.xml

Define your module configuration:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Magento_YourCompany_Magento2 Fixes" setup_version="1.0.0">
        <sequence>
            <module name="Magento_LaminasMail"/>
        </sequence>
    </module>
</config>

Next, create your custom AbstractAddressList in the following directory:

app/code/YourCompany/Magento2 Fixes/Laminas/Mail/AddressList

Implement your custom version of the AbstractAddressList:

namespace YourCompany\Magento2Fixes\Laminas\Mail\AddressList;

use Laminas\Mail\AddressList as OriginalAddressList;
use Laminas\Mail\Header\HeaderInterface;
use Magento\Framework\App\Config\ScopeConfigInterface;
use Magento\Framework\FilterManagerInterface;

class AddressList extends OriginalAddressList
{
    /**
     * @var ScopeConfigInterface
     */
    private $scopeConfig;

    /**
     * @var FilterManagerInterface
     */
    private $filterManager;

    public function __construct(
        array $addresses = [],
        ScopeConfigInterface $scopeConfig,
        FilterManagerInterface $filterManager
    ) {
        parent::__construct($addresses);
        $this->scopeConfig = $scopeConfig;
        $this->filterManager = $filterManager;
    }

    public function getFieldValue($format = HeaderInterface::FORMAT_RAW)
    {
        // Your custom logic here, including accent removal
        // ...

        if ($format !== HeaderInterface::FORMAT_RAW) {
            foreach ($emails as $email) {
                // Replace the invalid header value assertion with your custom rule
                // ...
            }
        }

        return implode(',' . Headers::FOLDING, $emails);
    }
}

Finally, register your custom AbstractAddressList in the following file:

app/code/YourCompany/Magento2 Fixes/etc/di.xml
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Laminas\Mail\AddressList">
        <arguments>
            <argument name="scopeConfig" xsi:type="object">Magento\Framework\App\Config\ScopeConfigInterface</argument>
            <argument name="filterManager" xsi:type="object">Magento\Framework\FilterManagerInterface</argument>
        </arguments>
    </type>
</config>

Conclusion

By following this guide, you should be able to resolve the ‘Invalid header value’ error that prevents emails from being sent when customer names contain special German or Danish characters.

Remember to test your solution thoroughly and follow best practices for Magento 2 extension development. You can find more resources on Magento 2 development at Laravel Company’s blog.

Happy coding!

Magento 2 Admin Email Customers

Our network