https://github.com/skn437/skn-spring-mail
A Simple Mail Service Library For Java Reactive Spring Boot
https://github.com/skn437/skn-spring-mail
gradle java library mail maven spring-boot
Last synced: 5 months ago
JSON representation
A Simple Mail Service Library For Java Reactive Spring Boot
- Host: GitHub
- URL: https://github.com/skn437/skn-spring-mail
- Owner: skn437
- License: apache-2.0
- Created: 2024-03-07T07:17:58.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-12-04T11:10:01.000Z (over 1 year ago)
- Last Synced: 2025-04-05T16:51:12.450Z (about 1 year ago)
- Topics: gradle, java, library, mail, maven, spring-boot
- Language: Java
- Homepage: https://javadoc.io/doc/best.skn/skn-spring-mail/latest/index.html
- Size: 157 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SKN Reactive Spring Boot Mail Library
> Java
[](https://central.sonatype.com/artifact/best.skn/skn-spring-mail) [](https://javadoc.io/doc/best.skn/skn-spring-mail/2.4.0) [](https://opensource.org/licenses/Apache-2.0)
## **_JavaDocs:_**
### Read the Javadoc for the main Service APIs
- [MailSenderService API](https://javadoc.io/doc/best.skn/skn-spring-mail/latest/best/skn/mail/services/MailSenderService.html)
- [MailSenderRequestInfo API](https://javadoc.io/doc/best.skn/skn-spring-mail/latest/best/skn/mail/models/MailSenderRequestInfo.html)
- [MailSenderInputStream API](https://javadoc.io/doc/best.skn/skn-spring-mail/latest/best/skn/mail/models/MailSenderInputStream.html)
- [MailSenderHtmlTemplate API](https://javadoc.io/doc/best.skn/skn-spring-mail/latest/best/skn/mail/models/MailSenderHtmlTemplate.html)
## **_Introduction:_**
### This is a simple Java Reactive Spring Boot Library for sending mails
### I made this library so that I can use it in most of my spring boot reactive projects without writing the same codes over and over again
### The main API Classes of this library are `MailSenderService` which has 4 methods to send mails, `MailSenderRequestInfo` which holds the blueprint for `@RequestBody/@RequestPart` annotated params, `MailSenderInputStream` which holds the blueprint for processing proper input stream info & `MailSenderHtmlTemplate` which holds the blueprint for processing proper thymeleaf HTML template info. These APIs are for controllers
## **_Details:_**
### **(1) `MailSenderService` Class:**
- It needs to be instantiated first
- It must be used in controller POST requests
- It has 4 methods to send mails
- These 4 methods throw `MessagingException` if sending error occurs
- 2 methods out of 4 also throw `IOException` if file attachment error occurs
- The modes to send mails:
- Basic Mail (It throws `MessagingException`)
- Basic Mail With Attachment (It throws `MessagingException` & `IOException`)
- Mail With HTML Template (It throws `MessagingException`)
- Mail With HTML Template & Attachment (It throws `MessagingException` & `IOException`)
### **(2) `MailSenderRequestInfo` Class:**
- It is the blueprint for `@RequestBody/@RequestPart` annotated params in controllers
- In controller POST requests, the request body or request part must match the blueprint of it
### **(3) `MailSenderInputStream` Class:**
- It is the blueprint for processing proper input stream info in controllers
- In controller POST requests, it will receive `MultipartFile` type as `@RequestPart`
- Then this API instance should be created with the input stream
### **(4) `MailSenderHtmlTemplate` Class:**
- It is the blueprint for processing proper thymeleaf HTML template info in controllers
- The project should have a Thymeleaf Html Template already
- Then this API instance should be created with the template name and the variable name inside that template
## **_Requirements:_**
- 💀 Minimum Java Version: `21`
- 💀 Minimum Spring Boot Version: `3.3.5`
- 💀 Spring Web Flux (Reactive Spring Boot)
- 💀 Spring Java Mail Sender
- 💀 Spring Thymeleaf
## **_Usage:_**
### For `Maven`, inside `dependencies` tag of `pom.xml`, copy the following
> ```xml
>
> best.skn
> skn-spring-mail
> 2.4.0
>
> ```
### For `Gradle`, inside `dependencies` block of `build.gradle.kts`, copy the following
> ```kotlin
> implementation("best.skn:skn-spring-mail:2.4.0")
> ```
### First create a configuration class
> ```java
> import best.skn.mail.configurations.MailSenderConfiguration;
>
> @Configuration
> @Import(MailSenderConfiguration.class)
> public class MailSenderSpringConfiguration {}
> ```
### Inside your Java Code, import the package like this for `MailSenderService`
> ```java
> import best.skn.mail.services.MailSenderService;
> ```
### Inside your Java Code, import the package like this for `MailSenderRequestInfo`, `MailSenderInputStream` & `MailSenderHtmlTemplate`
> ```java
> import best.skn.mail.models.*;
> ```
### In controller POST requests, use it like the following (Just an example)
> ```java
> @Autowired
> private MailSenderService mailSender;
>
> @PostMapping("/endpoint-for-basic-mail")
> public Mono sendMail(@RequestBody MailSenderRequestInfo info)
> throws MessagingException {
> return this.mailSender.sendMail(info);
> }
>
> @PostMapping("/endpoint-for-mail-with-attachment")
> public Mono sendMailWithAttachment(
> @RequestPart MailSenderRequestInfo info,
> @RequestPart MultipartFile file
> ) throws MessagingException, IOException {
> MailSenderInputStream stream = new MailSenderInputStream(
> "output file location here",
> file.getInputStream()
> );
>
> return this.mailSender.sendMailWithAttachment(info, stream);
> }
>
> @PostMapping("/endpoint-for-mail-with-html-template")
> public Mono sendMailWithHtmlTemplate(
> @RequestBody MailSenderRequestInfo info
> ) throws MessagingException {
> // you must have "mail.html" in `resources/templates` and the template must have a `message` variable
> MailSenderHtmlTemplate template = new MailSenderHtmlTemplate(
> "mail.html",
> "message"
> );
>
> return this.mailSender.sendMailWithHtmlTemplate(info, template);
> }
>
> @PostMapping("/endpoint-for-mail-with-html-template-and-attachment")
> public Mono sendMailWithHtmlTemplateAndAttachment(
> @RequestPart MailSenderRequestInfo info,
> @RequestPart MultipartFile file
> ) throws MessagingException, IOException {
> // you must have "mail.html" in `resources/templates` and the template must have a `message` variable
> MailSenderHtmlTemplate template = new MailSenderHtmlTemplate(
> "mail.html",
> "message"
> );
>
> MailSenderInputStream stream = new MailSenderInputStream(
> "output file location here",
> file.getInputStream()
> );
>
> return this.mailSender.sendMailWithHtmlTemplateAndAttachment(info, template, stream);
> }
> ```
### When requesting the API from `Postman` or `Frontend Framework` for mails without attachment, the request body `json` format can be like the following-
> ```json
> {
> "from": "sender email address",
> "to": "receiver email address",
> "subject": "mail subject",
> "body": "mail body"
> }
> ```
### When requesting the API from `Postman` or `Frontend Framework` for mails with attachment, the request should be made with `form-data` format as it will be processed with `@RequestPart`
## **_Dedicated To:_**
- 👩🎨`Prodipta Das Logno` & 🧛♀️`Atoshi Sarker Prithula`: The two most special ladies of my life. My best wishes will always be with you two. May you two always be happy.
- 💯`My Parents`: The greatest treasures of my life ever.
## **_License:_**
Copyright (C) 2024 SKN Shukhan
Licensed under the Apache License, Version 2.0