* REST API/Mail: viewing uploaded EML files, allowing user to answer, forward or download attachments

doc/REST-CalDAV-CardDAV/Mail.md

@@ -5,7 +5,8 @@ Authentication is via Basic Auth with username and a password, or a token valid
 - CalDAV/CardDAV Sync (REST API)
 - E-Mail application
 
-> Currently only implemented is sending mail or launching interactive compose windows.
+> Currently only implemented is sending mail, launching interactive compose windows, 
+> viewing EML files or setting the vacation notice.
 
 Implemented requests (relative to https://example.org/egroupware/groupdav.php)
 
@@ -136,6 +137,31 @@ Location: https://example.org/egroupware/groupdav.php/mail/attachment/<token>
 > When using curl to upload attachments it's important to use ```--data-binary```, just ```-d``` or ```--data``` is NOT sufficient!
 </details>
 
+- ```POST /mail[/<id>]/view``` view an eml file
+<details>
+  <summary>Example: Uploading an eml file to be viewed</summary>
+
+The content of the POST request is the eml-file. 
+It gets imported to the Drafts folder of the selected or default mail account, 
+and is then viewed from there.
+
+The user has the ability to answer or forward the message, or download attachments.
+
+```
+curl -i https://example.org/egroupware/groupdav.php/mail/attachments/<filename> --user <user> \
+    --data-binary @<eml-file> -H 'Content-Type: message/rfc822'
+HTTP/1.1 200 Ok
+
+{
+    "status": 200,
+    "message": "Request to open view window sent",
+}
+```
+> You get a `404 Not Found`, if the user is NOT online, like in compose.
+
+> When using curl to upload attachments it's important to use ```--data-binary```, just ```-d``` or ```--data``` is NOT sufficient!
+</details>
+
 - ```POST /mail[/<id>]/vacation``` enable or disable vacation message or forwarding
 
 <details>

mail/src/ApiHandler.php

@@ -69,6 +69,10 @@ class ApiHandler extends Api\CalDAV\Handler
 			{
 				return self::updateVacation($user, $options['content'], $matches[2]);
 			}
+			elseif (preg_match('#^/mail(/(\d+))?/view/?$#', $path, $matches))
+			{
+				return self::viewEml($user, $options['stream'] ?? $options['content'], $matches[2]);
+			}
 			elseif (preg_match('#^/mail(/(\d+))?(/compose)?#', $path, $matches))
 			{
 				$ident_id = $matches[2] ?? self::defaultIdentity($user);
@@ -294,6 +298,61 @@ class ApiHandler extends Api\CalDAV\Handler
 		throw new \Exception('Error storing attachment');
 	}
 
+	/**
+	 * View posted eml file
+	 *
+	 * @param int $user
+	 * @param string|stream $content
+	 * @param ?int $acc_id mail account to import in Drafts folder
+	 * @return string HTTP status
+	 * @throws \Exception on error
+	 */
+	protected static function viewEml(int $user, $content, int $acc_id=null)
+	{
+		if (empty($acc_id))
+		{
+			$acc_id = self::defaultIdentity($user);
+		}
+
+		// check and bail, if user is not online
+		if (!Api\Json\Push::isOnline($user))
+		{
+			$account_lid = Api\Accounts::id2name($user);
+			throw new \Exception("User '$account_lid' (#$user) is NOT online", 404);
+		}
+
+		// save posted eml to a temp-dir
+		$eml = tempnam($GLOBALS['egw_info']['server']['temp_dir'], 'view-eml-');
+		if (!(is_resource($content) ?
+			stream_copy_to_stream($content, $fp = fopen($eml, 'w')) :
+			file_put_contents($eml, $content)))
+		{
+			throw new \Exception('Error storing attachment');
+		}
+		if (isset($fp)) fclose($fp);
+
+		// import mail into drafts folder
+		$mail = Api\Mail::getInstance(false, $acc_id);
+		$folder = $mail->getDraftFolder();
+		$mailer = new Api\Mailer();
+		$mail->parseFileIntoMailObject($mailer, $eml);
+		$mail->openConnection();
+		$message_uid = $mail->appendMessage($folder, $mailer->getRaw(), null, '\\Seen');
+
+		// tell browser to view eml from drafts folder
+		$push = new Api\Json\Push($user);
+		$push->call('egw.open', \mail_ui::generateRowID($acc_id, $folder, $message_uid, true),
+			'mail', 'view', ['mode' => 'display'], '_blank', 'mail');
+
+		// respond with success message
+		echo json_encode([
+			'status' => 200,
+			'message' => 'Request to open view window sent',
+		], self::JSON_RESPONSE_OPTIONS);
+
+		return true;
+	}
+
 	/**
 	 * Get default identity of user
 	 *