{"id":13695673,"url":"https://github.com/playframework/play-mailer","last_synced_at":"2025-04-07T20:09:03.470Z","repository":{"id":22568165,"uuid":"25909546","full_name":"playframework/play-mailer","owner":"playframework","description":"Play mailer plugin","archived":false,"fork":false,"pushed_at":"2024-10-08T20:06:09.000Z","size":905,"stargazers_count":250,"open_issues_count":23,"forks_count":74,"subscribers_count":24,"default_branch":"main","last_synced_at":"2024-10-30T05:57:45.148Z","etag":null,"topics":["email-sender","java","mailer","play-framework","playframework","scala"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/playframework.png","metadata":{"funding":{"github":["playframework"],"open_collective":"playframework"},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-10-29T07:30:48.000Z","updated_at":"2024-10-21T15:36:16.000Z","dependencies_parsed_at":"2023-01-13T22:04:22.920Z","dependency_job_id":"b2434b81-4aef-48a7-9c14-bddaabdd117b","html_url":"https://github.com/playframework/play-mailer","commit_stats":{"total_commits":540,"total_committers":69,"mean_commits":7.826086956521739,"dds":0.7851851851851852,"last_synced_commit":"988237e861b28caa8b9fbea2d23085718a3f78ab"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playframework%2Fplay-mailer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playframework%2Fplay-mailer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playframework%2Fplay-mailer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playframework%2Fplay-mailer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/playframework","download_url":"https://codeload.github.com/playframework/play-mailer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332214,"owners_count":20921850,"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":["email-sender","java","mailer","play-framework","playframework","scala"],"created_at":"2024-08-02T18:00:32.154Z","updated_at":"2025-04-07T20:09:03.454Z","avatar_url":"https://github.com/playframework.png","language":"Scala","readme":"# Play Mailer\n\n[![Twitter Follow](https://img.shields.io/twitter/follow/playframework?label=follow\u0026style=flat\u0026logo=twitter\u0026color=brightgreen)](https://twitter.com/playframework)\n[![Discord](https://img.shields.io/discord/931647755942776882?logo=discord\u0026logoColor=white)](https://discord.gg/g5s2vtZ4Fa)\n[![GitHub Discussions](https://img.shields.io/github/discussions/playframework/playframework?\u0026logo=github\u0026color=brightgreen)](https://github.com/playframework/playframework/discussions)\n[![StackOverflow](https://img.shields.io/static/v1?label=stackoverflow\u0026logo=stackoverflow\u0026logoColor=fe7a16\u0026color=brightgreen\u0026message=playframework)](https://stackoverflow.com/tags/playframework)\n[![YouTube](https://img.shields.io/youtube/channel/views/UCRp6QDm5SDjbIuisUpxV9cg?label=watch\u0026logo=youtube\u0026style=flat\u0026color=brightgreen\u0026logoColor=ff0000)](https://www.youtube.com/channel/UCRp6QDm5SDjbIuisUpxV9cg)\n[![Twitch Status](https://img.shields.io/twitch/status/playframework?logo=twitch\u0026logoColor=white\u0026color=brightgreen\u0026label=live%20stream)](https://www.twitch.tv/playframework)\n[![OpenCollective](https://img.shields.io/opencollective/all/playframework?label=financial%20contributors\u0026logo=open-collective)](https://opencollective.com/playframework)\n\n[![Build Status](https://github.com/playframework/play-mailer/actions/workflows/build-test.yml/badge.svg)](https://github.com/playframework/play-mailer/actions/workflows/build-test.yml)\n[![Maven](https://img.shields.io/maven-central/v/org.playframework/play-mailer_2.13.svg?logo=apache-maven)](https://mvnrepository.com/artifact/org.playframework/play-mailer_2.13)\n[![Repository size](https://img.shields.io/github/repo-size/playframework/play-mailer.svg?logo=git)](https://github.com/playframework/play-mailer)\n[![Scala Steward badge](https://img.shields.io/badge/Scala_Steward-helping-blue.svg?style=flat\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAQCAMAAAARSr4IAAAAVFBMVEUAAACHjojlOy5NWlrKzcYRKjGFjIbp293YycuLa3pYY2LSqql4f3pCUFTgSjNodYRmcXUsPD/NTTbjRS+2jomhgnzNc223cGvZS0HaSD0XLjbaSjElhIr+AAAAAXRSTlMAQObYZgAAAHlJREFUCNdNyosOwyAIhWHAQS1Vt7a77/3fcxxdmv0xwmckutAR1nkm4ggbyEcg/wWmlGLDAA3oL50xi6fk5ffZ3E2E3QfZDCcCN2YtbEWZt+Drc6u6rlqv7Uk0LdKqqr5rk2UCRXOk0vmQKGfc94nOJyQjouF9H/wCc9gECEYfONoAAAAASUVORK5CYII=)](https://scala-steward.org)\n[![Mergify Status](https://img.shields.io/endpoint.svg?url=https://api.mergify.com/v1/badges/playframework/play-mailer\u0026style=flat)](https://mergify.com)\n\nPlay Mailer is a powerful Scala Mailing library. It provides a simple configurable mailer.\n\n## Getting Started\n\nTo get started you add `play-mailer` and `play-mailer-guice` as a dependency in SBT:\n\n```scala\nlibraryDependencies += \"org.playframework\" %% \"play-mailer\" % -version-\nlibraryDependencies += \"org.playframework\" %% \"play-mailer-guice\" % -version-\n\n// Until version 9.x:\nlibraryDependencies += \"com.typesafe.play\" %% \"play-mailer\" % -version-\nlibraryDependencies += \"com.typesafe.play\" %% \"play-mailer-guice\" % -version-\n```\n\n## Versioning\n\nThe Play Mailer plugin supports several different versions of Play.\n\n| Plugin version   | Play version    |\n|------------------|-----------------|\n| 10.x             | 3.0.x           |\n| 9.x              | 2.9.x           |\n| 8.x              | 2.8.x           |\n| 7.x              | 2.7.x           |\n\nSee [GitHub releases](https://github.com/playframework/play-mailer/releases) for the latest versions.\n\nAfter that you need to configure the mailer inside your `application.conf`:\n \n```HOCON\nplay.mailer {\n  host = \"example.com\" // (mandatory)\n  port = 25 // (defaults to 25)\n  ssl = no // (defaults to no)\n  tls = no // (defaults to no)\n  tlsRequired = no // (defaults to no)\n  user = null // (optional)\n  password = null // (optional)\n  debug = no // (defaults to no, to take effect you also need to set the log level to \"DEBUG\" for the \"play.mailer\" logger)\n  timeout = null // (defaults to 60s in milliseconds)\n  connectiontimeout = null // (defaults to 60s in milliseconds)\n  mock = no // (defaults to no, will only log all the email properties instead of sending an email)\n  props {\n    // Additional SMTP properties used by JavaMail. Can override existing configuration keys from above.\n    // A given property will be set for both the \"mail.smtp.*\" and the \"mail.smtps.*\" prefix.\n    // For a list of properties see:\n    // https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html#properties\n\n    // Example:\n    // To set the local host name used in the SMTP HELO or EHLO command:\n    // localhost = 127.0.0.1\n    // Results in \"mail.smtp.localhost=127.0.0.1\" and \"mail.smtps.localhost=127.0.0.1\" in the JavaMail session.\n  }\n}\n```\n\n## Usage\n\n### Scala\n\n#### Runtime Injection\n\nUse the `@Inject` annotation on the constructor, service of your component or controller:\n\n```scala\nimport play.api.libs.mailer._\nimport java.io.File\nimport org.apache.commons.mail2.jakarta.EmailAttachment\nimport jakarta.inject.Inject\n\nclass MailerService @Inject() (mailerClient: MailerClient) {\n\n  def sendEmail = {\n    val cid = \"1234\"\n    val email = Email(\n      \"Simple email\",\n      \"Mister FROM \u003cfrom@email.com\u003e\",\n      Seq(\"Miss TO \u003cto@email.com\u003e\"),\n      // adds attachment\n      attachments = Seq(\n        AttachmentFile(\"attachment.pdf\", new File(\"/some/path/attachment.pdf\")),\n        // adds inline attachment from byte array\n        AttachmentData(\"data.txt\", \"data\".getBytes, \"text/plain\", Some(\"Simple data\"), Some(EmailAttachment.INLINE)),\n        // adds cid attachment\n        AttachmentFile(\"image.jpg\", new File(\"/some/path/image.jpg\"), contentId = Some(cid))\n      ),\n      // sends text, HTML or both...\n      bodyText = Some(\"A text message\"),\n      bodyHtml = Some(s\"\"\"\u003chtml\u003e\u003cbody\u003e\u003cp\u003eAn \u003cb\u003ehtml\u003c/b\u003e message with cid \u003cimg src=\"cid:$cid\"\u003e\u003c/p\u003e\u003c/body\u003e\u003c/html\u003e\"\"\")\n    )\n    mailerClient.send(email)\n  }\n\n}\n```\n\n\u003e Configuration will be retrieved each time mailerClient.send(email) is called. \n\u003e This means that mailer client will always be up to date if you have a dynamic configuration.\n\n#### Compile Time Injection\n\nIf you use Compile time Injection you can remove `libraryDependencies += \"org.playframework\" %% \"play-mailer-guice\" % -version-` from your `build.sbt`.\n\nCreate the MailerService without the `@Inject` annotation:\n\n```scala\nimport play.api.libs.mailer._\n\nclass MyComponent(mailerClient: MailerClient) {\n\n  def sendEmail = {\n     val email = Email(\"Simple email\", \"Mister FROM \u003cfrom@email.com\u003e\", Seq(\"Miss TO \u003cto@email.com\u003e\"), bodyText = Some(\"A text message\"))\n     mailerClient.send(email)\n  }\n}\n```\n\nThen you need to register the `MailerComponents` trait in your main Components file:\n\n```scala\nimport play.api._\nimport play.api.ApplicationLoader.Context\nimport router.Routes\nimport play.api.libs.mailer._\n\nclass MyApplicationLoader extends ApplicationLoader {\n  def load(context: Context) = {\n    new ApplicationComponents(context).application\n  }\n}\n\nclass ApplicationComponents(context: Context) extends BuiltInComponentsFromContext(context) with MailerComponents {\n  lazy val myComponent = new MyComponent(mailerClient)\n  // create your controllers here ...\n  lazy val router = new Routes(...) // inject your controllers here\n  lazy val config = configuration.underlying\n}\n```\n\n#### Dynamic Configuration\n\nBy default the Mailer Plugin will automatically configure the injected instance with the `application.conf`.\n\nIf you want to configure the injected instances from another source, you will need to override the default provider:\n\nCreate a new file named `CustomSMTPConfigurationProvider.scala`:\n\n```scala\nclass CustomSMTPConfigurationProvider extends Provider[SMTPConfiguration] {\n  override def get() = {\n    // Custom configuration\n    new SMTPConfiguration(\"example.org\", 1234)\n  }\n}\n\nclass CustomMailerConfigurationModule extends Module {\n  def bindings(environment: Environment, configuration: Configuration) = Seq(\n    bind[SMTPConfiguration].toProvider[CustomSMTPConfigurationProvider]\n  )\n}\n```\n\nAnd override the default provider inside you `application.conf`:\n\n```HOCON\nplay.modules {\n    # Disable the default provider\n    disabled += \"play.api.libs.mailer.SMTPConfigurationModule\"\n    # Enable the custom provider (see above)\n    enabled += \"controllers.CustomMailerConfigurationModule\"\n}\n```\n\n\u003e The get() method of your CustomSMTPConfigurationProvider will be called multiple times.\n\u003e As a consequence, we recommend that code inside the get() method should be fast.\n\n\n#### Multiple SMTPMailer instances\n\nYou can also use the SMTPMailer constructor to create new instances with custom configuration:\n\n```scala\nval email = Email(\"Simple email\", \"Mister FROM \u003cfrom@email.com\u003e\")\nnew SMTPMailer(SMTPConfiguration(\"example.org\", 1234)).send(email)\nnew SMTPMailer(SMTPConfiguration(\"playframework.com\", 5678)).send(email)\n```\n\n### Java\n\nFor Java you can just create a simple MailerService and Inject the MailerClient into it:\n\n```java\nimport play.libs.mailer.Email;\nimport play.libs.mailer.MailerClient;\nimport jakarta.inject.Inject;\nimport java.io.File;\nimport org.apache.commons.mail.EmailAttachment;\n\npublic class MailerService {\n  @Inject MailerClient mailerClient;\n\n  public void sendEmail() {\n    String cid = \"1234\";\n    Email email = new Email()\n      .setSubject(\"Simple email\")\n      .setFrom(\"Mister FROM \u003cfrom@email.com\u003e\")\n      .addTo(\"Miss TO \u003cto@email.com\u003e\")\n      // adds attachment\n      .addAttachment(\"attachment.pdf\", new File(\"/some/path/attachment.pdf\"))\n      // adds inline attachment from byte array\n      .addAttachment(\"data.txt\", \"data\".getBytes(), \"text/plain\", \"Simple data\", EmailAttachment.INLINE)\n      // adds cid attachment\n      .addAttachment(\"image.jpg\", new File(\"/some/path/image.jpg\"), cid)\n      // sends text, HTML or both...\n      .setBodyText(\"A text message\")\n      .setBodyHtml(\"\u003chtml\u003e\u003cbody\u003e\u003cp\u003eAn \u003cb\u003ehtml\u003c/b\u003e message with cid \u003cimg src=\\\"cid:\" + cid + \"\\\"\u003e\u003c/p\u003e\u003c/body\u003e\u003c/html\u003e\");\n    mailerClient.send(email);\n  }\n}\n```\n\n## Releasing a new version\n\nSee https://github.com/playframework/.github/blob/main/RELEASING.md\n\n## License\n\nThis software is licensed under the Apache 2 license, quoted below.\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n","funding_links":["https://github.com/sponsors/playframework","https://opencollective.com/playframework"],"categories":["Code","Libraries"],"sub_categories":["Library","Others"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplayframework%2Fplay-mailer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplayframework%2Fplay-mailer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplayframework%2Fplay-mailer/lists"}