Return-Path header not respected

If you set the Return-Path header in code it will be discarded in favor of the from address. Under a range of circumstances it is important to be able to set the Return-Path in code - for example when running a mailing list, or processing bounced email.

function my_module_mail_alter(&$message) {
   // Will be ignored.
   $message['headers']['Return-Path'] = 'return-path@example.com'
}

This is an example of what you have to do with PHPMailer in order to set a Return-Path header such that it is different from the Reply-To or From headers:

$mail->Sender = $return_path_email;
$mail->From = $from_email;
$mail->FromName = $from_name;
$mail->AddAddress($to_email);