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