hermes, the herald of the Olympians, is a small CLI utility to send batched emails with some customised content. Note: hermes relies on external infrastructure such as a SMTP server.
Main user story:
Someone managing a number of groups with several people per group and these groups need to get information via email. Some of the email content is similar for all groups, some content specific to groups. Furthermore, another set of people should get cc-ed, depending on the group.
To solve this, one could write an email template, carefully copy-paste the groups' emails from a table and then, add the CC recipients where necessary. Before sending, the template content would be manually replaced by the specific content. An endeavour too long to really take.
hermes for the win! With hermes, the above described scenario is nothing more than providing a few tables, a template and the call of the hermes command and the emails are sent.
- hermes is written in Kotlin and thus requires a JVM
- Third party infrastructure for actually sending the email is required. For instance Gmail or other Email providers
Since hermes is for writing batched, templated emails, the following components have to be provided:
- A template for the email
- A dictionary with template replacements
- An address book with recipients
- Credentials to the external SMTP server
See below for further details about the configuration.
Sending an email then is as simply as issuing the command:
$> java -jar hermes.jar batch \
--mail=email-template.txt \
--credentials=credentials.json \
--dictionary=dictionary.csv \
--tasks=tasks.csv \
--addresses=addresses.csv
Read below for an example of each of the file formats. See credentials for info about the credentials.
The example email template, email-template.txt is a plain text file:
To:$key
From:[email protected]
Subject:Welcome from hermes, $addressee
Hi there, $addressee
This is a batched, email sent from hermes.
Your specific information is: $info
Don't forget that you are respondible for $target
Best,
Alice
Note the format, as described below. The to line is required, however in batch mode,
the key there is ignored (so technically, you could use any non whitespace character as replacement for $key)
The example dictionary, dictionary.csv is a table as follows.
The header contains all the placeholders from the template above (using the dollar $ prefix is just a convention).
Be aware that the key column must match with the one from the tasks file!
key,$addressee,$info,$target
g1,Group 01,"https://example.com/group01,food
g2,Group 02,"https://example.com/group02,"beverages & drinks"
g3,"Olympian Dieties","https://example.com/admin,"Being a diety"
The example address book, addresses.csv is a table with email addresses-key mappings:
key,email
group1,[email protected]
group1,[email protected]
group1,[email protected]
group2,[email protected]
group2,[email protected]
group2,[email protected]
dieties,[email protected]
dieties,[email protected]
dieties,[email protected]
Note that there is one entry per line, to form a group of recipients, group them by the same key.
This key is then used in the to column of the tasks file!
The example task file, tasks.csv is a table with (dicitonary-)key and (addressbook-)key pairs:
key,to,cc
g1,group1,[email protected]
g2,group2,[email protected]
g3,dieties,[email protected]
Note, the cc and bcc columns are optional
The major components of hermes have to be configured as follows
The basic format is a line-based, colon (:) separated text file.
Of which, Subject, To, From and the message body are required.
The headers and the message body are separated by an empty line:
Subject:
To:
From:
Cc:
Bcc:
Message body in plaintext
The Subject and message body might contain dictionary keys to be replaced before sending.
The recipients fields might contain keys for an address book.
The dictionary is a CSV file
The address book is a table with a key-email address format:
key,email
"key0","email1"
"key1","email2"
"key2","email3"
"key3","email4"
"key4","email5"
Example
key,email
"GroupAlice","[email protected]"
"GroupAlice","[email protected]"
"GroupTuring","[email protected]"
You require a third-party SMTP setup and provide the credentials in the following format:
{
"host": "<your-smtp-host>",
"port": 465,
"username": "<your-username>",
"password": "<your-password>",
"ssl": true
}Example with GMAIL:
{
"host": "smtp.googlemail.com",
"port": 465,
"username": "[email protected]",
"password": "alicespassword",
"ssl": true
}