Configure Email

Overview

This page describes how to configure email sending for your Bloomreach Cloud stack. Bloomreach Cloud (BRC) provides an SMTP server based on AWS Simple Email Service (SES). You can use the BRC-provided SMTP server or configure your own SMTP server.

When to Use

Configure email if your Bloomreach Experience Manager implementation needs to send email messages, such as notifications or form submissions.

Prerequisites

Access to your DNS provider to add verification records if using the BRC SMTP server.
The domain you want to send emails from.
Access to your Bloomreach Cloud stack and the ability to deploy configuration files.

SMTP Server Configuration

To enable email sending from applications deployed in your Bloomreach Cloud stack, you need:

SMTP credentials
SMTP host configuration string

You can use either your own SMTP server or request credentials for the BRC-provided SMTP server.

Using the BRC SMTP Server

To use the SMTP server provided by Bloomreach:

Create a support ticket specifying the domain you want to use for sending emails.
Bloomreach will request that you add DNS entries to verify domain ownership. These entries are required by AWS SES.
Add the DNS entries as soon as possible to avoid delays.
After verification, Bloomreach will upload a mail configuration file to your stack.

The configuration file includes 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 your distribution, select the option to copy this configuration file for production. The configuration file must be named brc-mail-smtp.properties.

Important:
You can only send emails from domains that have been verified. The "From", "Source", "Sender", and "Return-Path" addresses must use the verified domain.

Implementation Example

You can access the mail configuration properties in your custom code as Java system properties. The following example demonstrates how to send an email using these properties. This example is based on the AWS Java SMTP example.

// 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;
}

Note:
For production deployments, read the configuration file rather than relying on system properties exposed in the CMS admin console.

Enterprise Forms

If you use Enterprise Forms, you must deploy the mail configuration file with your distribution. The configuration file must be named brc-mail-smtp.properties.

Use a sender email address that has been verified.
When the mail configuration file is deployed, a mail/Session container variable is automatically configured in your environment using the properties listed above.

Blue/Green Deployment Impact:
During a Blue/Green deployment, data stored in the previous repository will be lost during the content freeze unless you migrate the data to the new repository.

SMTP Configuration Examples

Gmail SMTP Example

To use Gmail as a mail sender, set up an App Password for your Google account. For details, see 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

To use Office365 SMTP, enable SMTP AUTH on the mailbox. For details, see Enable or disable authenticated client SMTP submission.