Add DSN mail option

src/PHPMailer.php

@@ -371,6 +371,17 @@ class PHPMailer
      */
     public $Timeout = 300;
 
+    /**
+     * DSN Sender Extensions
+     * 'RET=FULL'  shall return the complete message in case of any error
+     *   xor
+     * 'RET=HDRS'  shall return only the headers of the failed e-mail.
+     * 'ENVID=xyz' shall include the ID xyz on the way back of this e-mail if any error.
+     *
+     * @see https://tools.ietf.org/html/rfc3461 See section 4.3 and 4.4 regarding RET and ENVID
+     */
+    public $dsn_ret = '';
+
     /**
      * Comma separated list of DSN notifications
      * 'NEVER' under no circumstances a DSN must be returned to the sender.
@@ -1884,7 +1895,7 @@ protected function smtpSend($header, $body)
         } else {
             $smtp_from = $this->Sender;
         }
-        if (!$this->smtp->mail($smtp_from)) {
+        if (!$this->smtp->mail($smtp_from, $this->dsn_ret)) {
             $this->setError($this->lang('from_failed') . $smtp_from . ' : ' . implode(',', $this->smtp->getError()));
             throw new Exception($this->ErrorInfo, self::STOP_CRITICAL);
         }

src/SMTP.php

@@ -853,6 +853,82 @@ protected function parseHelloFields($type)
         }
     }
 
+    /**
+     * Enforse the content of the DSN to be compliant with the RFC 3461, section 4.
+     *
+     * @param string $s eg. câfé
+     *
+     * @return string
+     */
+    static protected function xtext(string $s): string
+    {
+        $r = '';
+        for($i = 0, $len = strlen($s); $i < $len; $i++) {
+            $o = ord($s[$i]);
+            if (($o >= 0x21) && ($o < 0x7e) && ($o !== ord('+')) && ($o !== ord('='))) {
+                $r .= $s[$i];
+                 continue;
+            }
+            $r .= sprintf("+%02X", $o & 0xff);
+        }
+        return $r;
+    }
+
+    /**
+     * Enforce the content of the DSN to be compliant with the RFC 3461, section 4.
+     *
+     * @param string $s eg. câfé
+     *
+     * @return false|string
+     */
+    static protected function dsnize(string $str)
+    {
+        $r = array();
+        $args = explode(' ', $str);
+        switch(count($args)) {
+            case 1: /* likely RET=HDRS|FULL */
+            case 2: /* likely RET=HDRS|FULL ENVID=xtext */
+            /* place holder if more arguments get required */
+                break;
+            default:
+                return false;
+        }
+
+        foreach($args as $i => $arg) {
+            $tokens = explode('=', $arg);
+
+            if ($i === 0) {
+                if (count($tokens) !== 2)
+                    return false;
+
+                if (strcasecmp($tokens[0], 'RET') !== 0)
+                    return false;
+
+                if ((strcasecmp($tokens[1], 'FULL') !== 0) &&
+                    (strcasecmp($tokens[1], 'HDRS') !== 0))
+                    return false;
+
+                $r[] = sprintf("RET=%s", strtoupper($tokens[1])); /* FULL or HDRS */
+                continue;
+            }
+
+            if ($i == 1) {
+                /* support any cases including ENVID=ab=de */
+                if (count($tokens) <= 1)
+                    return false;
+
+                if (strcasecmp($tokens[0], 'ENVID') !== 0)
+                    return false;
+
+                array_shift($tokens); # pop ENVID
+                $id = implode('=', $tokens);
+                $r[] = sprintf("ENVID=%s", self::xtext($id));
+                continue;
+            }
+        }
+        return implode(' ', $r);
+    }
+
     /**
      * Send an SMTP MAIL command.
      * Starts a mail transaction from the email address specified in
@@ -862,16 +938,26 @@ protected function parseHelloFields($type)
      * Implements RFC 821: MAIL <SP> FROM:<reverse-path> <CRLF>.
      *
      * @param string $from Source address of this message
+     * @param string $ret  DSN argument
      *
      * @return bool
      */
-    public function mail($from)
+    public function mail($from, $ret = '')
     {
         $useVerp = ($this->do_verp ? ' XVERP' : '');
 
+        $useRet = '';
+        if ($this->getServerExt('DSN') && !empty($ret)) {
+            $useRet = self::dsnize($ret);
+	    if (!is_string($useRet))
+                $useRet = ''; # bad one
+	    else
+                $useRet = ' ' . $useRet;
+        }
+
         return $this->sendCommand(
             'MAIL FROM',
-            'MAIL FROM:<' . $from . '>' . $useVerp,
+            'MAIL FROM:<' . $from . '>' . $useVerp . $useRet,
             250
         );
     }