Create email templates for transactional events

Important

Some or all of the functionality noted in this topic is available as part of a preview release. The content and the functionality are subject to change. For more information about preview releases, see One version service updates FAQ.

This topic describes how to create, upload, and configure email templates for transactional events in Microsoft Dynamics 365 Commerce.

Dynamics 365 Commerce provides an out-of-box solution for sending emails that alert customers about transactional events. For example, emails can be sent when an order is placed, is ready for pickup, or has been shipped. This topic describes the steps for creating, uploading, and configuring the email templates that are used to send transactional emails.

Notification types

Notifications can be configured to inform customers via email when specific events occur as part of the order and customer lifecycle. To configure notifications, you must map an email template to a notification type by creating a Commerce email notification profile. For information about how to set up email notification profiles, see Set up an email notification profile.

Dynamics 365 Commerce supports the following notification types.

Order created

The order created notification type is triggered when a new sales order is created in Commerce headquarters.

Note

The order created notification type isn't triggered for cash-and-carry transactions that occur at a point of sale (POS) terminal. In this case, an emailed and/or printed receipt is generated instead. For more information, see Send email receipts from Modern POS (MPOS).

Order confirmed

The order confirmed notification type is triggered when an order confirmation document is generated for a sales order from Commerce headquarters.

Picking completed

The picking completed notification type is triggered when a picking list for an order is marked as completed in Commerce headquarters.

Note

The picking completed notification type isn't triggered when an item is marked as picked at a POS terminal.

Packing completed

The packing completed notification type is triggered when a packing slip document is generated for an order in Commerce headquarters at a POS terminal.

The packing completed notification type supports the following additional email placeholders to facilitate "order ready for pickup" and order lookup functionality from transactional emails.

Placeholder name Purpose
pickupstorename The name of the store where the order is available for pickup.
pickupstoreaddress The address of the store where the order is available for pickup.
pickupstorehourfrom The opening hour of the pickup store.
pickupstorehourto The closing hour of the pickup store.
pickupchannelid The store channel ID of the pickup store.
packingslipid The ID of the packing slip for the order that will be picked up.
confirmationid The order confirmation ID of the order that will be picked up. (This ID is sometimes referred to as the channel reference ID.)

For more information about the customer check-in and order lookup features, see Set up geo detection and redirection and Enable order lookup for guest checkouts.

Order ready for pickup

The order ready for pickup notification type is triggered when an order is marked as packed, and the mode of delivery is set to Customer pickup on one or more order lines.

Note

The order ready for pickup notification type has been deprecated in favor of the packing completed notification type. This notification type is customized by mode of delivery.

Order shipped

The order shipped notification type is triggered when an order that has a non-store-pickup mode of delivery is invoiced.

Note

The order shipped notification type has been deprecated in favor of the order invoiced notification type. This notification type is customized by mode of delivery.

Order invoiced

The order invoiced notification type is triggered when an order is invoiced in POS or Commerce headquarters.

Issue gift card

The issue gift card notification type is triggered when a sales order that contains a product of the gift card type is invoiced.

Note

The issue gift card notification email is sent to the gift card recipient. The gift card recipient is specified in Commerce headquarters, on an individual sales order line on the Packing tab under Line details. It can be specified either manually or programmatically.

The issue gift card notification type supports the following additional placeholders.

Placeholder name Purpose
giftcardnumber The gift card number, for products of the gift card type.
giftcardbalance The gift card balance, for products of the gift card type.
giftcardmessage The gift card message, for products of the gift card type.
giftcardpin The personal identification number (PIN) of the gift card, for products of the gift card type. (This placeholder is specific to external gift cards.)
giftcardexpiration The expiration date of the gift card, for products of the gift card type. (This placeholder is specific to external gift cards.)
giftcardrecipientname The name of the gift card recipient, for products of the gift card type.
giftcardbuyername The name of the gift card buyer, for products of the gift card type.

For more information about gift cards, see E-commerce digital gift cards and Support for external gift cards.

Order cancellation

The order cancellation notification type is triggered when an order is canceled in Commerce headquarters.

Customer created

The customer created notification type is triggered when a new customer entity is created in Commerce headquarters.

B2B prospect approved

The B2B prospect approved notification type is triggered when a prospect's onboarding request is approved in Commerce headquarters. For more information about how to approve or reject B2B prospects, see Set up the administrator user for a new business partner.

The B2B prospect approved notification type supports the following additional placeholders.

Placeholder name Purpose
firstname The first name of the B2B prospect as it's entered in the application.
lastname The last name of the B2B prospect as it's entered in the application.
company The name of the applicant's company as it's entered in the application.
email The prospect's email address as it's entered in the application.
zipcode The ZIP/postal code of the prospect's primary address.
comments The comment that the prospect entered in the application.
storename The name of the channel where the prospect was created.
storeurl Empty by default. A custom extension must be created to use this placeholder.

B2B prospect approved

The B2B prospect rejected notification type is triggered when a prospect's onboarding request is rejected in Commerce headquarters. For more information about how to approve or reject B2B prospects, see Set up the administrator user for a new business partner.

The B2B prospect rejected notification type supports the following additional placeholders.

Placeholder name Purpose
firstname The first name of the B2B prospect as it's entered in the application.
lastname The last name of the B2B prospect as it's entered in the application.
company The name of the applicant's company as it's entered in the application.

Create an email template

Before you can map a specific transactional event to an email template, you must create the template.

To create an email template, follow these steps.

  1. In Commerce headquarters, go to Retail and Commerce > Headquarters setup > Organization email templates or Organization administration > Setup > Organization email templates.

  2. Select New.

  3. Under General, set the following fields:

    • Email ID – The email ID is the unique identifier for a template. It's the value that is shown when you select a template to map to an event.
    • Email description – You can use this optional field to provide a description of the template. The value that you enter appears only in Commerce headquarters.
    • Sender name – The name that you enter appears in the "from" field of most email clients.
    • Sender email – Enter the email address that should be used for emails that are sent by using this template.
    • Default language code – This field specifies the localized version of the email that is sent by default, if the channel that invokes this template doesn't specify a language.
  4. Under Email message content, select New.

  5. In the Language field, enter the language for the email template. You can add more languages and localized templates later.

  6. In the Subject field, enter the email subject that should appear in the subject field of the email.

  7. Select Edit to upload your email template.

Create an email message body by using HTML

The message body of your email is composed in HTML. You can use any layout, styling, and branding that HTML and inline Cascading Style Sheets (CSS) allow for. You can also use images, if you host them on a publicly available web endpoint. To add an image, enter the image's URL in the src attribute of the HTML <img> tag.

Note

Email clients impose layout and style limitations that might require adjustments to the HTML and CSS that you use for the message body. We recommend that you familiarize yourself with the best practices for creating HTML that the most popular email clients will support.

Add placeholders to the email message body

Your email can contain placeholders that are replaced with customer-specific and transaction-specific values when the email is generated. Placeholders are always surrounded by percent signs (%) and are inserted directly into the HTML document.

Here is an example.

<p>
    Hello %customername%,<br />
    Order number %salesid%, can be picked up from the <b>%pickupstorename%</b> store.
</p>

Order placeholders (sales order level)

The following placeholders retrieve and show data that is defined at the sales order level (as opposed to the sales line level).

Placeholder name Purpose
customername The name of the customer who placed the order.
customeraddress The address of the customer.
customeremailaddress The email address that the customer entered at checkout.
salesid The sales ID of the order.
orderconfirmationid The cross-channel ID that was generated at order creation.
channelid The ID of the retail or online channel that the order was placed through.
deliveryname The name that is specified for the delivery address.
deliveryaddress The delivery address for shipped orders.
deliverydate The delivery date.
shipdate The ship date.
modeofdelivery The delivery mode of the order.
ordernetamount The total amount for the order, minus the total tax.
discount The total discount for the order.
charges The total charges for the order.
tax The total tax for the order.
total The total amount for the order.
storename The name of the store where the order was placed.
storeaddress The address of the store that placed the order.
storeopenfrom The opening time of the store that placed the order.
storeopento The closing time of the store that placed the order.
pickupstorename The name of the store where the order will be picked up.*
pickupstoreaddress The address of the store where the order will be picked up.*
pickupopenstorefrom The opening time of the store where the order will be picked up.*
pickupopenstoreto The closing time of the store where the order will be picked up.*
pickupchannelid The channel ID of the store that is specified for a pickup mode of delivery.*
packingslipid The ID of the packing slip that was generated when lines in an order were packed.*

* These placeholders return data only when they are used for the Order ready for pickup notification type.

Order line placeholders (sales line level)

The following placeholders retrieve and show data for individual products (lines) in the sales order.

Placeholder name Purpose
productid

The ID of the product. This ID accounts for variants.

Note: This placeholder has been deprecated in favor of lineproductrecid.

lineproductrecid The ID of the product. This ID accounts for variants. It uniquely identifies an item at the variant level.
lineitemid The product-level ID of the product. (This ID doesn't account for variants.)
lineproductvariantid The ID of the product variant.
lineproductname The name of the product.
lineproductdescription The description of the product.
linequantity The number of units that were ordered for the line, plus the unit of measure (for example, ea, or pair).
lineunit The unit of measure for the line.
linequantity_withoutunit The number of units that were ordered for the line, without the unit of measure.
linequantitypicked When the PickOrder event is used, the number of units that were picked. Otherwise, 0 (zero).
linequantitypicked_withoutunit When the PickOrder event is used, the number of units that were picked, without the unit of measure. Otherwise, 0 (zero).
linequantitypacked When the PackOrder and Order ready for pickup events are used, the number of units that were packed. Otherwise, 0 (zero).
linequantitypacked_withoutuom When the PackOrder and Order ready for pickup events are used, the number of units that were packed, without the unit of measure. Otherwise, 0 (zero).
linequantityshipped Always 0, except when specific events are used, as described in the next row.
linequantityshipped_withoutuom When the ShipOrder event is used, the number of units that were picked, without the unit of measure. Otherwise, 0 (zero).
lineprice The price of a single unit.
linenetamount The price of the line after the number of units and discount are applied.
linediscount The discount for an individual unit.
lineshipdate The ship date for the line.
linedeliverydate The delivery date for the line.
linedeliverymode The delivery mode for the line.
linedeliveryaddress The delivery address for the line.
linepickupdate The pickup date that the customer specified, for orders that use a pickup mode of delivery.
linepickuptimeslot The pickup time range that the customer specified, for orders that use a pickup mode of delivery.
giftcardnumber The gift card number, for products of the gift card type.
giftcardbalance The gift card balance, for products of the gift card type.
giftcardmessage The gift card message, for products of the gift card type.
giftcardpin The PIN of the gift card, for products of the gift card type. (This placeholder is specific to external gift cards.)
giftcardexpiration The expiration date of the gift card, for products of the gift card type. (This placeholder is specific to external gift cards.)
giftcardrecipientname The name of the gift card recipient, for products of the gift card type.
giftcardbuyername The name of the gift card buyer, for products of the gift card type.

Format of order line placeholders in the email message body

When you create the HTML for the individual order lines in the email message body, surround the repeating block of HTML and placeholders for the lines with the following placeholders. Notice that the placeholders are inside HTML comment tags.

<!--%tablebegin.salesline%-->

(Insert the repeating block of HTML and placeholders for individual lines here.)

<!--%tableend.salesline%-->

Here is an example.

<table>
    <tr>
        <td>Product name</td>
        <td>Quantity</td>
        <td>Price</td>
    </tr>
    <!--%tablebegin.salesline%-->
    <tr>
        <td>%lineproductname%</td>
        <td>%linequantity_withoutunit%</td>
        <td>%lineprice%</td>
    </tr>
    <!--%tableend.salesline%-->
</table>

Create a template for emailed receipts

Receipts can be emailed to customers who make purchases at a retail point of sale (POS). In general, the steps for creating the emailed receipt template are the same as the steps for creating templates for other transactional events. However, the following changes are required:

  • The %message% placeholder is used to insert the text of the receipt into the email. To ensure that the receipt body is correctly rendered, surround the %message% placeholder with HTML <pre> and </pre> tags.
  • The %receiptid% placeholder can be used to show a QR code or bar code that represents the receipt ID. (QR codes and bar codes are dynamically generated and served by a third-party service.) For more information about how to show a QR code or bar code in an emailed receipt, see Add a QR code or bar code to transactional and receipt emails.

Upload the email HTML

After you've created and tested the HTML for your message body, it must be uploaded to Commerce headquarters. Currently, email HTML can't be exported. Therefore, you must maintain the master copy of your HTML outside Commerce headquarters.

To upload a new or edited email template HTML, follow these steps.

  1. In Commerce headquarters, go to Retail and Commerce > Headquarters setup > Organization email templates.
  2. Select the row for the language that you want to add or replace HTML for. Alternatively, select New to create a row for a new language.
  3. Select Edit.
  4. In the dialog box that appears, select Browse. Browse to the HTML document that you want to upload, select it, and then select Open.
  5. Select Upload.
  6. After your email HTML appears in the preview window, select OK.
  7. Make sure that the Has body checkbox is selected for the row.

If you've already configured Commerce headquarters to send email, your new or updated email will be sent to all customers who perform a transaction that invokes the event that is mapped to the template.

For more information about how to configure emails in Dynamics 365 Commerce, see Configure and send email.

Additional resources

Set up an email notification profile

Configure and send email

Set up email receipts

Send email receipts from Modern POS