Configure Email

Introduction

Goal

BRC provides an SMTP server based on AWS SES. This page explains how to configure the SMTP server for your Bloomreach Cloud stack to enable your Bloomreach Experience Manager implementation to send email messages.

Procedure

To enable the applications deployed in your Bloomreach Cloud stack to send email messages, you need credentials and the host configuration string for the SMTP server. You can use your own SMTP server, or BloomReach can provide this.

To use a SMTP server provided by BloomReach, please create a support ticket with the domain to send the mails from. BloomReach will ask you on behalf of AWS to put some entries into your DNS to prove you own the domain. It is best not to wait too long with entering these entries. After the confirmation, BloomReach will upload a mail configuration file to your stack. This configuration file will contain the following properties:

Common (both smtp and smtps):
brc.mail.smtp.password=...
brc.mail.transport.protocol=... (default is smtp)
brc.mail.debug.auth=... (default is false)
brc.mail.debug=... (default is false)

SMTP properties:
brc.mail.smtp.host=...
brc.mail.smtp.username=...
brc.mail.smtp.port=...
brc.mail.smtp.auth=... (default is true)
brc.mail.smtp.ssl.checkserveridentity=... (default is false)
brc.mail.smtp.ssl.trust=... (default is *)
brc.mail.smtp.ssl.protocols=... (default is TLSv1 TLSv1.1 TLSv1.2)
brc.mail.smtp.starttls.enable=... (default is true)
brc.mail.smtp.starttls.required=... (default is false)

SMTPS properties:
brc.mail.smtps.host=...
brc.mail.smtps.username=...
brc.mail.smtps.port=...
brc.mail.smtps.auth=... (default is true)
brc.mail.smtps.ssl.checkserveridentity=... (default is false)
brc.mail.smtps.ssl.trust=... (default is *)
brc.mail.smtps.ssl.protocols=... (default is TLSv1 TLSv1.1 TLSv1.2)
brc.mail.smtps.starttls.enable=... (default is true)
brc.mail.smtps.starttls.required=... (default is false)

When deploying a distribution, you need to select the option to copy this configuration file for production usage.

Make sure that the file name for copied config is: brc-mail-smtp.properties.

Note that you can only send emails from the verified domain. This means that the fields "From", "Source", "Sender", or "Return-Path" addresses must use the verified domain.

Example

Your custom code can use the Java system properties as in the example below. Notice the brc.mail.* entries, these are populated through Java system properties from the configuration file. This example is based on the AWS Java SMTP example and provided for learning purposes. For production usage we recommend reading the configuration file as system properties are exposed in the CMS admin console.

// returns info message or exception message
private String brcMail() throws MessagingException, UnsupportedEncodingException, NamingException {
    // Replace [email protected] with your "From" address.
    // This address must be verified.
    final String FROM = "[email protected]";
    final String FROMNAME = "Customer";

    // Replace [email protected] with a "To" address.
    final String TO = "[email protected]";

    final String SUBJECT = "BRC Test";

    final String BODY = String.join(
            System.getProperty("line.separator"),
            "<h1>BloomReach Cloud Email Test</h1>",
            "<p>This email was sent with BloomReach Cloud using the ",
            "<a href='https://github.com/javaee/javamail'>Javamail Package</a>",
            " for <a href='https://www.java.com'>Java</a>."
    );

    // retrieve Session object from JNDI
    Context initCtx = new InitialContext();
    Context envCtx = (Context) initCtx.lookup("java:comp/env");
    Session session = (Session) envCtx.lookup("mail/Session");

    // Create a message with the specified information.
    MimeMessage msg = new MimeMessage(session);
    msg.setFrom(new InternetAddress(FROM, FROMNAME));
    msg.setRecipient(Message.RecipientType.TO, new InternetAddress(TO));
    msg.setSubject(SUBJECT);
    msg.setContent(BODY,"text/html");

    // Create a transport.
    Transport transport = session.getTransport();

    // Send the message
    String result;
    try
    {
        System.out.println("Sending...");

        // Connect to Amazon SES
        transport.connect();

        // Send the email.
        transport.sendMessage(msg, msg.getAllRecipients());
        result = "Email sent!";
        System.out.println(result);
    }
    catch (Exception ex) {
        System.out.println("The email was not sent.");
        System.out.println("Error message: " + ex.getMessage());
        result = ex.getMessage();
    }
    finally
    {
        // Close and terminate the connection.
        transport.close();
    }
    return result;
}

Enterprise Forms

If you plan to use Enterprise Forms, you also need to deploy the mail configuration file together with your distribution. When deploying, make sure that the file name for copied config is: brc-mail-smtp.properties. It is critical to configure enterprise forms to use a sender email address that has been verified. When deploying using mail configuration file, a mail/Session container variable is automatically configured in your environment using the properties mentioned above. 
Note that using Enterprise forms will have an impact on the Blue/Green deployments; during the content freeze, data that is stored in the 'old' repository will get lost if you do not migrate the data to the new repository.

Gmail SMTP example

Note: For using Gmail as mail sender, one can setup App password for Google account. More details here: Sign in with App Passwords

Example configuration file:

brc.mail.transport.protocol=smtp
brc.mail.smtp.host=smtp.gmail.com
brc.mail.smtp.username=... (Gmail address)
brc.mail.smtp.password=... (Gmail app password)
brc.mail.smtp.port=587
brc.mail.smtp.starttls.enable=true
brc.mail.smtp.ssl.protocols=TLSv1.2

Office365 SMTP example

Note: For using SMTP, one needs to enable SMTP AUTH on mailbox. More details here: Enable or disable authenticated client SMTP submission

Example configuration file:

brc.mail.transport.protocol=smtp
brc.mail.smtp.host=smtp.office365.com
brc.mail.smtp.username=... (Office365 account address)
brc.mail.smtp.password=... (Office365 account password)
brc.mail.smtp.port=587
brc.mail.smtp.starttls.enable=true
brc.mail.smtp.ssl.protocols=TLSv1.2

Note: For Office365 SMTP, one needs to setup valid From address field to be a valid Office365 mail account address. To do that, go to CMS Console. In the treeview browse to:

/hst:hst/hst:configurations/common/hst:components/emaileform

Update parameter values for eforms-from-name and eforms-from-email.