Customizing the Confirmation Email

While you are processing shipments, up to three emails may be sent automatically: a ship notification email from the carrier, an order status change email from the underlying store (if your store software supports this), and a ship confirmation email from Shipper. This article describes how you can customize the confirmation email that Shipper sends.

The confirmation email is actually sent by Shipper Service using the "SendMail" function of the underlying store. Normally a fixed format is used to create the email, but you can customize the email by creating an email template file called EmailTemplate.config in the Shipper Service directory. If Shipper Service finds the template file, it will use it to create the email.

The email template has two sections: one for the subject line and one for the body of the email. Each section is a mix of text and tokens. During processing the tokens are replaced with the actual values that are appropriate for the shipment.

Sample EmailTemplate.config file (source)

<EmailTemplate>

<Format>Text</Format>

<Subject>Order {OrderNumber} Shipment Notification</Subject>

<Body>
Dear {FirstName} {LastName},

A shipment from order {OrderNumber} is scheduled to be shipped on {ShipDate} from {StoreName}. To determine the shipping status for this order, please sign on to your account at {StoreUrl} and review the order history.

Sincerely,
{StoreName}
</Body>

</EmailTemplate>

The word between the <Format> and </Format> markers indicates the format of the email. Everything between the <Subject> and </Subject> markers will be used for the email subject. Everything between the <Body> and </Body> markers will be used for the body of the email. Tokens are surrounded by curly braces.

Email Formats

Text	Sends a plain text email.
HTML	Sends an HTML formatted email.

Email Template tokens

{FirstName}	The first name of the customer.
{LastName}	The last name of the customer.
{OrderNumber}	The order number.
{ShipDate}	The shipment pickup date.
{ShippingMethod}	The name of the shipping method.
{StoreName}	The name of the store.
{StoreUrl}	The URL of the store home page.
{TrackingNumber}	The tracking number.

Summary

Create a plain text file in the Shipper Service directory on the web site called EmailTemplate.config using the format shown above (or copy this version of EmailTemplate.config to your web site).
Fill in the subject and body sections using the tokens shown above.

Notes

If you want to use the characters <, >, or & in the Subject or Body, you must use the entities <, >, and & or a CDATA section.
Partial Example Using HTML entities

<Body>
<html>
....
</html>
</Body>

Partial Example Using CDATA

<Body>
<![CDATA[
<html>
....
</html>
]]>
</Body>
You can apply specific formats to the token fields. The token name and format are both placed inside the curly braces separate by a colon. For example, the {ShipDate} token is a date and dates can be formatted in many different ways. To display the shipment pickup date in "long date" format use {ShipDate:D}. Other date formats are shown here.
If you want to use a different name for the email template file or store the email template file in a different directory, create an <appSettings> key named "EmailTemplate.FileName". The value should be the path and filename of the template file.
If you are a developer and want to create a more sophisticated confirmation email, create a class that implements StructuredSolutions.ShipperService.IEmailHelper, then create an <appSettings> key named "EmailHelperType". The value should be the type and assembly name. For example,

<add key="EmailHelperType" value="MyNamespace.MyEmailHelper, MyAssembly" />

Shipper Service will load, create an instance of your handler, and then use it to create and send the confirmation email. Of course your handler does not need to send an email. You could send a text message to a phone for example.