Showing results for 
Search instead for 
Did you mean: 

Backward-incompatible Changes in the Mail Library for Magento 2.3.3

Adobe Team

This post describes changes made to the Mail library in Magento 2.3.3 and explains the actions that merchants and extension developers need to take to ensure that extensions that use Mail library compatibility with these changes. 


Backward-incompatible Changes

The Magento\Email\Model\Transport class has been changed as follows:  


  • The type of the $message constructor parameter has been changed from Magento\Framework\Mail\MessageInterface to Magento\Framework\Mail\EmailMessageInterface 
  • The return type of the getMessage method has been changed from Magento\Framework\Mail\MessageInterface to Magento\Framework\Mail\EmailMessageInterface 


Recommendations for Merchants 

Merchants should apply the Mail library patch (available from Magento Tech Resources) as soon as possible, especially if their deployments include extensions or customizations that use the Mail library. 


This patch fixes the type of the constructor parameter, getMessage method return value and makes EmailMessageInterface extend MailMessageInterface. These changes will be included in Magento 2.3.4.


Recommendations for Extension Developers

Extension developers should both advise the merchants who use their extensions to apply the patch as well as update their extensions to be compatible with Magento 2.3.3 and 2.3.3 with the patch.


Extension developers should update their extensions to ensure compatibility with Magento 2.3.2, 2.3.3, and 2.3.4 (not yet released) by applying the following changes: 


Usage scenarioA custom class inherits from

Magento\Framework\Mail\Template\TransportBuilder  and relies on the protected $message property. 

Solution: Useinstanceof  to determinewhich class is sending $messagebefore using this property. 


if ($message instanceof \Magento\Framework\Mail\MessageInterface) {
    // Keep existing behavior here 
} else { 
    // Introduce new behavior here 


Usage scenario: The use of MessageInterface in a method signature. 

Solution: Loosen typing by removing  MessageInterface from the method signature and instead use instanceof check. 


Usage scenario:  Any plugin for Magento\Framework\Mail\TransportInterface  that uses$subject->getMessage(). 

Solution: Useinstanceof to determinewhich class is sending $messagebefore using this property.


Usage scenario: Any client code that usesMagento\Framework\Mail\TransportInterface::getMessage() will now get an instance of EmailMessageInterface instead of MessageInterface. 

Solution: Useinstanceof to determinewhich class is sending $messagebefore using this property. 


Usage scenario: Instantiation of Magento\Email\Model\Transport using factory now requires message argument to implement the new EmailMessageInterface. 

Solution:  UseMagento\Framework\Mail\Template\TransportBuilder instead. 


Usage scenario: Calling getBody/getMessageBody on  EmailMessageInterface.

Solution: Use instanceof MessageInterface on $message. If $message is an instance of MessageInterface, call getMessageBody. Otherwice call getBody. 


Additional Notes

  • MailMessageInterface and Magento\Framework\Mail\Message have been deprecated.
  • EmailMessageInterface temporarily extends MailMessageInterface, but methods that belong to MailMessageInterface may be removed in Magento 2.4.
  • We recommend not to use deprecated methods and use only methods of EmailMessageInterface itself (not inherited methods) to have extensions aligned with changes that may be done in Magento 2.4.