Email Templates

This documentation refers to System Management | Email Templates, either Edit () or Add Email Template () (/Enterprise/EmailTemplate.aspx?ID={new, GUID}), and assumes familiarity with standard HTML markup.

Basic Use

Email Design, Best Practices

Typical email clients are, essentially, stripped-down web browsers, and no two are entirely alike in their support of HTML/CSS standards. This necessitates a simplified approach to email design. The following are some general guidelines:

• Do not include Javascript in an Email Template. It will normally be stripped out of the email and/or will not work.
• Do not include internal or external CSS stylesheets in an Email Template. They will normally be stripped out of the email and/or will not work.
• Do not include form tags in an Email Template. Forms will normally not work.
• Older email clients/browsers will not render a “background” image, but will still use the deprecated “bgcolor” attribute.
• “Fancy” CSS tricks may not be supported in all clients. Stick to the basics when feasible.
• “Shorthand” CSS properties may not be supported in all clients. Use separate declarations for CSS properties with multiple parameters when feasible.
• CSS “positioning” is not supported well in all clients. It is acceptable to use a table for layout in emails, as it will work more reliably in older email clients.
• Basic HTML elements may not behave as expected in all email clients. Use inline CSS to force important desired behavior. (For example, in some email clients, a paragraph tag (<p>) is rendered without the usual bottom-margin, so it must be manually added with inline CSS.)
• Ensure that image paths are relative to the site where the Email Template is being edited, or to the “live” site, and that the images have been uploaded to the virtual images folder for the site(s).
• For best results, always include alternate text (alt) for all images, as this will be displayed for images that are not loaded (yet).
• Some email clients have problems resizing images, either by fixed widths or by percentage. For best results, use an image of the appropriate size.

Browsers and email clients are always changing. Therefore, it is advisable to research current email design best-practices to keep abreast of the latest trends and capabilities.

Using Percent (%) in HTML Code

The system needs to be told to treat percent symbols (%) not intended to be part of a Replacement Expression (see Advanced Use below) as a text character—or “escaped”—with a backslash (\). Note, in these cases the backslash will not be displayed in the email. For example, enter “Discount %: %Cart.Discount_Percent%” as “Discount \%: %Cart.Discount_Percent%.”

Plain Text Template

Because each website User has the option to receive emails in a “text-only” format, an Email Template includes a normal HTML layout (HTML Template tab) and a Plain Text layout (Plain Text Template tab). When creating or editing a Template, don’t forget the Plain Text version—if the Plain Text layout is not populated, Users who have elected to receive Plain Text emails will not see anything in their emails. Treat the Plain Text Template as “preformatted” text; otherwise, everything (including Replacement Expressions; see Advanced Use below) works the same as for the HTML Template.

Sending a Test Email

Clicking the Send Test Email to Yourself icon () will generate and send an email using the Template currently being created/edited to the Login ID of the current User (if logged in with a Login ID that is not a legitimate email address, the system will fail to deliver the test email). The test email will not include any order or invoice data (as there will be no order or invoice associated with it); Templates for orders or invoices may be tested against real order or invoice data on the Order Form or Invoice Form pages in Customer Service.

Advanced Use

Email Templates may be designed to display data pulled from the database. The Object Type selected (on the Main tab) tells the system what sort of data the Template will be allowed to pull; only one type may be selected for a given Template. When the system generates the email, it will identify any Replacement Expressions (anything between un-escaped percent (%) characters), and attempt to replace those expressions with data pulled from the database appropriate to the selected Object Type.

Example: “Welcome to %URL%” would be rendered as “Welcome to www.mysite.com”

To include Google hyperlink analytics in an Email Template:

This Replacement Expression is used in a hyperlink's (<a>) “href” attribute to generate the necessary data that allows Google Analytics to identify the source of the click that referred its traffic to the associated web-page. To use, the path must be followed by a question mark (?), or if one already exists in the hyperlink’s path, an ampersand (&), followed by the Replacement Expression; replace “{name}” with a descriptive name for the hyperlink.

Replacement Expression for Hyperlink Analytics (all Object Types)

%LINKID({name})%

Generates Google tracking data for hyperlinks

Example 1: http://www.mysite.com/index.html?%LINKID(banner)%
Example 2: http://www.mysite.com/Page.aspx?Id=87de23d7-b0e6-4adf-aeec-34155a493f1b&%LINKID(banner)%

To include an “unsubscribe” link in an Email Template:

This Replacement Expression generates a hyperlink that points to the website’s Unsubscribe page (Unsubscribe.aspx) tagged with the ID of the User that received the email, where the User can confirm that he no longer wishes to receive such emails. The HTML is generated fully (with the text, “unsubscribe”) and requires no further editing.

Replacement Expression for “Unsubscribe” Link (all Object Types)

%OPTOUTLINK%

Generates “unsubscribe” hyperlink

To include website data in an Email Template:

All default BirdDog Email Templates display dynamic website data in the footer; this is generally not needed for custom Email Templates as this information can be just as easily entered manually, except when using the same Email Template for multiple URLs or companies.

Available Replacement Expressions for Website Data (all Object Types)

%CompanyName%

Company Name from sitesettings (or Global Settings)

%CompanyAddress%

Company Address from sitesettings (or Global Settings)

%URL%

URL of the website

%ForgotPasswordURL%

Hyperlink path to the website's Reset Password page

To include User data in an Email Template:

User-type data is used in the Default New User Acknowledgement and Default Lost Password or Default Password Recovery Templates to display some of the email recipient's personal information. Most informational emails and email campaigns will use an Email Template with the User Object Type, which allows the generated email to be “personalized” for the recipient.

Available Replacement Expressions for User Data (Object Type: User)

%FName%

User’s first name

%LName%

User’s last name

%Name%

User’s first and last name

%LoginID%

User’s website login

%Password%

User’s website password

To include Order data in an Email Template:

Order-type data is used in the Default Order Acknowledgement Template to display data relating to a specific Order that has been placed on the website or in Customer Service. A “repeater” (see Repeaters below) is available and required to display the details for each of the Order’s line-items.

Available Replacement Expressions for Order Data (Object Type: Order)

%Ord_Type%

Order type

%Ord_No%

Order number

%Order_Date%

Order date

%PO_No%

Purchase Order number

%Sales_Person.Name%

Order’s salesperson

%Terms_Description%

Order’s payment terms

%Cus_No%

Buyer’s customer number

%Bill_To_Name%

Buyer’s name

%Bill_To_Addr_1%

Buyer’s address, first line

%Bill_To_Addr_2%

Buyer’s address, second line

%Bill_To_CityStateZip%

Buyer’s city, state and zip

%Bill_To_Country%

Buyer’s country

%Ship_To_Name%

Name of the person order is to be shipped to

%Ship_To_Addr_1%

Shipping address, first line

%Ship_To_Addr_2%

Shipping address, second line

%Ship_To_CityStateZip%

Shipping city, state and zip

%Ship_To_Country%

Shipping country

%Order_Source_Enum%

Order's source

%Consumer_PO_No%

%Ship_Via_Description%

How the order is to be shipped

%ShipComplete%

“False” if some items will be back-ordered, “True” if order will only be shipped when all items are available

%Order.Status%

Order’s status code

%Freight_Pay_Code%

Order’s freight pay code

%Comments%

Comments entered with the order

%SubTotalByOrdered%

Order’s overall sub-total

%SubTotalByShipped%

Sub-total of items ordered that are to be shipped immediately

%Freight%

Order’s freight charges

%Miscellaneous%

Order’s miscellaneous charges

%TaxByOrdered%

Order’s tax charges

%TotalByOrdered%

Order’s total

To include Invoice data in an Email Template:

Invoice-type data is used in the Default Invoice Template and Default Shipping Confirmation Template to display data relating to a specific Invoice, for an Order placed on the website or in Customer Service. A “repeater” (see Repeaters below) is available and required to display the details for each of the Order’s line-items.

Available Replacement Expressions for Invoice Data (Object Type: Invoice)

%Inv_No%

Invoice number

%Inv_Date%

Invoice date

%PO_No%

Order’s Purchase Order number

%Ship_Via_Description%

Order’s Ship-Via

%Ord_No%

Order’s Order number

%Order_Date%

Order’s Order date

%Sales_Person.Name%

Name of Order’s salesperson

%Terms_Description%

Order’s payment terms

%Cus_No%

Buyer’s customer number

%Bill_To_Name%

Buyer’s name

%Bill_To_Addr_1%

Buyer’s address, first line

%Bill_To_Addr_2%

Buyer’s address, second line

%Bill_To_CityStateZip%

Buyer’s city, state and zip

%Bill_To_Country%

Buyer’s country

%Ship_To_Name%

Name of the person order is to be shipped to

%Ship_To_Addr_1%

Shipping address, first line

%Ship_To_Addr_2%

Shipping address, second line

%Ship_To_CityStateZip%

Shipping city, state and zip

%Ship_To_Country%

Shipping country

%SubTotal%

Order’s sub-total

%Freight%

Order’s freight charges

%Miscellaneous%

Order’s miscellaneous charges

%Tax%

Order’s tax charges

%Total%

Order’s total

%Due_Date%

%Payment_Amount%

%Credits%

%Amount_Due%

To include Purchase Order data in an Email Template:

Purchase Order-type data is used in the Default Purchase Order Acknowledgement Template to display data relating to a specific Purchase Order that has been placed. A “repeater” (see Repeaters below) is available and required to display the details for each of the Purchase Order’s line-items.

Available Replacement Expressions for Purchase Order Data (Object Type: Purchase Order)

%Ord_No_Formatted%

%Executed_Date%

%Type%

%Vend_No%

%Order_From_Name%

%Order_From_Addr_1%

%Order_From_Addr_2%

%Order_From_City%

%Order_From_State%

%Order_From_Zip%

%Order_From_Country%

%Buyer_Planner_Name%

%Terms_Description%

Purchase Order’s payment terms

%Acknowledge%

“False” if x, “True” if y

%Confirm%

%FOB_Description%

%Ship_Via_Description%

Purchase Order’s Ship-Via

%Comment1%

Purchase Order comments

%Comment2%

Purchase Order comments

%Comment3%

Purchase Order comments

%TotalOrdered%

Purchase Order’s total

To include Task data in an Email Template:

Available Replacement Expressions for Task Data (Object Type: Task)

%ReferenceNo%

%Reference%

Repeaters

Repeaters are a special type of Replacement Expression. The specific expression used determines the data to be returned (for example, “lines” will refer to the items in an order, when using the “Order” Object Type), and consists of a “start” and “end” expression; any markup between the two is repeated, once for each “item” within the data. In the case of HTML tables, the first row is expected to contain the column labels, and is not repeated.

To include Order Lines in an Email Template:

The following is an example Order Lines Repeater that may be pasted into your Email Template (in the “Edit HTML Source” window). The colored text is the portion that will be repeated per item.

Order Lines - Example

%startlines%
<table id="tblItems" style="margin-bottom: 10px; font-size: 8pt; width: 100\%;" cellspacing="0" cellpadding="0" border="1">
<tbody>
<tr bgcolor="#f95602">
<td>Item</td>
<td>Description</td>
<td>Quantity</td>
<td>UOM</td>
<td>Price</td>
<td align="right">Amount</td>
</tr>

<tr>
<td>%Item_No%</td>
<td>%Item.ShortDescription%</td>
<td>%Qty_Ordered%</td>
<td>%UOM%</td>
<td>$%Price%</td>
<td align="right">$%Amount%</td>
</tr>

</tbody>
</table>
%endlines%

The above should appear in the rendered email as follows:

Item	Description	Quantity	UOM	Price	Amount
[Item#1]	[Item#1 Description]	[#]	[EA]	$[Price]	$[Price×Qty]
[Item#2]	[Item#2 Description]	[#]	[EA]	$[Price]	$[Price×Qty]

Replacement Expressions for Order Lines

Object Type

 

%Line_No%

Purchase Order

Line Number

%Item_No%

Order, Invoice, Purchase Order

Item Number

%Item.ShortDescription%

Order, Invoice, Purchase Order

Item Description

%VendorItemNo%

Purchase Order

Vendor's Item Number

%Qty_Ordered%

Order, Invoice, Purchase Order

Quantity ordered

%Qty_Back_Ordered%

Order, Invoice

Quantity ordered that is on back-order

%Qty_To_Ship%

Order, Invoice

Quantity ordered that is to be shipped immediately

%Request_Date%

Purchase Order

Requested Date

%Expected_Unit_Cost%

Purchase Order

Expected Unit Cost

%UOM%

Order, Invoice, Purchase Order

Unit of Measure

%Price%

Order, Invoice, Purchase Order

Price per unit

%Amount%

Order

Price×Quantity

%Total%

Invoice

Price×Quantity

%TotalOrdered%

Purchase Order

Price×Quantity

%Comments%

Order, Invoice

Line Comments

%user_def_fld_{#}%

Order, Invoice

User-Defined Field {#}

To include Credit Card Transactions in an Email Template:

The following is an example Credit Card Transactions Repeater that may be pasted into your Email Template (in the “Edit HTML Source” window). The colored text is the portion that will be repeated per item.

Credit Card Transactions - Example

%STARTCreditCardTransactions%

%Credit_Card_Type%&nbsp;%Credit_Card_No_Masked%<br />

%ENDCreditCardTransactions%

Available Replacement Expressions for Credit Card Transactions Repeaters

%Credit_Card_Type%

Type of Credit Card associated with the transaction

%Credit_Card_No_Masked%

Credit Card ID associated with the transaction, with all but the last four digits replaced with asterisks (*)

%Authorization_No%

Authorization ID for the transaction

To include Invoice Comments in an Email Template:

The following is an example Comments Repeater that may be pasted into your Email Template (in the “Edit HTML Source” window). The colored text is the portion that will be repeated per item.

Invoice Comments - Example

%STARTComments%

<div>%Comment%</div>

%ENDComments%

Available Replacement Expressions for Invoice Comments Repeaters

%Comment%

To include Shipment Tracking Links in an Email Template:

The following is an example Shipment Tracking Links Repeater that may be pasted into your Email Template (in the “Edit HTML Source” window). The colored text is the portion that will be repeated per item.

Shipment Tracking Links - Example

%STARTManifestTrxs%

<p>Tracking #: <a href="/%Tracking_URL%">%Tracking_No%</a></p>

%ENDManifestTrxs%

Available Replacement Expressions for Shipment Tracking Links Repeaters

%Tracking_URL%

Hyperlink path to shipment tracking website

%Tracking_No%

Shipper’s tracking number/ID for the shipment

Nested Repeaters

Repeaters may be "nested" as needed, where the data is supported. Example:

To include Serial/Lot#s in Order Lines in an Email Template:

The following is an example Order Lines Repeater that may be pasted into your Email Template (in the “Edit HTML Source” window). The colored text is the portion that will be repeated per item.

Order Lines - Example

%startlines%
<table id="tblItems" style="margin-bottom: 10px; font-size: 8pt; width: 100\%;" cellspacing="0" cellpadding="0" border="1">
<tbody>
<tr bgcolor="#f95602">
<td>Item</td>
<td>Description</td>
<td>Quantity</td>
<td>UOM</td>
<td>Lot#</td>
<td>Price</td>
<td align="right">Amount</td>
</tr> <tr>
<td>%Item_No%</td>
<td>%Item.ShortDescription%</td>
<td>%Qty_Ordered%</td>
<td>%UOM%</td>

<td>%STARTSerialLotTransactions%
<div>%SerialLotNo%</div>
%ENDSerialLotTransactions%</td>

<td>$%Price%</td>
<td align="right">$%Amount%</td>
</tr>
</tbody>
</table>
%endlines%

The above should appear in the rendered email as follows:

Item	Description	Quantity	UOM	Lot#	Price	Amount
[Item#1]	[Item#1 Description]	[#]	[EA]	[Lot#] [Lot#] [Lot#]	$[Price]	$[Price×Qty]
[Item#2]	[Item#2 Description]	[#]	[EA]	[Lot#] [Lot#] [Lot#]	$[Price]	$[Price×Qty]