JarCastingiplant-email
Provides backend services with a relatively simple way to send emails.
Installation
iplant-email is packaged as an RPM and can be installed using the command, yum install iplant-email.
Configuration
The configuration settings for iplant-email are stored in a Zookeeper cluster in the format generated by Clavin, iPlant's command-line utility for loading property files into Zookeeper. As with most other iPlant services, the settings used to connect to zookeeper are stored in /etc/iplant-services/zkhosts.properties, which should contain a single property, zookeeper, that contains a comma-delimited list of host names and port numbers used to connect to Zookeeper. Here's an example:
zookeeper = by-tor.example.org:2112,snow-dog.example.org:1984
At this time, three configuration settings are stored in Zookeeper: the SMTP host (iplant-email.smtp.host), the "from" e-mail address (iplant-email.smtp.from-address) and the listen port (iplant-email.app.listen-port). Here's an example configuration file in properties file format:
iplant-email.smtp.host=smtp.example.org
iplant-email.smtp.from-address[email protected]
iplant-email.app.listen-port=3000
Making a request
There is only one endpoint in the iplant-email app, "/". To request that an email be sent, you need to know the template name, the 'to' email address, and the values that are to be interpolated into the email template.
Here is a sample request:
curl -H "Content-Type:application/json" -d '
{
"to" : "[email protected]",
"from-addr" : "[email protected]",
"from-name" : "Example Support",
"subject" : "Example",
"template" : "bettertest",
"values" : {
"user" : "Foo",
"useremail" : "[email protected]",
"value" : "foobar"
}
}
' http://127.0.0.1:3000/
The 'to' field is hopefully pretty self-explanatory, as is the 'subject' field.
The from-addr field is optional and contains the email address that should be placed in the from field. If it is omitted from the request, the configuration option from iplant-emails config file will be used instead.
The from-name field is optional and contains the name associated with the email address placed in the from field. If it is omitted, then no name is associated with the from adress.
The 'template' field corresponds to an email template located in the /etc/iplant-email directory. It is the filename of the template, minus the .st extension.
The values field is a map that contains values that are interpolated into corresponding fields in the email template. For instance, "Foo" is substituted into the email wherever $user$ appears.
Adding/Modifying Email Templates
Email templates live in /etc/iplant-email.
You can add and modify templates on the fly, iplant-email will pick up the changes without having to be restarted.
All template files must end with a '.st' extension. The name of the template is derived from the part of the filename that comes before the '.st' extension.
The syntax for templatizing emails is available in the "Learn basic StringTemplate syntax" section on this website: http://www.antlr.org/wiki/display/ST/Five+minute+Introduction
