https://github.com/softinstigate/ermes-mail
ErmesMail is a Java library and command line interface for sending e-mail messages asynchronously
https://github.com/softinstigate/ermes-mail
asynchronous command-line command-line-tool email java mailhog smtp
Last synced: 5 months ago
JSON representation
ErmesMail is a Java library and command line interface for sending e-mail messages asynchronously
- Host: GitHub
- URL: https://github.com/softinstigate/ermes-mail
- Owner: SoftInstigate
- License: apache-2.0
- Created: 2022-05-25T14:18:48.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2023-04-19T09:10:25.000Z (over 2 years ago)
- Last Synced: 2025-02-16T21:47:27.768Z (8 months ago)
- Topics: asynchronous, command-line, command-line-tool, email, java, mailhog, smtp
- Language: Java
- Homepage:
- Size: 121 KB
- Stars: 2
- Watchers: 4
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Ἑρμῆς (Hermês) Mail
[](https://jitpack.io/#com.softinstigate/ermes-mail)
ErmesMail is a set of Java classes for sending e-mail messages asynchronously, via SMTP servers.
1. It can be embedded in your Java project as a tiny wrapper for the [Apache Commons Email library](https://commons.apache.org/proper/commons-email/).
1. it can be used as a handy command line utility, to send emails programmatically from the shell.
ErmesMail is developed in Java 17 and built with Maven 3.8.
## JavaDocs
JavaDocs are available [here](https://jitpack.io/com/github/softinstigate/ermes-mail/latest/javadoc/).
## Build and cli execution
1. Build the application with maven: `mvn package`.
2. Run the Java executable by passing the following parameters:
```shell
$ java -jar target/ermes-mail.jar --help
Usage: java -jar ermes-mail.jar [-v] [--help] [--sslon] [-P[=]]
-b= -f= [-h=]
[-n=] [-p=] -s=
[--sslport=] [-u=]
[--bcc=[,...]...]...
[--cc=[,...]...]...
--to=[,...]... [--to=[,
...]...]...
Sends an HTML email to the given recipient(s).
-h, --host= SMTP host.
-p, --port= SMTP port.
-u, --user= SMTP user name.
-P, --password[=]
SMTP user password.
--sslon Use SSL.
--sslport= SSL port (default is 465).
-f, --from= FROM field.
-n, --sender= Sender full name (optional).
-s, --subject= Subject.
-b, --body= Message body (can be HTML).
--to=[,...]...
List of mandatory TO recipients.
--cc=[,...]...
List of optional CC recipients.
--bcc=[,...]...
List of optional BCC recipients.
--help display this help message.
-v, --version print version information and exit.
Copyright(c) 2022 SoftInstigate srl (https://www.softinstigate.com)
```
## Send a test email message to MailHog
To test the sending of e-mails via comand line, we suggest running a local SMTP mock server like [MailHog](https://github.com/mailhog/MailHog). Please look [here](https://github.com/mailhog/MailHog#installation) for MailHogs's installation instructions.
After executing MailHog (usually with the `MailHog` command) you can send your first HTML email message to `localhost` with ErmesEmail:
```shell
$ java -jar target/ermes-mail.jar -h localhost -p 1025 \
-f sender@email.com -s "test" -b "This is a HTML test email." \
--to receiver@email.com
mag 24, 2022 4:46:16 PM com.softinstigate.ermes.mail.EmailService
INFORMAZIONI: MailService initialized with SMTPConfig{hostname='localhost', port=1025, username='', ssl=false, sslPort=465}
mag 24, 2022 4:46:16 PM com.softinstigate.ermes.mail.EmailService send
INFORMAZIONI: Sending emails asynchronously...
mag 24, 2022 4:46:16 PM com.softinstigate.ermes.mail.SendEmailTask call
INFORMAZIONI: Processing MailModel{from='sender@email.com', senderFullName='null', subject='test', message='This is a HTML test email.', to=[Recipient{email='receiver@email.com', name='null'}], cc=[], bcc=[], attachments=[]}
mag 24, 2022 4:46:16 PM com.softinstigate.ermes.mail.SendEmailTask call
INFORMAZIONI: Email successfully sent!
TO: [Recipient{email='receiver@email.com', name='null'}]
CC: []
BCC: []
mag 24, 2022 4:46:16 PM com.softinstigate.ermes.mail.EmailService shutdown
INFORMAZIONI: ExecutorService terminated normally after shutdown request.```
```
You can read the e-mail message on the [MailHog UI](http://0.0.0.0:8025/).
> **Note**: To send messages via Google SMTP, it is necessary to configure your Gmail account by enabling IMAP. [More information](https://support.google.com/mail/answer/7126229)
## Add ErmesMail to your Maven project
To use ErmesMail in your Maven build, first add the JitPack repository in your pom.xml
```xml
jitpack.io
https://jitpack.io
```
Then add the following dependency:
```xml
com.softinstigate
ermes-mail
1.1.0
shaded
```
> **Warning**: As ErmesMail depends on `org.apache.commons.commons-email` v1.5, we suggest to include the below runtime dependencies (`javax.mail-api` and `javax.mail`) to prevent classpath conflicts. The wrong version of these dependancies, included by other libraries, might provoke the following runtime exception when sending emails: `java.lang.NoSuchMethodError: 'void com.sun.mail.util.LineOutputStream.(java.io.OutputStream, boolean)`
```xml
javax.mail
javax.mail-api
1.5.6
runtime
com.sun.mail
javax.mail
1.5.6
runtime
```
You can run `mvn dependency:tree` in your project to check if other artifacts are including these.
### Java example
There are two methods for sending emails: `EmailService.send` is asynchronous and returns a Future list of error strings. the `EmailService.sendSynch` is synchronous and returns a list of error strings. If the list is empty, it means no errors. However, the [SendEmailTask](https://github.com/SoftInstigate/ermes-mail/blob/master/src/main/java/com/softinstigate/ermes/mail/SendEmailTask.java) logs exceptions anyway.
You may wanto to use the asynchronous invocation only in case you have to send tons of email in parallel and don't want to block the rest of the program, otherwise the synchronous method works just fine.
Internally the [EmailService](https://github.com/SoftInstigate/ermes-mail/blob/master/src/main/java/com/softinstigate/ermes/mail/EmailService.java) uses a [java.util.concurrent.ExecutorService](https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ExecutorService.html) to send emails in parallel.
A good understanding of [Java Futures](https://www.baeldung.com/java-future) would help you implementing the best waiting strategy.
Below a java fragment, for example:
```java
SMTPConfig smtpConfig = new SMTPConfig("localhost", 1025, "user", "password", false);
EmailModel emailModel = new EmailModel(
"dick.silly@domain.com", "Dick Silly",
"Test email - " + System.currentTimeMillis(),
"This is a HTML message.");
emailModel.addTo("john.doe@email.com", "John Doe");
emailModel.addTo("serena.wiliams@email.com", "Serena Wiliams");
emailModel.addCc("tom.clancy@email.com", "Tom Clancy");
emailModel.addBcc("ann.smith@email.com", "Ann Smith");
EmailService emailService = new EmailService(smtpConfig, 3); // 3 threads pool
Future> errors = emailService.send(emailModel); // send is asynch
emailService.shutdown();
List listOfErrors = errors.get(); // WARNING: Future.get() is blocking
if (!listOfErrors.isEmpty()) {
System.err.println("Errors sending emails: " + listOfErrors.toString());
}
```