Email delivery in Elastic Path Commerce is triggered by messages sent within the Event Messaging framework. Certain event messages trigger the publishing of a corresponding email message that contains the contents and metadata of the outgoing email. For example, when a new order is created, an
ORDER_CREATED event message is published. One of the consumers of this message is the component that generates an order confirmation email.
The following events will trigger the sending of an email:
- A new customer registers an account
- A customer requests a forgotten password
- A Commerce Manager user creates a new Commerce Manager user account
- A Commerce Manager user requests a forgotten password
- A customer or Commerce Manager user resets the customer’s password
- A customer places a new order
- A Commerce Manger user completes an order shipment
- A customer sends their wish list to a friend
- A customer purchases a gift certificate (the recipient is notified)
- A CSV, Comma Separated Values, Import job completes (the Commerce Manager user is notified)
- A Commerce manager user processes a returned or exchanged item (an RMA, Return Merchandise Authorization, email is sent to the customer)
All emails have plain text and HTML versions. Each email event uses a different template and includes event-specific content (such as the order number). Email templates are store-specific, so each store should have a separate set of templates.
Elastic Path Commerce uses Velocity for the email templates. The general administration (non-store) email templates are located in
<assets>/cmassets/templates/velocity/email. Store specific email templates are located in
The Commerce Engine does not include an SMTP server out of the box.
Emails are sent as multi-part MIME (Multipurpose Internet Mail Extensions) messages. If the email client cannot accept an HTML version, the email will degrade to the text version.
Adding a new email
You can add new emails by implementing the
com.elasticpath.email.producer.spi.AbstractEmailProducer class and injecting your new
EmailProducer class into a new
EventMessageTriggeredEmailRouteBuilder bean, which in turn is added to an Apache Camel context.
Creating a Camel Context
Apache Camel coordinates and communicates with the various systems involved in event messaging, such as a JMS (Java Messaging Service) broker. A Camel context is required to route the incoming event messages to the components that create each individual email message.
When creating a new email handler module, copy the following into a new Spring configuration file and configure accordingly to create the Camel context:
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:camel="http://camel.apache.org/schema/spring" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.0.xsd http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd "> <camel:camelContext id="ep-custom-email-handler" xmlns="http://camel.apache.org/schema/spring"> </camel:camelContext> </beans>
Implementing an Email Producer
com.elasticpath.email.producer.api.EmailProducer interface and
com.elasticpath.email.producer.spi.AbstractEmailProducer class define methods that take a domain object’s GUID and a Map of data, and return
com.elasticpath.email.EmailDto instances that represent an email to be sent.
EmailProducer interface is the primary API class involved in constructing an email. While this interface can be implemented directly, most implementations should extend
To send a single email, extend the
AbstractEmailProducer class and override the
createEmail(String, Map) method. To construct multiple emails at the same time, implement the
EmailProducer interface and override the
createEmails(String, Map) method.
Each implementation is free to determine the manner by which an email is created. The existing Commerce Engine
EmailProducer classes utilise Velocity to construct both the plain text and HTML contents of emails. See an existing
EmailProducer implementation for more details.
Injecting an EmaiProducer Into a
After implementing an
EmailProducer, inject it into an
EventMessageTriggeredEmailRouteBuilder so that it gets invoked when a particular event message is published.
You can define new Event Messages to trigger your email. Refer to Asynchronous Event Messaging in Elastic Path Commerce Engine for instructions on how to create new Event Types.
To create a new
EventMessageTriggeredEmailRouteBuilder, add the following bean definition into your email handler’s Spring context and configure accordingly:
<bean id="customEmailHandlingRouteBuilder" parent="abstractEventMessageTriggeredEmailRouteBuilder"> <property name="routeId" value="customEmailHandlingRoute" /> <property name="incomingEndpoint"> <bean class="org.apache.camel.spring.CamelEndpointFactoryBean"> <property name="camelContextId" value="ep-custom-email-handler" /> <property name="uri" value="jms:topic:ep.eventmessagetype"/> </bean> </property> <property name="outgoingEndpoint"> <bean class="org.apache.camel.spring.CamelEndpointFactoryBean"> <property name="camelContextId" value="ep-custom-email-handler" /> <property name="uri" value="jms:ep.emails"/> </bean> </property> <property name="eventMessagePredicateFilter" ref="customEventTypePredicate"/> <property name="emailProducer" ref="customEmailProducer"/> </bean>
The required properties of the
A unique ID by which your route can be identified.
The endpoint URI from which the event messages should be consumed.
Recommended value: The channel containing the relevant event messages.
Existing routes defer this definition to a settings framework value - see existing
EventMessageTriggeredEmailRouteBuilderbean definitions for an example.
The endpoint URI of the email delivery queue. This queue is consumed by the email sending component, which is responsible for sending all email messages via the configured SMTP(S) server.
Recommended value: The channel containing the relevant event messages. By default, this value is
Existing routes defer this definition to a Settings Framework value - see existing
EventMessageTriggeredEmailRouteBuilderbean definitions for an example.
EventMessagePredicateinstance that determines whether or not a given event message should trigger an Email to be sent.
Recommended value: A
CompatibleEventTypePredicateimplementation that accepts the appropriate Event Type.
EmailProducerresponsible for creating the email message.
Recommended value: An instance of your newly-created EmailProducer class
abstractEventMessageTriggeredEmailRouteBuilder bean defines the following default properties:
DataFormatused to unmarshal event messages from a String to an
DataFormatused to marshal an Email into a String for publishing to the email delivery JMS queue.
A Camel Predicate instance that determines whether or not emails should be sent. We recommend you use the
emailEnabledPredicatebean, which returns the value of the
EventMessageTriggeredEmailRouteBuilder to the Camel context configuration to activate it and have it respond to event messages:
<camel:camelContext id="ep-custom-email-handler" xmlns="http://camel.apache.org/schema/spring"> <routeBuilder ref="customEmailHandlingRouteBuilder"/> </camel:camelContext>
Sending file attachments
You can send file attachments with your emails if required. Existing out of the box emails do not implement file attachments.
To send file attachments, use one of the following methods provided by the EmailDto class when you construct your email:
addAttachmentUrl(): Adds the URL of a file to attach to a collection of attachment URLs
withAttachmentUrls(): Clears the current collection of attachment URLs, and adds the attachment URL(s) to a collection of attachments
addAttachment(): Adds a file attachment’s binary data to a collection of attachments
withAttachments(): Clears the current collection of binary data attachments, and adds the attachment data to a collection of attachments
LegacyEmailProducer and LegacyEmailComposer
If you are migrating functionality to Elastic Path Commerce 7.1 from an earlier version and need to maintain backwards compatibility, use the
com.elasticpath.email.util.LegacyEmailComposer interfaces instead of the default
The legacy interfaces produce
org.apache.commons.mail.Email instances, and do not support email attachments. The legacy interfaces should use the