Sending Email

First you need to define an SMTP server in your stallion.toml settings. You can get an SMTP email sending service for free from services such as Postmark, Sendgrid, or Mailgun.

[email]
host = "smtp.postmarkapp.com"
username = "yourusername"
password = "yourpassword"
defaultFromAddress = "someone@stallion.io"
adminEmails = ["admin@stallion.io"]
port = 587
canSpamText = "Sent by Stallion Software LLC 123 AnyStreet, Anytown USA"

(Remember, that if you do not want to put your password in plain-text, you can use encrypted secrets management).

Here is how to send a basic email using io.stallion.email.EmailSender, which itself just wraps javax.mail.

var EmailSender = Packages.io.stallion.email.EmailSender; var emailer = EmailSender.newSender(); emailer .setFrom(transformMaybe(getFromAddress())) .setHtml(html) .setReplyTo(transformMaybe(getReplyTo())) .setSubject(transformMaybe(getSubject())) .setTo(user.getEmail()); EmailSender emailer = EmailSender.newSender(); emailer .setFrom("me@service.com") .setHtml(html) .setReplyTo("service@service.com") .setSubject("You are the luck winner!") .setTo("customer@somewhere.com") .send();

The option above is very basic. There is a more complete option that gives you a bunch of nice helpers, and can be used for sending an email to any object that implements the Contactable interface (such as a User or a Contact).

Use it by creating a subclass of the io.stallion.email.ContactableEmailer

Features include:

• easy support for sending emails based on Jinja templates
• respect default user email opt-out
• safe-guards for preventing accidentally sending duplicate emails

Here is an example of the built-in password reset emailer:

var JsExtendableContactableEmailer = Packages.io.stallion.email.JsExtendableContactableEmailer; var EventEmailer = Java.extend(JsExtendableContactableEmailer, { // If true, ignore default user email opt-out isTransactional: function(self) { return false; }, // Get the jinja template for the email getTemplate: function(self) { return 'emails/comment.jinja'; }, // Who is sending the email getFromAddress: function(self) { return '{ commenter.displayName } via UpFor '; }, // The email subject getSubjectJs: function(self) { return 'RE: ' + self.get('event').emailSubject; } }); // Send one email to a particular user: (new EventEmailer(user, {event: event, commenter: commenter})).sendEmail(); public class ResetEmailEmailer extends ContactableEmailer { public ResetEmailEmailer(T user, String resetToken, String returnUrl) { super(user); // Add variables to the template context put("resetToken", resetToken); put("returnUrl", url); } /** * As a transactional email, will be sent even if the user has opted out of * of marketing emails */ @Override public boolean isTransactional() { return true; } /** * Get the template for this email */ @Override public String getTemplate() { return "stallion:email/reset-password.jinja"; } /** * The subject is a simple template string that can interpolate context variables */ @Override public String getSubject() { return "Reset your password for {user.username} on " + Settings.instance().getSiteName(); } /** * Unique keys get stored in memory, and ensure we never send the same email twice */ public String getUniqueKey() { return truncate(GeneralUtils.slugify(getSubject()), 150) + "-" + user.getEmail() + "-" + minuteStamp + getEmailType(); } } // An email can then me sent as so: new ResetEmailEmailer(user, encryptedToken, returnUrl).sendEmail();

Additional stallion.toml Settings

There a few more optional settings to note:

[email]
# Defaults to true. If true, in non-prod mode, disables sending emails to
# anybody who is not match the white-list patterns. All emails instead will
# go to the outboundEmailTestAddress
restrictOutboundEmails = true
# A list of regular expressions defining which email addresses are allowed in
# non-prod mode
allowedTestingOutboundEmailPatterns = [".*@stallion.io"]
# List of email addresses that are allowed in non-prod mode
allowedOutboundEmails = ["test@stallion.io"]
# A test email address that all non-whitelisted email addresses will be routed to.
outboundEmailTestAddress = "test@stallion.io"