{"id":20103162,"url":"https://github.com/dotkernel/dot-mail","last_synced_at":"2025-05-06T08:31:10.846Z","repository":{"id":38430890,"uuid":"68154290","full_name":"dotkernel/dot-mail","owner":"dotkernel","description":"DotKernel mail component based on laminas-mail","archived":false,"fork":false,"pushed_at":"2025-01-13T14:38:20.000Z","size":264,"stargazers_count":9,"open_issues_count":6,"forks_count":3,"subscribers_count":5,"default_branch":"5.0","last_synced_at":"2025-01-21T13:40:25.471Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.dotkernel.org/dot-mail/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dotkernel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-13T23:01:31.000Z","updated_at":"2025-01-13T14:34:57.000Z","dependencies_parsed_at":"2024-05-03T19:57:50.652Z","dependency_job_id":"9364a03a-7907-426e-bfbc-a6acdac77f5a","html_url":"https://github.com/dotkernel/dot-mail","commit_stats":{"total_commits":65,"total_committers":11,"mean_commits":5.909090909090909,"dds":0.6923076923076923,"last_synced_commit":"b5ab919ee6265fcc65c3737c7100dc0d50d5eb52"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotkernel%2Fdot-mail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotkernel%2Fdot-mail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotkernel%2Fdot-mail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotkernel%2Fdot-mail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotkernel","download_url":"https://codeload.github.com/dotkernel/dot-mail/tar.gz/refs/heads/5.0","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252648573,"owners_count":21782405,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T17:34:30.425Z","updated_at":"2025-05-06T08:31:10.840Z","avatar_url":"https://github.com/dotkernel.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dot-mail\n\n\u003e [!IMPORTANT]\n\u003e dot-mail is a wrapper on top of [symfony mailer](https://github.com/symfony/mailer)\n\n## dot-mail badges\n\n![OSS Lifecycle](https://img.shields.io/osslifecycle/dotkernel/dot-mail)\n![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-mail/5.2.1)\n\n[![GitHub issues](https://img.shields.io/github/issues/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/issues)\n[![GitHub forks](https://img.shields.io/github/forks/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/network)\n[![GitHub stars](https://img.shields.io/github/stars/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/stargazers)\n[![GitHub license](https://img.shields.io/github/license/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/blob/5.0/LICENSE.md)\n\n[![Build Static](https://github.com/dotkernel/dot-mail/actions/workflows/continuous-integration.yml/badge.svg?branch=5.0)](https://github.com/dotkernel/dot-mail/actions/workflows/continuous-integration.yml)\n[![codecov](https://codecov.io/gh/dotkernel/dot-mail/branch/5.0/graph/badge.svg?token=G51NEHYKD3)](https://codecov.io/gh/dotkernel/dot-mail)\n\n## Installation\n\nInstall `dotkernel/dot-mail` by executing the following Composer command:\n\n```shell\ncomposer require dotkernel/dot-mail\n```\n\n## Configuration\n\n### Mail - Sendmail\n\nIf your server has Sendmail installed, update the `config/autoload/mail.local.php.dist` file by setting the `transport` key like below\n\n```php\n\u003c?php\nreturn [\n    'dot_mail' =\u003e [\n        'default' =\u003e [\n            //...\n            'transport' =\u003e 'sendmail',\n            //...\n        ]\n    ]\n]\n```\n\n### Mail - ESMTP\n\nIf 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.\n\nUnder `message_options` key:\n\n- `from` - email address from whom users will receive emails\n\nUnder `smtp_options` key:\n\n- `host` - the mail server's hostname or IP address\n- `port` - the mail server's port\n- `connection_config` - fill in the `username` and `password` keys with the login details of the email used in `from` above\n- if you want to disable auto_tls set `tls` key to false\n\n\u003e Note: all other keys can be left as is.\n\n```php\n\u003c?php\nreturn [\n    'dot_mail' =\u003e [\n        'default' =\u003e [\n            //...\n            'transport' =\u003e 'esmtp'\n            'message_options' =\u003e [\n                'from' =\u003e '',\n                //...\n            ],\n            'smtp_options' =\u003e [\n                'host' =\u003e '',\n                'port' =\u003e 25,\n                'connection_config' =\u003e [\n                    'username' =\u003e '',\n                    'password' =\u003e '',\n                    'tls' =\u003e null,\n                ]\n            ]\n            //...\n        ]\n    ]\n]\n```\n\nIn `config/autoload/local.php` add under `contact` =\u003e `message_receivers` =\u003e `to` key *string* values with the emails that should receive contact messages\n\n\u003e Note: **Please add at least 1 email address in order for contact message to reach someone**\n\nAlso feel free to add as many cc as you want under `contact` =\u003e `message_receivers` =\u003e `cc` key\n\n### Sending an e-mail\n\nBelow 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.\n\nNote 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()`.\n\nThe 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.\n\n```php\npublic function sendBasicMail()\n{\n    $this-\u003emailService-\u003esetBody('Email body');\n    $this-\u003emailService-\u003esetSubject('Email subject');\n    $this-\u003emailService-\u003egetMessage()-\u003eaddTo('email@example.com', 'User name');\n    $this-\u003emailService-\u003egetMessage()-\u003esetEncoding('utf-8');\n    return $this-\u003emailService-\u003esend()-\u003eisValid();\n}\n```\n\nIt'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`.\n\n```php\ntry {\n    $this-\u003euserService-\u003esendBasicMail();\n    $this-\u003emessenger-\u003eaddSuccess('The mail was sent successfully', 'user-login');\n    //more code...\n} catch (Exception $exception) {\n    $this-\u003emessenger-\u003eaddError($exception-\u003egetMessage(), 'user-login');\n    //more code...\n}\n```\n\n### Testing if an e-mail message is valid\n\nAfter sending an e-mail you can check if the message was valid or not.\nThe `$this-\u003emailService-\u003esend()-\u003eisValid()` method call will return a boolean value.\nIf the returned result is `true`, the e-mail was valid, otherwise the e-mail was invalid.\nIn case your e-mail was invalid, you can check for any errors using `$this-\u003emailService-\u003esend()-\u003egetMessage()`.\n\nUsing the below logic will let you determine if a message was valid or not and log it.\nYou can implement your own custom error logging logic.\n\n```php\n$result = $this-\u003emailService-\u003esend();\nif (! $result-\u003eisValid()) {\n    //log the error\n    error_log($result-\u003egetMessage());\n}\n```\n\n\u003e Invalid e-mail messages will not be sent.\n\n### Logging outgoing emails\n\nOptionally, 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.\n\nLogs are stored in the following format:\n\n```text\n[YYYY-MM-DD HH:MM:SS]: {\"subject\":\"Test subject\",\"to\":[\"Test Account \u003ctest@dotkernel.com\u003e\"],\"cc\":[],\"bcc\":[]}.\n```\n\nIn order to enable it, make sure that your `config/autoload/mail.local.php` has the below `log` configuration under the `dot_mail` key:\n\n```php\n\u003c?php\n\nreturn [\n    'dot_mail' =\u003e [\n        ...\n        'log' =\u003e [\n            'sent' =\u003e getcwd() . '/log/mail/sent.log'\n        ]\n    ]\n];\n```\n\nTo disable it, set the value of `sent` to `null`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotkernel%2Fdot-mail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotkernel%2Fdot-mail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotkernel%2Fdot-mail/lists"}