IMailer.php 2.5 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
  6. * SPDX-License-Identifier: AGPL-3.0-only
  7. */
  8. namespace OCP\Mail;
  9. /**
  10. * Class IMailer provides some basic functions to create a mail message that can be used in combination with
  11. * \OC\Mail\Message.
  12. *
  13. * Example usage:
  14. *
  15. * $mailer = \OC::$server->get(\OCP\Mail\IMailer::class);
  16. * $message = $mailer->createMessage();
  17. * $message->setSubject('Your Subject');
  18. * $message->setFrom(['cloud@domain.org' => 'Nextcloud Notifier']);
  19. * $message->setTo(['recipient@domain.org' => 'Recipient']);
  20. * $message->setPlainBody('The message text');
  21. * $message->setHtmlBody('The <strong>message</strong> text');
  22. * $mailer->send($message);
  23. *
  24. * This message can then be passed to send() of \OC\Mail\Mailer
  25. *
  26. * @since 8.1.0
  27. */
  28. interface IMailer {
  29. /**
  30. * Creates a new message object that can be passed to send()
  31. *
  32. * @return IMessage
  33. * @since 8.1.0
  34. */
  35. public function createMessage(): IMessage;
  36. /**
  37. * @param string|null $data
  38. * @param string|null $filename
  39. * @param string|null $contentType
  40. * @return IAttachment
  41. * @since 13.0.0
  42. */
  43. public function createAttachment($data = null, $filename = null, $contentType = null): IAttachment;
  44. /**
  45. * @param string $path
  46. * @param string|null $contentType
  47. * @return IAttachment
  48. * @since 13.0.0
  49. */
  50. public function createAttachmentFromPath(string $path, $contentType = null): IAttachment;
  51. /**
  52. * Creates a new email template object
  53. *
  54. * @param string $emailId
  55. * @param array $data
  56. * @return IEMailTemplate
  57. * @since 12.0.0 Parameters added in 12.0.3
  58. */
  59. public function createEMailTemplate(string $emailId, array $data = []): IEMailTemplate;
  60. /**
  61. * Send the specified message. Also sets the from address to the value defined in config.php
  62. * if no-one has been passed.
  63. *
  64. * @param IMessage $message Message to send
  65. * @return string[] Array with failed recipients. Be aware that this depends on the used mail backend and
  66. * therefore should be considered
  67. * @throws \Exception In case it was not possible to send the message. (for example if an invalid mail address
  68. * has been supplied.)
  69. * @since 8.1.0
  70. */
  71. public function send(IMessage $message): array;
  72. /**
  73. * @param string $email Email address to be validated
  74. * @return bool True if the mail address is valid, false otherwise
  75. * @since 8.1.0
  76. */
  77. public function validateMailAddress(string $email): bool;
  78. }