diff --git a/index.html b/index.html index a84a514..41189e0 100644 --- a/index.html +++ b/index.html @@ -448,5 +448,5 @@
Search
diff --git a/search/search_index.json b/search/search_index.json index 709bc78..557e926 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"dot-mail [!IMPORTANT] dot-mail is a wrapper on top of symfony mailer dot-mail badges Installation Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail Configuration Mail - Sendmail If your server has Sendmail installed, update the config/autoload/mail.local.php.dist file by setting the transport key like below <?php return [ 'dot_mail' => [ 'default' => [ //... 'transport' => Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport::class, //... ] ] ] Mail - SMTP If you want your application to send mails on e.g. registration, contact, then edit the file config/autoload/mail.local.php . Set the transport , message_options and smtp_options keys like below. Under message_options key: from - email address from whom users will receive emails Under smtp_options key: host - the mail server's hostname or IP address port - the mail server's port connection_config - fill in the username , password and ssl keys with the login details of the email used in from above Note: all other keys can be left as is. <?php return [ 'dot_mail' => [ 'default' => [ //... 'transport' => Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport::class, 'message_options' => [ 'from' => '', //... ], 'smtp_options' => [ 'host' => '', 'port' => 25, 'connection_config' => [ 'username' => '', 'password' => '', 'ssl' => '', ] ] //... ] ] ] In config/autoload/local.php add under contact => message_receivers => to key string values with the emails that should receive contact messages Note: Please add at least 1 email address in order for contact message to reach someone Also feel free to add as many cc as you want under contact => message_receivers => cc key Sending an e-mail Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. Note that addTo is only one of the methods available for the Message class returned by getMessage() . Other useful methods that were not included in the example are addCc() , addBcc() , addReplyTo() . The returned type is boolean, but if the isValid() method is removed, the returned type becomes MailResult which allows the use of getMessage() for a more detailed error message. See the Testing if an e-mail message is valid section below. public function sendBasicMail() { $this->mailService->setBody('Email body'); $this->mailService->setSubject('Email subject'); $this->mailService->getMessage()->addTo('email@example.com', 'User name'); $this->mailService->getMessage()->setEncoding('utf-8'); return $this->mailService->send()->isValid(); } It's optional, but recommended to call the above function in a try-catch block to display helpful error messages. The next example calls the sendBasicMail function from within UserController , but you can implement it in other controllers, just make sure that the controller's construct also includes the FlashMessenger parameter $messenger . try { $this->userService->sendBasicMail(); $this->messenger->addSuccess('The mail was sent successfully', 'user-login'); //more code... } catch (Exception $exception) { $this->messenger->addError($exception->getMessage(), 'user-login'); //more code... } Testing if an e-mail message is valid After sending an e-mail you can check if the message was valid or not. The $this->mailService->send()->isValid() method call will return a boolean value. If the returned result is true , the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using $this->mailService->send()->getMessage() . Using the below logic will let you determine if a message was valid or not and log it. You can implement your own custom error logging logic. $result = $this->mailService->send(); if (! $result->isValid()) { //log the error error_log($result->getMessage()); } Invalid e-mail messages will not be sent. Logging outgoing emails Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {\"subject\":\"Test subject\",\"to\":[\"Test Account <test@dotkernel.com>\"],\"cc\":[],\"bcc\":[]} . In order to enable it, make sure that your config/autoload/mail.local.php has the below log configuration under the dot_mail key: <?php return [ 'dot_mail' => [ ... 'log' => [ 'sent' => getcwd() . '/log/mail/sent.log' ] ] ]; To disable it, set the value of sent to null .","title":"Home"},{"location":"#dot-mail","text":"[!IMPORTANT] dot-mail is a wrapper on top of symfony mailer","title":"dot-mail"},{"location":"#dot-mail-badges","text":"","title":"dot-mail badges"},{"location":"#installation","text":"Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail","title":"Installation"},{"location":"#configuration","text":"","title":"Configuration"},{"location":"v4/configuration/","text":"Configuration Register dot-mail in you project by adding Dot\\Mail\\ConfigProvider::class to your configuration aggregator (to config/config.php for example). After registering the ConfigProvider copy the configuration file config/mail.global.php.dist into your project's config/autoload/ directory as mail.global.php . The resulting mail.global.php contains the necessary configurations for all available transport types, message options and logging options in one place. The config file provides a set of default values available to all mails under the dot-mail.default key. Many of these options can be programmatically set when sending the actual email. An example of this is the dot-mail.default.message_options key, which can be filled in with default message values to be available to all emails. When sending the actual email, these values can be overwritten by using an available \"setter\" function, supplemented by using \"add\" functions or simply left as the default. // setter will overwrite existing destination email $this->mailService->getMessage()->setTo(\"receiver@email.com\"); // existing destination email kept, new destination email added alongside it $this->mailService->getMessage()->addTo(\"receiver@email.com\"); Transport configuration dot-mail uses the transport key under the main dot_mail configuration key to select the email transport. It has four email transport classes available by default ( Sendmail , Smtp , File , InMemory ), one of which is to be added under the dot_mail.transport key for use. Both Sendmail and InMemory transports requires no specific configuration to use by default. Sending email with the Smtp transport requires valid data for the values under dot-mail.default.smtp_options , which is only used in this case. The dot_mail.default.save_sent_message_folder key may be uncommented when using this transport, saving a copy of all sent email to a certain IMAP folder. Using Laminas\\Mail\\Transport\\File as the transport will require uncommenting the dot-mail.default.file_options key. The configured path must be a writable directory 'file_options' => [ 'path' => 'data/mail/output', //'callback' => null, ], If no callback is provided to specify a new file name format, the messages will be saved in files using the default format set in Laminas\\Mail\\Transport\\FileOptions . // Example of a custom format 'callback' => static fn() => sprintf('DotMail%d_%s.log', time(), 'customFormat'), Logging configuration Uncommenting the dot-mail.log key will save a copy of all sent emails' subject, recipient addresses, cc and bcc addresses alongside a timestamp. In order to enable it, make sure that your mail.local.php has the below log configuration under the dot_mail key: <?php return [ 'dot_mail' => [ ... 'log' => [ 'sent' => getcwd() . '/log/mail/sent.log' ] ] ]; To disable it, set the value of sent to null .","title":"Configuration"},{"location":"v4/configuration/#configuration","text":"Register dot-mail in you project by adding Dot\\Mail\\ConfigProvider::class to your configuration aggregator (to config/config.php for example). After registering the ConfigProvider copy the configuration file config/mail.global.php.dist into your project's config/autoload/ directory as mail.global.php . The resulting mail.global.php contains the necessary configurations for all available transport types, message options and logging options in one place. The config file provides a set of default values available to all mails under the dot-mail.default key. Many of these options can be programmatically set when sending the actual email. An example of this is the dot-mail.default.message_options key, which can be filled in with default message values to be available to all emails. When sending the actual email, these values can be overwritten by using an available \"setter\" function, supplemented by using \"add\" functions or simply left as the default. // setter will overwrite existing destination email $this->mailService->getMessage()->setTo(\"receiver@email.com\"); // existing destination email kept, new destination email added alongside it $this->mailService->getMessage()->addTo(\"receiver@email.com\");","title":"Configuration"},{"location":"v4/configuration/#transport-configuration","text":"dot-mail uses the transport key under the main dot_mail configuration key to select the email transport. It has four email transport classes available by default ( Sendmail , Smtp , File , InMemory ), one of which is to be added under the dot_mail.transport key for use. Both Sendmail and InMemory transports requires no specific configuration to use by default. Sending email with the Smtp transport requires valid data for the values under dot-mail.default.smtp_options , which is only used in this case. The dot_mail.default.save_sent_message_folder key may be uncommented when using this transport, saving a copy of all sent email to a certain IMAP folder. Using Laminas\\Mail\\Transport\\File as the transport will require uncommenting the dot-mail.default.file_options key. The configured path must be a writable directory 'file_options' => [ 'path' => 'data/mail/output', //'callback' => null, ], If no callback is provided to specify a new file name format, the messages will be saved in files using the default format set in Laminas\\Mail\\Transport\\FileOptions . // Example of a custom format 'callback' => static fn() => sprintf('DotMail%d_%s.log', time(), 'customFormat'),","title":"Transport configuration"},{"location":"v4/configuration/#logging-configuration","text":"Uncommenting the dot-mail.log key will save a copy of all sent emails' subject, recipient addresses, cc and bcc addresses alongside a timestamp. In order to enable it, make sure that your mail.local.php has the below log configuration under the dot_mail key: <?php return [ 'dot_mail' => [ ... 'log' => [ 'sent' => getcwd() . '/log/mail/sent.log' ] ] ]; To disable it, set the value of sent to null .","title":"Logging configuration"},{"location":"v4/installation/","text":"Installation Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail","title":"Installation"},{"location":"v4/installation/#installation","text":"Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail","title":"Installation"},{"location":"v4/overview/","text":"Overview dot-mail is a wrapper on top of laminas-mail Extra features the option to log the results of the mailing process it provides the developer with more information and greater control.","title":"Overview"},{"location":"v4/overview/#overview","text":"dot-mail is a wrapper on top of laminas-mail","title":"Overview"},{"location":"v4/overview/#extra-features","text":"the option to log the results of the mailing process it provides the developer with more information and greater control.","title":"Extra features"},{"location":"v4/transports/","text":"Transports dot-mail can use any transport class that implements Laminas\\Mail\\Transport\\TransportInterface , with the four standard transports available being: Laminas\\Mail\\Transport\\Sendmail - the default transport set in the config file Laminas\\Mail\\Transport\\Smtp Laminas\\Mail\\Transport\\File Laminas\\Mail\\Transport\\InMemory Feel free to use any custom transport you desire, provided it implements the mentioned TransportInterface . Sendmail is a wrapper over PHP's mail() function, and as such has a different behaviour on Windows than on nix systems. Using sendmail on Windows will not work in combination with * addBcc() . Note: emails sent using the sendmail transport will be more often delivered to SPAM. Smtp connects to the configured SMTP host in order to handle sending emails. Saving a copy of an outgoing mail into a folder is possible for this transport only, and is done by uncommenting save_sent_message_folder in the config file mail.local.php under dot_mail.default . Common folder names are INBOX , INBOX.Archive , INBOX.Drafts , INBOX.Sent , INBOX.Spam , INBOX.Trash . If you have MailService available in your class, you can call $this->mailService->getFolderGlobalNames() to list the folder global names for the email you are using. Multiple folders can be added to the save_sent_message_folder key to save a copy of the outgoing email in each folder. File writes each message individually in a file named after the configured format, placed in the configured directory. From here the files may be used for sending via another transport mechanism, or simply as logs. InMemory saves the message in memory, allowing access to the last \"sent\" message via the getLastMessage() function. As the email is not sent, this transport can be helpful in development, with the access to the message being potentially useful in tests as well $this->mailService->setBody('First email body'); $this->mailService->setSubject('First email subject'); $this->mailService->getMessage()->setTo('email@example.com'); // The email is not sent to the email, instead it is stored in memory $this->mailService->send(); $this->mailService->setBody('Second email body'); $this->mailService->setSubject('Second email subject'); $this->mailService->getMessage()->setTo('email@example.com'); // The email is not sent to the email either, it overwrites the previously \"sent\" email in memory $this->mailService->send(); // Returns the second email's Laminas\\Mail\\Message object from memory $lastMessage = $this->mailService()->getTransport()->getLastMessage();","title":"Transports"},{"location":"v4/transports/#transports","text":"dot-mail can use any transport class that implements Laminas\\Mail\\Transport\\TransportInterface , with the four standard transports available being: Laminas\\Mail\\Transport\\Sendmail - the default transport set in the config file Laminas\\Mail\\Transport\\Smtp Laminas\\Mail\\Transport\\File Laminas\\Mail\\Transport\\InMemory Feel free to use any custom transport you desire, provided it implements the mentioned TransportInterface . Sendmail is a wrapper over PHP's mail() function, and as such has a different behaviour on Windows than on nix systems. Using sendmail on Windows will not work in combination with * addBcc() . Note: emails sent using the sendmail transport will be more often delivered to SPAM. Smtp connects to the configured SMTP host in order to handle sending emails. Saving a copy of an outgoing mail into a folder is possible for this transport only, and is done by uncommenting save_sent_message_folder in the config file mail.local.php under dot_mail.default . Common folder names are INBOX , INBOX.Archive , INBOX.Drafts , INBOX.Sent , INBOX.Spam , INBOX.Trash . If you have MailService available in your class, you can call $this->mailService->getFolderGlobalNames() to list the folder global names for the email you are using. Multiple folders can be added to the save_sent_message_folder key to save a copy of the outgoing email in each folder. File writes each message individually in a file named after the configured format, placed in the configured directory. From here the files may be used for sending via another transport mechanism, or simply as logs. InMemory saves the message in memory, allowing access to the last \"sent\" message via the getLastMessage() function. As the email is not sent, this transport can be helpful in development, with the access to the message being potentially useful in tests as well $this->mailService->setBody('First email body'); $this->mailService->setSubject('First email subject'); $this->mailService->getMessage()->setTo('email@example.com'); // The email is not sent to the email, instead it is stored in memory $this->mailService->send(); $this->mailService->setBody('Second email body'); $this->mailService->setSubject('Second email subject'); $this->mailService->getMessage()->setTo('email@example.com'); // The email is not sent to the email either, it overwrites the previously \"sent\" email in memory $this->mailService->send(); // Returns the second email's Laminas\\Mail\\Message object from memory $lastMessage = $this->mailService()->getTransport()->getLastMessage();","title":"Transports"},{"location":"v4/usage/","text":"Usage Sending an e-mail Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. Note that addTo is only one of the methods available for the Message class returned by getMessage() . Other useful methods that were not included in the example are addCc() , addBcc() , addReplyTo() . The returned type is boolean, but if the isValid() method is removed, the returned type becomes MailResult which allows the use of getMessage() for a more detailed error message. See the Testing if an e-mail message is valid section below. public function sendBasicMail() { $this->mailService->setBody('Email body'); $this->mailService->setSubject('Email subject'); $this->mailService->getMessage()->addTo('email@example.com', 'User name'); $this->mailService->getMessage()->setEncoding('utf-8'); return $this->mailService->send()->isValid(); } It's optional, but recommended to call the above function in a try-catch block to display helpful error messages. The next example calls the sendBasicMail function from within UserController , but you can implement it in other controllers, just make sure that the controller's construct also includes the FlashMessenger parameter $messenger . try { $this->userService->sendBasicMail(); $this->messenger->addSuccess('The mail was sent successfully', 'user-login'); //more code... } catch (Exception $exception) { $this->messenger->addError($exception->getMessage(), 'user-login'); //more code... } Testing if an e-mail message is valid After sending an e-mail you can check if the message was valid or not. The $this->mailService->send()->isValid() method call will return a boolean value. If the returned result is true , the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using $this->mailService->send()->getMessage() . Using the below logic will let you determine if a message was valid or not and log it. You can implement your own custom error logging logic. $result = $this->mailService->send(); if (! $result->isValid()) { //log the error error_log($result->getMessage()); } Invalid e-mail messages will not be sent. Logging outgoing emails Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {\"subject\":\"Test subject\",\"to\":[\"Test Account <test@dotkernel.com>\"],\"cc\":[],\"bcc\":[]} . Each email is saved via the dotkernel/dot-log component in the shown JSON format, in the single file configured under the dot-mail.log.sent key. To disable it, set the value of dot-mail.log.sent to null . Transport usage Transports","title":"Usage"},{"location":"v4/usage/#usage","text":"","title":"Usage"},{"location":"v4/usage/#sending-an-e-mail","text":"Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. Note that addTo is only one of the methods available for the Message class returned by getMessage() . Other useful methods that were not included in the example are addCc() , addBcc() , addReplyTo() . The returned type is boolean, but if the isValid() method is removed, the returned type becomes MailResult which allows the use of getMessage() for a more detailed error message. See the Testing if an e-mail message is valid section below. public function sendBasicMail() { $this->mailService->setBody('Email body'); $this->mailService->setSubject('Email subject'); $this->mailService->getMessage()->addTo('email@example.com', 'User name'); $this->mailService->getMessage()->setEncoding('utf-8'); return $this->mailService->send()->isValid(); } It's optional, but recommended to call the above function in a try-catch block to display helpful error messages. The next example calls the sendBasicMail function from within UserController , but you can implement it in other controllers, just make sure that the controller's construct also includes the FlashMessenger parameter $messenger . try { $this->userService->sendBasicMail(); $this->messenger->addSuccess('The mail was sent successfully', 'user-login'); //more code... } catch (Exception $exception) { $this->messenger->addError($exception->getMessage(), 'user-login'); //more code... }","title":"Sending an e-mail"},{"location":"v4/usage/#testing-if-an-e-mail-message-is-valid","text":"After sending an e-mail you can check if the message was valid or not. The $this->mailService->send()->isValid() method call will return a boolean value. If the returned result is true , the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using $this->mailService->send()->getMessage() . Using the below logic will let you determine if a message was valid or not and log it. You can implement your own custom error logging logic. $result = $this->mailService->send(); if (! $result->isValid()) { //log the error error_log($result->getMessage()); } Invalid e-mail messages will not be sent.","title":"Testing if an e-mail message is valid"},{"location":"v4/usage/#logging-outgoing-emails","text":"Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {\"subject\":\"Test subject\",\"to\":[\"Test Account <test@dotkernel.com>\"],\"cc\":[],\"bcc\":[]} . Each email is saved via the dotkernel/dot-log component in the shown JSON format, in the single file configured under the dot-mail.log.sent key. To disable it, set the value of dot-mail.log.sent to null .","title":"Logging outgoing emails"},{"location":"v4/usage/#transport-usage","text":"Transports","title":"Transport usage"},{"location":"v5/configuration/","text":"Configuration Register dot-mail in you project by adding Dot\\Mail\\ConfigProvider::class to your configuration aggregator (to config/config.php for example). After registering the ConfigProvider copy the configuration file config/mail.global.php.dist into your project's config/autoload/ directory as mail.global.php . The resulting mail.global.php contains the necessary configurations for all available transport types, message options and logging options in one place. The config file provides a set of default values available to all mails under the dot-mail.default key. Many of these options can be programmatically set when sending the actual email. An example of this is the dot-mail.default.message_options key, which can be filled in with default message values to be available to all emails. When sending the actual email, these values can be overwritten by using an available \"setter\" function, supplemented by using \"add\" functions or simply left as the default. // setter will overwrite existing destination email $this->mailService->getMessage()->setTo(\"receiver@email.com\"); // existing destination email kept, new destination email added alongside it $this->mailService->getMessage()->addTo(\"receiver@email.com\"); Transport configuration dot-mail uses the transport key under the main dot_mail configuration key to select the email transport. It has four email transport classes available by default ( SmtpTransport ), one of which is to be added under the dot_mail.transport key for use. Sending email with the Smtp transport requires valid data for the values under dot-mail.default.smtp_options , which is only used in this case. The configured path must be a writable directory 'file_options' => [ 'path' => 'data/mail/output', //'callback' => null, ], Logging configuration Uncommenting the dot-mail.log key will save a copy of all sent emails' subject, recipient addresses, cc and bcc addresses alongside a timestamp. In order to enable it, make sure that your mail.local.php has the below log configuration under the dot_mail key: <?php return [ 'dot_mail' => [ ... 'log' => [ 'sent' => getcwd() . '/log/mail/sent.log' ] ] ]; To disable it, set the value of sent to null .","title":"Configuration"},{"location":"v5/configuration/#configuration","text":"Register dot-mail in you project by adding Dot\\Mail\\ConfigProvider::class to your configuration aggregator (to config/config.php for example). After registering the ConfigProvider copy the configuration file config/mail.global.php.dist into your project's config/autoload/ directory as mail.global.php . The resulting mail.global.php contains the necessary configurations for all available transport types, message options and logging options in one place. The config file provides a set of default values available to all mails under the dot-mail.default key. Many of these options can be programmatically set when sending the actual email. An example of this is the dot-mail.default.message_options key, which can be filled in with default message values to be available to all emails. When sending the actual email, these values can be overwritten by using an available \"setter\" function, supplemented by using \"add\" functions or simply left as the default. // setter will overwrite existing destination email $this->mailService->getMessage()->setTo(\"receiver@email.com\"); // existing destination email kept, new destination email added alongside it $this->mailService->getMessage()->addTo(\"receiver@email.com\");","title":"Configuration"},{"location":"v5/configuration/#transport-configuration","text":"dot-mail uses the transport key under the main dot_mail configuration key to select the email transport. It has four email transport classes available by default ( SmtpTransport ), one of which is to be added under the dot_mail.transport key for use. Sending email with the Smtp transport requires valid data for the values under dot-mail.default.smtp_options , which is only used in this case. The configured path must be a writable directory 'file_options' => [ 'path' => 'data/mail/output', //'callback' => null, ],","title":"Transport configuration"},{"location":"v5/configuration/#logging-configuration","text":"Uncommenting the dot-mail.log key will save a copy of all sent emails' subject, recipient addresses, cc and bcc addresses alongside a timestamp. In order to enable it, make sure that your mail.local.php has the below log configuration under the dot_mail key: <?php return [ 'dot_mail' => [ ... 'log' => [ 'sent' => getcwd() . '/log/mail/sent.log' ] ] ]; To disable it, set the value of sent to null .","title":"Logging configuration"},{"location":"v5/installation/","text":"Installation Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail","title":"Installation"},{"location":"v5/installation/#installation","text":"Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail","title":"Installation"},{"location":"v5/overview/","text":"Overview dot-mail is a wrapper on top of symfony mailer Extra features the option to log the results of the mailing process it provides the developer with more information and greater control.","title":"Overview"},{"location":"v5/overview/#overview","text":"dot-mail is a wrapper on top of symfony mailer","title":"Overview"},{"location":"v5/overview/#extra-features","text":"the option to log the results of the mailing process it provides the developer with more information and greater control.","title":"Extra features"},{"location":"v5/transports/","text":"Transports dot-mail can use any transport class that implements Symfony\\Component\\Mailer\\Transport\\TransportInterface , with the standard transport available being: Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport, Symfony\\Component\\Mailer\\Transport\\SendmailTransport, Feel free to use any custom transport you desire, provided it implements the mentioned TransportInterface . Sendmail is a wrapper over PHP's mail() function, and as such has a different behaviour on Windows than on nix systems. Using sendmail on Windows will not work in combination with * addBcc() . Note: emails sent using the sendmail transport will be more often delivered to SPAM. Smtp connects to the configured SMTP host in order to handle sending emails.","title":"Transports"},{"location":"v5/transports/#transports","text":"dot-mail can use any transport class that implements Symfony\\Component\\Mailer\\Transport\\TransportInterface , with the standard transport available being: Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport, Symfony\\Component\\Mailer\\Transport\\SendmailTransport, Feel free to use any custom transport you desire, provided it implements the mentioned TransportInterface . Sendmail is a wrapper over PHP's mail() function, and as such has a different behaviour on Windows than on nix systems. Using sendmail on Windows will not work in combination with * addBcc() . Note: emails sent using the sendmail transport will be more often delivered to SPAM. Smtp connects to the configured SMTP host in order to handle sending emails.","title":"Transports"},{"location":"v5/usage/","text":"Usage Sending an e-mail Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. Note that addTo is only one of the methods available for the Message class returned by getMessage() . Other useful methods that were not included in the example are addCc() , addBcc() , addReplyTo() . The returned type is boolean, but if the isValid() method is removed, the returned type becomes MailResult which allows the use of getMessage() for a more detailed error message. See the Testing if an e-mail message is valid section below. public function sendBasicMail() { $this->mailService->setBody('Email body'); $this->mailService->setSubject('Email subject'); $this->mailService->getMessage()->addTo('email@example.com', 'User name'); $this->mailService->getMessage()->setEncoding('utf-8'); return $this->mailService->send()->isValid(); } It's optional, but recommended to call the above function in a try-catch block to display helpful error messages. The next example calls the sendBasicMail function from within UserController , but you can implement it in other controllers, just make sure that the controller's construct also includes the FlashMessenger parameter $messenger . try { $this->userService->sendBasicMail(); $this->messenger->addSuccess('The mail was sent successfully', 'user-login'); //more code... } catch (Exception $exception) { $this->messenger->addError($exception->getMessage(), 'user-login'); //more code... } Testing if an e-mail message is valid After sending an e-mail you can check if the message was valid or not. The $this->mailService->send()->isValid() method call will return a boolean value. If the returned result is true , the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using $this->mailService->send()->getMessage() . Using the below logic will let you determine if a message was valid or not and log it. You can implement your own custom error logging logic. $result = $this->mailService->send(); if (! $result->isValid()) { //log the error error_log($result->getMessage()); } Invalid e-mail messages will not be sent. Logging outgoing emails Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {\"subject\":\"Test subject\",\"to\":[\"Test Account <test@dotkernel.com>\"],\"cc\":[],\"bcc\":[]} . Each email is saved via the dotkernel/dot-log component in the shown JSON format, in the single file configured under the dot-mail.log.sent key. To disable it, set the value of dot-mail.log.sent to null . Transport usage Transports","title":"Usage"},{"location":"v5/usage/#usage","text":"","title":"Usage"},{"location":"v5/usage/#sending-an-e-mail","text":"Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. Note that addTo is only one of the methods available for the Message class returned by getMessage() . Other useful methods that were not included in the example are addCc() , addBcc() , addReplyTo() . The returned type is boolean, but if the isValid() method is removed, the returned type becomes MailResult which allows the use of getMessage() for a more detailed error message. See the Testing if an e-mail message is valid section below. public function sendBasicMail() { $this->mailService->setBody('Email body'); $this->mailService->setSubject('Email subject'); $this->mailService->getMessage()->addTo('email@example.com', 'User name'); $this->mailService->getMessage()->setEncoding('utf-8'); return $this->mailService->send()->isValid(); } It's optional, but recommended to call the above function in a try-catch block to display helpful error messages. The next example calls the sendBasicMail function from within UserController , but you can implement it in other controllers, just make sure that the controller's construct also includes the FlashMessenger parameter $messenger . try { $this->userService->sendBasicMail(); $this->messenger->addSuccess('The mail was sent successfully', 'user-login'); //more code... } catch (Exception $exception) { $this->messenger->addError($exception->getMessage(), 'user-login'); //more code... }","title":"Sending an e-mail"},{"location":"v5/usage/#testing-if-an-e-mail-message-is-valid","text":"After sending an e-mail you can check if the message was valid or not. The $this->mailService->send()->isValid() method call will return a boolean value. If the returned result is true , the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using $this->mailService->send()->getMessage() . Using the below logic will let you determine if a message was valid or not and log it. You can implement your own custom error logging logic. $result = $this->mailService->send(); if (! $result->isValid()) { //log the error error_log($result->getMessage()); } Invalid e-mail messages will not be sent.","title":"Testing if an e-mail message is valid"},{"location":"v5/usage/#logging-outgoing-emails","text":"Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {\"subject\":\"Test subject\",\"to\":[\"Test Account <test@dotkernel.com>\"],\"cc\":[],\"bcc\":[]} . Each email is saved via the dotkernel/dot-log component in the shown JSON format, in the single file configured under the dot-mail.log.sent key. To disable it, set the value of dot-mail.log.sent to null .","title":"Logging outgoing emails"},{"location":"v5/usage/#transport-usage","text":"Transports","title":"Transport usage"}]} \ No newline at end of file +{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"dot-mail [!IMPORTANT] dot-mail is a wrapper on top of symfony mailer dot-mail badges Installation Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail Configuration Mail - Sendmail If your server has Sendmail installed, update the config/autoload/mail.local.php.dist file by setting the transport key like below <?php return [ 'dot_mail' => [ 'default' => [ //... 'transport' => Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport::class, //... ] ] ] Mail - SMTP If you want your application to send mails on e.g. registration, contact, then edit the file config/autoload/mail.local.php . Set the transport , message_options and smtp_options keys like below. Under message_options key: from - email address from whom users will receive emails Under smtp_options key: host - the mail server's hostname or IP address port - the mail server's port connection_config - fill in the username , password and ssl keys with the login details of the email used in from above Note: all other keys can be left as is. <?php return [ 'dot_mail' => [ 'default' => [ //... 'transport' => Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport::class, 'message_options' => [ 'from' => '', //... ], 'smtp_options' => [ 'host' => '', 'port' => 25, 'connection_config' => [ 'username' => '', 'password' => '', 'ssl' => '', ] ] //... ] ] ] In config/autoload/local.php add under contact => message_receivers => to key string values with the emails that should receive contact messages Note: Please add at least 1 email address in order for contact message to reach someone Also feel free to add as many cc as you want under contact => message_receivers => cc key Sending an e-mail Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. Note that addTo is only one of the methods available for the Message class returned by getMessage() . Other useful methods that were not included in the example are addCc() , addBcc() , addReplyTo() . The returned type is boolean, but if the isValid() method is removed, the returned type becomes MailResult which allows the use of getMessage() for a more detailed error message. See the Testing if an e-mail message is valid section below. public function sendBasicMail() { $this->mailService->setBody('Email body'); $this->mailService->setSubject('Email subject'); $this->mailService->getMessage()->addTo('email@example.com', 'User name'); $this->mailService->getMessage()->setEncoding('utf-8'); return $this->mailService->send()->isValid(); } It's optional, but recommended to call the above function in a try-catch block to display helpful error messages. The next example calls the sendBasicMail function from within UserController , but you can implement it in other controllers, just make sure that the controller's construct also includes the FlashMessenger parameter $messenger . try { $this->userService->sendBasicMail(); $this->messenger->addSuccess('The mail was sent successfully', 'user-login'); //more code... } catch (Exception $exception) { $this->messenger->addError($exception->getMessage(), 'user-login'); //more code... } Testing if an e-mail message is valid After sending an e-mail you can check if the message was valid or not. The $this->mailService->send()->isValid() method call will return a boolean value. If the returned result is true , the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using $this->mailService->send()->getMessage() . Using the below logic will let you determine if a message was valid or not and log it. You can implement your own custom error logging logic. $result = $this->mailService->send(); if (! $result->isValid()) { //log the error error_log($result->getMessage()); } Invalid e-mail messages will not be sent. Logging outgoing emails Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {\"subject\":\"Test subject\",\"to\":[\"Test Account <test@dotkernel.com>\"],\"cc\":[],\"bcc\":[]} . In order to enable it, make sure that your config/autoload/mail.local.php has the below log configuration under the dot_mail key: <?php return [ 'dot_mail' => [ ... 'log' => [ 'sent' => getcwd() . '/log/mail/sent.log' ] ] ]; To disable it, set the value of sent to null .","title":"Home"},{"location":"#dot-mail","text":"[!IMPORTANT] dot-mail is a wrapper on top of symfony mailer","title":"dot-mail"},{"location":"#dot-mail-badges","text":"","title":"dot-mail badges"},{"location":"#installation","text":"Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail","title":"Installation"},{"location":"#configuration","text":"","title":"Configuration"},{"location":"v4/configuration/","text":"Configuration Register dot-mail in you project by adding Dot\\Mail\\ConfigProvider::class to your configuration aggregator (to config/config.php for example). After registering the ConfigProvider copy the configuration file config/mail.global.php.dist into your project's config/autoload/ directory as mail.global.php . The resulting mail.global.php contains the necessary configurations for all available transport types, message options and logging options in one place. The config file provides a set of default values available to all mails under the dot-mail.default key. Many of these options can be programmatically set when sending the actual email. An example of this is the dot-mail.default.message_options key, which can be filled in with default message values to be available to all emails. When sending the actual email, these values can be overwritten by using an available \"setter\" function, supplemented by using \"add\" functions or simply left as the default. // setter will overwrite existing destination email $this->mailService->getMessage()->setTo(\"receiver@email.com\"); // existing destination email kept, new destination email added alongside it $this->mailService->getMessage()->addTo(\"receiver@email.com\"); Transport configuration dot-mail uses the transport key under the main dot_mail configuration key to select the email transport. It has four email transport classes available by default ( Sendmail , Smtp , File , InMemory ), one of which is to be added under the dot_mail.transport key for use. Both Sendmail and InMemory transports requires no specific configuration to use by default. Sending email with the Smtp transport requires valid data for the values under dot-mail.default.smtp_options , which is only used in this case. The dot_mail.default.save_sent_message_folder key may be uncommented when using this transport, saving a copy of all sent email to a certain IMAP folder. Using Laminas\\Mail\\Transport\\File as the transport will require uncommenting the dot-mail.default.file_options key. The configured path must be a writable directory 'file_options' => [ 'path' => 'data/mail/output', //'callback' => null, ], If no callback is provided to specify a new file name format, the messages will be saved in files using the default format set in Laminas\\Mail\\Transport\\FileOptions . // Example of a custom format 'callback' => static fn() => sprintf('DotMail%d_%s.log', time(), 'customFormat'), Logging configuration Uncommenting the dot-mail.log key will save a copy of all sent emails' subject, recipient addresses, cc and bcc addresses alongside a timestamp. In order to enable it, make sure that your mail.local.php has the below log configuration under the dot_mail key: <?php return [ 'dot_mail' => [ ... 'log' => [ 'sent' => getcwd() . '/log/mail/sent.log' ] ] ]; To disable it, set the value of sent to null .","title":"Configuration"},{"location":"v4/configuration/#configuration","text":"Register dot-mail in you project by adding Dot\\Mail\\ConfigProvider::class to your configuration aggregator (to config/config.php for example). After registering the ConfigProvider copy the configuration file config/mail.global.php.dist into your project's config/autoload/ directory as mail.global.php . The resulting mail.global.php contains the necessary configurations for all available transport types, message options and logging options in one place. The config file provides a set of default values available to all mails under the dot-mail.default key. Many of these options can be programmatically set when sending the actual email. An example of this is the dot-mail.default.message_options key, which can be filled in with default message values to be available to all emails. When sending the actual email, these values can be overwritten by using an available \"setter\" function, supplemented by using \"add\" functions or simply left as the default. // setter will overwrite existing destination email $this->mailService->getMessage()->setTo(\"receiver@email.com\"); // existing destination email kept, new destination email added alongside it $this->mailService->getMessage()->addTo(\"receiver@email.com\");","title":"Configuration"},{"location":"v4/configuration/#transport-configuration","text":"dot-mail uses the transport key under the main dot_mail configuration key to select the email transport. It has four email transport classes available by default ( Sendmail , Smtp , File , InMemory ), one of which is to be added under the dot_mail.transport key for use. Both Sendmail and InMemory transports requires no specific configuration to use by default. Sending email with the Smtp transport requires valid data for the values under dot-mail.default.smtp_options , which is only used in this case. The dot_mail.default.save_sent_message_folder key may be uncommented when using this transport, saving a copy of all sent email to a certain IMAP folder. Using Laminas\\Mail\\Transport\\File as the transport will require uncommenting the dot-mail.default.file_options key. The configured path must be a writable directory 'file_options' => [ 'path' => 'data/mail/output', //'callback' => null, ], If no callback is provided to specify a new file name format, the messages will be saved in files using the default format set in Laminas\\Mail\\Transport\\FileOptions . // Example of a custom format 'callback' => static fn() => sprintf('DotMail%d_%s.log', time(), 'customFormat'),","title":"Transport configuration"},{"location":"v4/configuration/#logging-configuration","text":"Uncommenting the dot-mail.log key will save a copy of all sent emails' subject, recipient addresses, cc and bcc addresses alongside a timestamp. In order to enable it, make sure that your mail.local.php has the below log configuration under the dot_mail key: <?php return [ 'dot_mail' => [ ... 'log' => [ 'sent' => getcwd() . '/log/mail/sent.log' ] ] ]; To disable it, set the value of sent to null .","title":"Logging configuration"},{"location":"v4/installation/","text":"Installation Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail","title":"Installation"},{"location":"v4/installation/#installation","text":"Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail","title":"Installation"},{"location":"v4/overview/","text":"Overview dot-mail is a wrapper on top of laminas-mail Extra features the option to log the results of the mailing process it provides the developer with more information and greater control.","title":"Overview"},{"location":"v4/overview/#overview","text":"dot-mail is a wrapper on top of laminas-mail","title":"Overview"},{"location":"v4/overview/#extra-features","text":"the option to log the results of the mailing process it provides the developer with more information and greater control.","title":"Extra features"},{"location":"v4/transports/","text":"Transports dot-mail can use any transport class that implements Laminas\\Mail\\Transport\\TransportInterface , with the four standard transports available being: Laminas\\Mail\\Transport\\Sendmail - the default transport set in the config file Laminas\\Mail\\Transport\\Smtp Laminas\\Mail\\Transport\\File Laminas\\Mail\\Transport\\InMemory Feel free to use any custom transport you desire, provided it implements the mentioned TransportInterface . Sendmail is a wrapper over PHP's mail() function, and as such has a different behaviour on Windows than on nix systems. Using sendmail on Windows will not work in combination with * addBcc() . Note: emails sent using the sendmail transport will be more often delivered to SPAM. Smtp connects to the configured SMTP host in order to handle sending emails. Saving a copy of an outgoing mail into a folder is possible for this transport only, and is done by uncommenting save_sent_message_folder in the config file mail.local.php under dot_mail.default . Common folder names are INBOX , INBOX.Archive , INBOX.Drafts , INBOX.Sent , INBOX.Spam , INBOX.Trash . If you have MailService available in your class, you can call $this->mailService->getFolderGlobalNames() to list the folder global names for the email you are using. Multiple folders can be added to the save_sent_message_folder key to save a copy of the outgoing email in each folder. File writes each message individually in a file named after the configured format, placed in the configured directory. From here the files may be used for sending via another transport mechanism, or simply as logs. InMemory saves the message in memory, allowing access to the last \"sent\" message via the getLastMessage() function. As the email is not sent, this transport can be helpful in development, with the access to the message being potentially useful in tests as well $this->mailService->setBody('First email body'); $this->mailService->setSubject('First email subject'); $this->mailService->getMessage()->setTo('email@example.com'); // The email is not sent to the email, instead it is stored in memory $this->mailService->send(); $this->mailService->setBody('Second email body'); $this->mailService->setSubject('Second email subject'); $this->mailService->getMessage()->setTo('email@example.com'); // The email is not sent to the email either, it overwrites the previously \"sent\" email in memory $this->mailService->send(); // Returns the second email's Laminas\\Mail\\Message object from memory $lastMessage = $this->mailService()->getTransport()->getLastMessage();","title":"Transports"},{"location":"v4/transports/#transports","text":"dot-mail can use any transport class that implements Laminas\\Mail\\Transport\\TransportInterface , with the four standard transports available being: Laminas\\Mail\\Transport\\Sendmail - the default transport set in the config file Laminas\\Mail\\Transport\\Smtp Laminas\\Mail\\Transport\\File Laminas\\Mail\\Transport\\InMemory Feel free to use any custom transport you desire, provided it implements the mentioned TransportInterface . Sendmail is a wrapper over PHP's mail() function, and as such has a different behaviour on Windows than on nix systems. Using sendmail on Windows will not work in combination with * addBcc() . Note: emails sent using the sendmail transport will be more often delivered to SPAM. Smtp connects to the configured SMTP host in order to handle sending emails. Saving a copy of an outgoing mail into a folder is possible for this transport only, and is done by uncommenting save_sent_message_folder in the config file mail.local.php under dot_mail.default . Common folder names are INBOX , INBOX.Archive , INBOX.Drafts , INBOX.Sent , INBOX.Spam , INBOX.Trash . If you have MailService available in your class, you can call $this->mailService->getFolderGlobalNames() to list the folder global names for the email you are using. Multiple folders can be added to the save_sent_message_folder key to save a copy of the outgoing email in each folder. File writes each message individually in a file named after the configured format, placed in the configured directory. From here the files may be used for sending via another transport mechanism, or simply as logs. InMemory saves the message in memory, allowing access to the last \"sent\" message via the getLastMessage() function. As the email is not sent, this transport can be helpful in development, with the access to the message being potentially useful in tests as well $this->mailService->setBody('First email body'); $this->mailService->setSubject('First email subject'); $this->mailService->getMessage()->setTo('email@example.com'); // The email is not sent to the email, instead it is stored in memory $this->mailService->send(); $this->mailService->setBody('Second email body'); $this->mailService->setSubject('Second email subject'); $this->mailService->getMessage()->setTo('email@example.com'); // The email is not sent to the email either, it overwrites the previously \"sent\" email in memory $this->mailService->send(); // Returns the second email's Laminas\\Mail\\Message object from memory $lastMessage = $this->mailService()->getTransport()->getLastMessage();","title":"Transports"},{"location":"v4/usage/","text":"Usage Sending an e-mail Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. Note that addTo is only one of the methods available for the Message class returned by getMessage() . Other useful methods that were not included in the example are addCc() , addBcc() , addReplyTo() . The returned type is boolean, but if the isValid() method is removed, the returned type becomes MailResult which allows the use of getMessage() for a more detailed error message. See the Testing if an e-mail message is valid section below. public function sendBasicMail() { $this->mailService->setBody('Email body'); $this->mailService->setSubject('Email subject'); $this->mailService->getMessage()->addTo('email@example.com', 'User name'); $this->mailService->getMessage()->setEncoding('utf-8'); return $this->mailService->send()->isValid(); } It's optional, but recommended to call the above function in a try-catch block to display helpful error messages. The next example calls the sendBasicMail function from within UserController , but you can implement it in other controllers, just make sure that the controller's construct also includes the FlashMessenger parameter $messenger . try { $this->userService->sendBasicMail(); $this->messenger->addSuccess('The mail was sent successfully', 'user-login'); //more code... } catch (Exception $exception) { $this->messenger->addError($exception->getMessage(), 'user-login'); //more code... } Testing if an e-mail message is valid After sending an e-mail you can check if the message was valid or not. The $this->mailService->send()->isValid() method call will return a boolean value. If the returned result is true , the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using $this->mailService->send()->getMessage() . Using the below logic will let you determine if a message was valid or not and log it. You can implement your own custom error logging logic. $result = $this->mailService->send(); if (! $result->isValid()) { //log the error error_log($result->getMessage()); } Invalid e-mail messages will not be sent. Logging outgoing emails Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {\"subject\":\"Test subject\",\"to\":[\"Test Account <test@dotkernel.com>\"],\"cc\":[],\"bcc\":[]} . Each email is saved via the dotkernel/dot-log component in the shown JSON format, in the single file configured under the dot-mail.log.sent key. To disable it, set the value of dot-mail.log.sent to null . Transport usage Transports","title":"Usage"},{"location":"v4/usage/#usage","text":"","title":"Usage"},{"location":"v4/usage/#sending-an-e-mail","text":"Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. Note that addTo is only one of the methods available for the Message class returned by getMessage() . Other useful methods that were not included in the example are addCc() , addBcc() , addReplyTo() . The returned type is boolean, but if the isValid() method is removed, the returned type becomes MailResult which allows the use of getMessage() for a more detailed error message. See the Testing if an e-mail message is valid section below. public function sendBasicMail() { $this->mailService->setBody('Email body'); $this->mailService->setSubject('Email subject'); $this->mailService->getMessage()->addTo('email@example.com', 'User name'); $this->mailService->getMessage()->setEncoding('utf-8'); return $this->mailService->send()->isValid(); } It's optional, but recommended to call the above function in a try-catch block to display helpful error messages. The next example calls the sendBasicMail function from within UserController , but you can implement it in other controllers, just make sure that the controller's construct also includes the FlashMessenger parameter $messenger . try { $this->userService->sendBasicMail(); $this->messenger->addSuccess('The mail was sent successfully', 'user-login'); //more code... } catch (Exception $exception) { $this->messenger->addError($exception->getMessage(), 'user-login'); //more code... }","title":"Sending an e-mail"},{"location":"v4/usage/#testing-if-an-e-mail-message-is-valid","text":"After sending an e-mail you can check if the message was valid or not. The $this->mailService->send()->isValid() method call will return a boolean value. If the returned result is true , the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using $this->mailService->send()->getMessage() . Using the below logic will let you determine if a message was valid or not and log it. You can implement your own custom error logging logic. $result = $this->mailService->send(); if (! $result->isValid()) { //log the error error_log($result->getMessage()); } Invalid e-mail messages will not be sent.","title":"Testing if an e-mail message is valid"},{"location":"v4/usage/#logging-outgoing-emails","text":"Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {\"subject\":\"Test subject\",\"to\":[\"Test Account <test@dotkernel.com>\"],\"cc\":[],\"bcc\":[]} . Each email is saved via the dotkernel/dot-log component in the shown JSON format, in the single file configured under the dot-mail.log.sent key. To disable it, set the value of dot-mail.log.sent to null .","title":"Logging outgoing emails"},{"location":"v4/usage/#transport-usage","text":"Transports","title":"Transport usage"},{"location":"v5/configuration/","text":"Configuration Register dot-mail in you project by adding Dot\\Mail\\ConfigProvider::class to your configuration aggregator (to config/config.php for example). After registering the ConfigProvider copy the configuration file config/mail.global.php.dist into your project's config/autoload/ directory as mail.global.php . The resulting mail.global.php contains the necessary configurations for all available transport types, message options and logging options in one place. The config file provides a set of default values available to all mails under the dot-mail.default key. Many of these options can be programmatically set when sending the actual email. An example of this is the dot-mail.default.message_options key, which can be filled in with default message values to be available to all emails. When sending the actual email, these values can be overwritten by using an available \"setter\" function, supplemented by using \"add\" functions or simply left as the default. // setter will overwrite existing destination email $this->mailService->getMessage()->setTo(\"receiver@email.com\"); // existing destination email kept, new destination email added alongside it $this->mailService->getMessage()->addTo(\"receiver@email.com\"); Transport configuration dot-mail uses the transport key under the main dot_mail configuration key to select the email transport. It has four email transport classes available by default ( SmtpTransport ), one of which is to be added under the dot_mail.transport key for use. Sending email with the Smtp transport requires valid data for the values under dot-mail.default.smtp_options , which is only used in this case. The configured path must be a writable directory Logging configuration Uncommenting the dot-mail.log key will save a copy of all sent emails' subject, recipient addresses, cc and bcc addresses alongside a timestamp. In order to enable it, make sure that your mail.local.php has the below log configuration under the dot_mail key: <?php return [ 'dot_mail' => [ ... 'log' => [ 'sent' => getcwd() . '/log/mail/sent.log' ] ] ]; To disable it, set the value of sent to null .","title":"Configuration"},{"location":"v5/configuration/#configuration","text":"Register dot-mail in you project by adding Dot\\Mail\\ConfigProvider::class to your configuration aggregator (to config/config.php for example). After registering the ConfigProvider copy the configuration file config/mail.global.php.dist into your project's config/autoload/ directory as mail.global.php . The resulting mail.global.php contains the necessary configurations for all available transport types, message options and logging options in one place. The config file provides a set of default values available to all mails under the dot-mail.default key. Many of these options can be programmatically set when sending the actual email. An example of this is the dot-mail.default.message_options key, which can be filled in with default message values to be available to all emails. When sending the actual email, these values can be overwritten by using an available \"setter\" function, supplemented by using \"add\" functions or simply left as the default. // setter will overwrite existing destination email $this->mailService->getMessage()->setTo(\"receiver@email.com\"); // existing destination email kept, new destination email added alongside it $this->mailService->getMessage()->addTo(\"receiver@email.com\");","title":"Configuration"},{"location":"v5/configuration/#transport-configuration","text":"dot-mail uses the transport key under the main dot_mail configuration key to select the email transport. It has four email transport classes available by default ( SmtpTransport ), one of which is to be added under the dot_mail.transport key for use. Sending email with the Smtp transport requires valid data for the values under dot-mail.default.smtp_options , which is only used in this case. The configured path must be a writable directory","title":"Transport configuration"},{"location":"v5/configuration/#logging-configuration","text":"Uncommenting the dot-mail.log key will save a copy of all sent emails' subject, recipient addresses, cc and bcc addresses alongside a timestamp. In order to enable it, make sure that your mail.local.php has the below log configuration under the dot_mail key: <?php return [ 'dot_mail' => [ ... 'log' => [ 'sent' => getcwd() . '/log/mail/sent.log' ] ] ]; To disable it, set the value of sent to null .","title":"Logging configuration"},{"location":"v5/installation/","text":"Installation Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail","title":"Installation"},{"location":"v5/installation/#installation","text":"Install dotkernel/dot-mail by executing the following Composer command: composer require dotkernel/dot-mail","title":"Installation"},{"location":"v5/overview/","text":"Overview dot-mail is a wrapper on top of symfony mailer Extra features the option to log the results of the mailing process it provides the developer with more information and greater control.","title":"Overview"},{"location":"v5/overview/#overview","text":"dot-mail is a wrapper on top of symfony mailer","title":"Overview"},{"location":"v5/overview/#extra-features","text":"the option to log the results of the mailing process it provides the developer with more information and greater control.","title":"Extra features"},{"location":"v5/transports/","text":"Transports dot-mail can use any transport class that implements Symfony\\Component\\Mailer\\Transport\\TransportInterface , with the standard transport available being: Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport, Symfony\\Component\\Mailer\\Transport\\SendmailTransport, Feel free to use any custom transport you desire, provided it implements the mentioned TransportInterface . PHP's mail() function is a wrapper over Sendmail , and as such has a different behaviour on Windows than on nix systems. Using sendmail on Windows will not work in combination with * addBcc() . Note: emails sent using the sendmail transport will be more often delivered to SPAM. Smtp connects to the configured SMTP host in order to handle sending emails.","title":"Transports"},{"location":"v5/transports/#transports","text":"dot-mail can use any transport class that implements Symfony\\Component\\Mailer\\Transport\\TransportInterface , with the standard transport available being: Symfony\\Component\\Mailer\\Transport\\Smtp\\SmtpTransport, Symfony\\Component\\Mailer\\Transport\\SendmailTransport, Feel free to use any custom transport you desire, provided it implements the mentioned TransportInterface . PHP's mail() function is a wrapper over Sendmail , and as such has a different behaviour on Windows than on nix systems. Using sendmail on Windows will not work in combination with * addBcc() . Note: emails sent using the sendmail transport will be more often delivered to SPAM. Smtp connects to the configured SMTP host in order to handle sending emails.","title":"Transports"},{"location":"v5/usage/","text":"Usage Sending an e-mail Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. Note that addTo is only one of the methods available for the Message class returned by getMessage() . Other useful methods that were not included in the example are addCc() , addBcc() , addReplyTo() . The returned type is boolean, but if the isValid() method is removed, the returned type becomes MailResult which allows the use of getMessage() for a more detailed error message. See the Testing if an e-mail message is valid section below. public function sendBasicMail() { $this->mailService->setBody('Email body'); $this->mailService->setSubject('Email subject'); $this->mailService->getMessage()->addTo('email@example.com', 'User name'); $this->mailService->getMessage()->setEncoding('utf-8'); return $this->mailService->send()->isValid(); } It's optional, but recommended to call the above function in a try-catch block to display helpful error messages. The next example calls the sendBasicMail function from within UserController , but you can implement it in other controllers, just make sure that the controller's construct also includes the FlashMessenger parameter $messenger . try { $this->userService->sendBasicMail(); $this->messenger->addSuccess('The mail was sent successfully', 'user-login'); //more code... } catch (Exception $exception) { $this->messenger->addError($exception->getMessage(), 'user-login'); //more code... } Testing if an e-mail message is valid After sending an e-mail you can check if the message was valid or not. The $this->mailService->send()->isValid() method call will return a boolean value. If the returned result is true , the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using $this->mailService->send()->getMessage() . Using the below logic will let you determine if a message was valid or not and log it. You can implement your own custom error logging logic. $result = $this->mailService->send(); if (! $result->isValid()) { //log the error error_log($result->getMessage()); } Invalid e-mail messages will not be sent. Logging outgoing emails Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {\"subject\":\"Test subject\",\"to\":[\"Test Account <test@dotkernel.com>\"],\"cc\":[],\"bcc\":[]} . Each email is saved via the dotkernel/dot-log component in the shown JSON format, in the single file configured under the dot-mail.log.sent key. To disable it, set the value of dot-mail.log.sent to null . Transport usage Transports","title":"Usage"},{"location":"v5/usage/#usage","text":"","title":"Usage"},{"location":"v5/usage/#sending-an-e-mail","text":"Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body. Note that addTo is only one of the methods available for the Message class returned by getMessage() . Other useful methods that were not included in the example are addCc() , addBcc() , addReplyTo() . The returned type is boolean, but if the isValid() method is removed, the returned type becomes MailResult which allows the use of getMessage() for a more detailed error message. See the Testing if an e-mail message is valid section below. public function sendBasicMail() { $this->mailService->setBody('Email body'); $this->mailService->setSubject('Email subject'); $this->mailService->getMessage()->addTo('email@example.com', 'User name'); $this->mailService->getMessage()->setEncoding('utf-8'); return $this->mailService->send()->isValid(); } It's optional, but recommended to call the above function in a try-catch block to display helpful error messages. The next example calls the sendBasicMail function from within UserController , but you can implement it in other controllers, just make sure that the controller's construct also includes the FlashMessenger parameter $messenger . try { $this->userService->sendBasicMail(); $this->messenger->addSuccess('The mail was sent successfully', 'user-login'); //more code... } catch (Exception $exception) { $this->messenger->addError($exception->getMessage(), 'user-login'); //more code... }","title":"Sending an e-mail"},{"location":"v5/usage/#testing-if-an-e-mail-message-is-valid","text":"After sending an e-mail you can check if the message was valid or not. The $this->mailService->send()->isValid() method call will return a boolean value. If the returned result is true , the e-mail was valid, otherwise the e-mail was invalid. In case your e-mail was invalid, you can check for any errors using $this->mailService->send()->getMessage() . Using the below logic will let you determine if a message was valid or not and log it. You can implement your own custom error logging logic. $result = $this->mailService->send(); if (! $result->isValid()) { //log the error error_log($result->getMessage()); } Invalid e-mail messages will not be sent.","title":"Testing if an e-mail message is valid"},{"location":"v5/usage/#logging-outgoing-emails","text":"Optionally, you can keep a log of each successfully sent email. This might be useful when you need to know if/when a specific email has been sent out to a recipient. Logs are stored in the following format: [YYYY-MM-DD HH:MM:SS]: {\"subject\":\"Test subject\",\"to\":[\"Test Account <test@dotkernel.com>\"],\"cc\":[],\"bcc\":[]} . Each email is saved via the dotkernel/dot-log component in the shown JSON format, in the single file configured under the dot-mail.log.sent key. To disable it, set the value of dot-mail.log.sent to null .","title":"Logging outgoing emails"},{"location":"v5/usage/#transport-usage","text":"Transports","title":"Transport usage"}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml index eeac432..b10bf26 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -2,46 +2,46 @@ https://docs.dotkernel.org/dot-mail/ - 2024-11-18 + 2024-11-19 https://docs.dotkernel.org/dot-mail/v4/configuration/ - 2024-11-18 + 2024-11-19 https://docs.dotkernel.org/dot-mail/v4/installation/ - 2024-11-18 + 2024-11-19 https://docs.dotkernel.org/dot-mail/v4/overview/ - 2024-11-18 + 2024-11-19 https://docs.dotkernel.org/dot-mail/v4/transports/ - 2024-11-18 + 2024-11-19 https://docs.dotkernel.org/dot-mail/v4/usage/ - 2024-11-18 + 2024-11-19 https://docs.dotkernel.org/dot-mail/v5/configuration/ - 2024-11-18 + 2024-11-19 https://docs.dotkernel.org/dot-mail/v5/installation/ - 2024-11-18 + 2024-11-19 https://docs.dotkernel.org/dot-mail/v5/overview/ - 2024-11-18 + 2024-11-19 https://docs.dotkernel.org/dot-mail/v5/transports/ - 2024-11-18 + 2024-11-19 https://docs.dotkernel.org/dot-mail/v5/usage/ - 2024-11-18 + 2024-11-19 \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index 0f18152..ff3f783 100644 Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ diff --git a/v5/configuration/index.html b/v5/configuration/index.html index 23ee62e..c7d9af1 100644 --- a/v5/configuration/index.html +++ b/v5/configuration/index.html @@ -318,10 +318,6 @@

Transport configuration

The configured path must be a writable directory

-
'file_options' => [
-    'path' => 'data/mail/output',
-    //'callback' => null,
-],

Logging configuration

Uncommenting the dot-mail.log key will save a copy of all sent emails' subject, recipient addresses, cc and bcc addresses alongside a timestamp. In order to enable it, make sure that your mail.local.php has the below log configuration under the dot_mail key:

diff --git a/v5/transports/index.html b/v5/transports/index.html index 764dfd5..785ffcb 100644 --- a/v5/transports/index.html +++ b/v5/transports/index.html @@ -293,7 +293,7 @@

Transports

Feel free to use any custom transport you desire, provided it implements the mentioned TransportInterface.

-

Sendmail is a wrapper over PHP's mail() function, and as such has a different behaviour on Windows than on nix systems. Using sendmail on Windows will not work in combination with* addBcc().

+

PHP's mail() function is a wrapper over Sendmail, and as such has a different behaviour on Windows than on nix systems. Using sendmail on Windows will not work in combination with* addBcc().