1<?php
2
3declare(strict_types=1);
4
5/**
6 * @copyright Copyright (c) 2016, ownCloud, Inc.
7 *
8 * @author Joas Schilling <coding@schilljs.com>
9 * @author Lukas Reschke <lukas@statuscode.ch>
10 * @author Morris Jobke <hey@morrisjobke.de>
11 * @author Roeland Jago Douma <roeland@famdouma.nl>
12 *
13 * @license AGPL-3.0
14 *
15 * This code is free software: you can redistribute it and/or modify
16 * it under the terms of the GNU Affero General Public License, version 3,
17 * as published by the Free Software Foundation.
18 *
19 * This program is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU Affero General Public License for more details.
23 *
24 * You should have received a copy of the GNU Affero General Public License, version 3,
25 * along with this program. If not, see <http://www.gnu.org/licenses/>
26 *
27 */
28namespace OCP\Mail;
29
30/**
31 * Class IMailer provides some basic functions to create a mail message that can be used in combination with
32 * \OC\Mail\Message.
33 *
34 * Example usage:
35 *
36 * 	$mailer = \OC::$server->getMailer();
37 * 	$message = $mailer->createMessage();
38 * 	$message->setSubject('Your Subject');
39 * 	$message->setFrom(['cloud@domain.org' => 'Nextcloud Notifier']);
40 * 	$message->setTo(['recipient@domain.org' => 'Recipient']);
41 * 	$message->setPlainBody('The message text');
42 * 	$message->setHtmlBody('The <strong>message</strong> text');
43 * 	$mailer->send($message);
44 *
45 * This message can then be passed to send() of \OC\Mail\Mailer
46 *
47 * @since 8.1.0
48 */
49interface IMailer {
50	/**
51	 * Creates a new message object that can be passed to send()
52	 *
53	 * @return IMessage
54	 * @since 8.1.0
55	 */
56	public function createMessage(): IMessage;
57
58	/**
59	 * @param string|null $data
60	 * @param string|null $filename
61	 * @param string|null $contentType
62	 * @return IAttachment
63	 * @since 13.0.0
64	 */
65	public function createAttachment($data = null, $filename = null, $contentType = null): IAttachment;
66
67	/**
68	 * @param string $path
69	 * @param string|null $contentType
70	 * @return IAttachment
71	 * @since 13.0.0
72	 */
73	public function createAttachmentFromPath(string $path, $contentType = null): IAttachment;
74
75	/**
76	 * Creates a new email template object
77	 *
78	 * @param string $emailId
79	 * @param array $data
80	 * @return IEMailTemplate
81	 * @since 12.0.0 Parameters added in 12.0.3
82	 */
83	public function createEMailTemplate(string $emailId, array $data = []): IEMailTemplate;
84
85	/**
86	 * Send the specified message. Also sets the from address to the value defined in config.php
87	 * if no-one has been passed.
88	 *
89	 * @param IMessage $message Message to send
90	 * @return string[] Array with failed recipients. Be aware that this depends on the used mail backend and
91	 * therefore should be considered
92	 * @throws \Exception In case it was not possible to send the message. (for example if an invalid mail address
93	 * has been supplied.)
94	 * @since 8.1.0
95	 */
96	public function send(IMessage $message): array;
97
98	/**
99	 * Checks if an e-mail address is valid
100	 *
101	 * @param string $email Email address to be validated
102	 * @return bool True if the mail address is valid, false otherwise
103	 * @since 8.1.0
104	 */
105	public function validateMailAddress(string $email): bool;
106}
107