1. Home
  2. Docs
  3. REST API
  4. API Reference
  5. Mailing Templates and Mail Merge Shortcodes

Mailing Templates and Mail Merge Shortcodes

The template resource allows programmatic definition of the template used by mailings sent from FeedBlitz. Templates defined with this resource are considered “Advanced” and, if edited manually in FeedBlitz, will use the advanced template editor (ATE).

Resource path: /template/<listid>

Methods:         GET, POST, DELETE, PUT

Example:         /template/84

The best way to understand this resource is to define a template manually in the FeedBlitz user interface (it need not be activated), and then GET it with this method.

When saving a template using PUT or POST, the 1st three elements are required. You can save a template deactivated if you wish; if not specified initially, the template is inactive. If a list’s template is inactive, it uses the account’s master template (if specified in the UI) or the FeedBlitz default template otherwise.

IMPORTANT:A template that is incorrectly defined (e.g. the shortcodes don’t match up) will revert to the FeedBlitz default. It is important to test a template concept on a test list, or interactively at https://app.feedblitz.com/f/?preview=<listid> to ensure the results are what you expect.

You should also build in responsiveness and bear in mind that HTML for email apps is massively different from that for the web. Simply C&Ping a web page will not work. Again, testing is key.

Tag Comment
<fromname> The friendly name of the sender. Required for PUT / POST
<fromaddress> The email address in the “From” column. Also used for replies if the recipient responds to the mailing, whether manually or via out-of-office email autoresponder. Required for PUT / POST
<template> HTML template to be used. Required for PUT / POST
<active> 0 – inactive 1 – active
<mastertemplate> 0 – template is NOT the master for the account 1 – template is the master for the account

Note: All text fields should be encoded to ensure XML validity.

Note: Inactivating a template prevents all elements of the template (master template, sender name, address and the template itself) from being used.

Note: For POST and PUT, the <mastertemplate> value is optional. If not specified, the account’s master template ID is unchanged. If you set a list to be the master template, it will make sure that a prior master template record is removed (i.e. you don’t have to explicitly disable master template on the prior list if you’re switching the master template from a prior list to this one).

FeedBlitz Template Shortcodes (Custom Tags and Mail Merge Personalization)

These tags can substitute in custom values at email generation time.

Personalizing and Mail Merge

As well as the short codes below, you can insert any custom field or tag value into a mailing by using code of the form <$fieldname$> – so if you have a custom field called “JobTitle” you would insert that into the template as <$JobTitle$>. You can insert custom fields anywhere in the template, including URLs used by the <$Feed$> shortcode.

Of course, when you do that you want to take into account when fields are empty and the effects you want to see, using conditional shortcodes.

Conditional Mail Merge: <$if$>

You insert segment expressions as logical tests inside <$if$> <$else$> <$endif$> shortcodes.

<$else$> is optional; you can nest conditional layers. 

As an example, you can so this:

<$if JobTitle="CEO"$>Hail to the Chief!<$else$>Hello there, minion.<$endif$>

Note that custom field names are not adorned with <$$> when used as expressions. Here’s a more practical example, assuming you have a field called “Name”,  to create a personalized salutation:

<$if Name<>""$>Dear <$Name$>,<$else$>Hi there,<$endif$>

The FeedBlitz Visual Mailing Editor (VME) has a personalization builder that can be used to build these expressions interactively.

Shortcodes Reference

<$BlogTitle$>The name of the blog (without enclosing quotes).
<$BlogPosting$>Indicates the start and stop of a single post or feed item.

There must be exactly two <$BlogPosting$> tags – The content between these two is repeated for each post in the mailing.

It is usually easiest to start with a standard FeedBlitz template or one built using the easy template editor and then edit. 

You can also use <$BlogBlock$> tags to subdivide the post section – see this article for more.
<$BlogRecipient$>The recipient’s email address.
<$BlogDescription$>This is used to place the email subject line (without the prefix) into the body of the text. It varies depending on whether there are more than one entries in the update.
<$BlogURL$>The blog’s home page URL.
<$BlogItemTitle$>The title of this post.
<$BlogItemUrl$>The link (permalink) URL for this entry.
<$BlogItemBody$>The text of an individual blog entry.
<$BlogItemNumber$>The ordinal value for this entry in the mailing. Used for automatic index construction.
<$BlogItemAuthor$>The author of the entry, if known, or of the entire feed, if available.
<$BlogIndex$>Indicates the part of the template used to construct a table of contents for the email. Content between these tags is replicated for each post.

If you use them, there must be exactly two <$BlogIndex$> tags

Advanced use: If the first of a pair of the <$BlogIndex$> tags is written like this <$BlogIndex$ tag=”1″> then the table of contents is written in 2 columns, with articles organized by tag. We strongly recommend previewing your newsletter before saving the template using this advanced version.
<$BlogItemCount$>The total number of entries included in this update.
<$BlogViewOnline$>Pastes in the URL of this mailing’s online archive, so the subscriber can access it via a web browser.
<$BlogFTAF$>Provides a link to forward to a friend – Sends the entire email to one or more contacts.
<$BlogNoLandingPage$>Text between a pair of these tags is removed from web-based landing pages, including the signup form, confirmation landing page, import courtesy emails and unsubscribe forms. 

There must be an even number of <$BlogNoLandingPage> tags. 

If you have an odd number of these tags, all graphics after the trailing tag will be removed on the relevant pages.
<$Date$>In subject lines, this is the date of the email formatted as YYYY/MM/DD 

In item posts, this is the date and time of the entry’s publication, formatted as YYYY/MM/DD HH:MM ZZZ where ZZZ is the US time zone of the main FeedBlitz server.
<$Date format=”formatstring“$>Format the date using a custom formatstring. The formatstring codes are the same as used in C programming library strftime function (see examples below). Here are some common examples for February 9, 2008, 2:45 PM

<$Date format=”%m/%d/%Y”$>
02/09/2008

<$Date format=”%d.%m.%Y”$>
09.02.2008

<$Date format=”%Y-%m-%d”$>
2008-09-02

<$Date format=”%a, %b %d %Y, %I:%M %p”$>
Sat, Feb 09 2008, 2:45 P.M.

<$Date format=”%B %d %Y, %H:%M”$>
February 09 2008, 14:45

<$Date format=”%A – %H:%M”$>
Saturday – 14:45

All times are formatted in US English, US eastern time zone.
<$Feed=url$>Insert a different RSS feed into the template, e.g.

<$Feed=https://feeds.feedblitz.com/feedblitz$>

After the opening Feed tag use regular template tags (including a pair of <$BlogPosting$>) tags to define how the new feed should be inserted. Close the third party RSS feed section with a simple <$Feed$> tag.

Articles from the included feed will be altered according to the parent feed’s content settings (e.g. maximum character limits) unless overridden with attributes (see below). You may have multiple <$feed$> blocks in your template.
<$Feed=url
 count=number
maxchars=number
maxcount=number
index=number 
raw=number$>
Count, maxchars, maxcount, index, and raw are optional attributes when including third party feeds in your template.

count
Always coerce the number of articles shown from the included feed, regardless of their time stamps.

maxchars
Abridge or extend the content inserted by the <$BlogItemBody$> tag when inside the <$feed$> block.

index
Start inserting RSS articles other than the most recent entry (the top article is index zero, so use the number 1 to start at the next one, etc.).

raw
Use raw=”1″ to insert posts feed as-is, without any modification by the template (i.e. no extra social sharing icons).

maxcount
Restricts the number of posts included, so maxcount=”2″ restricts the section to two posts, even if under the automatic campaign’s schedule more would have be included.
<$BlogItemThumbnailImage
width=number 
height=number
background=color
align=value
style=css$>
Inserts a thumbnail image, and removes that image from the content inserted by <$BlogItemBody$>. It has four optional attributes: width, height, background, align. Most of the time, you will only need to specify the thumbnail’s width.

Width
Force the image to be this many pixels wide. Optional.

Height
Force the image to be this tall. Optional.

If you specify BOTH width and height, the thumbnail will be forced to the width specified, and limited to the height you define. In the majorty of email apps, the image will be scaled correctly and any excess beyond the specified height will be cropped. In desktop Outlook, however, the image will be forcibly resized to fit the box; this is a result of the weakness of Outlook’s HTML rendering, and may affect the aspect ratio.

Background
Specify a background color for any space in the thumbnail slot the image doesn’t occupy. Optional; Leave blank for transparent, which is the default. Color specification is HTML / CSS, so for red you can use “background=#FF0000″ or “background=#F00″ or “background=red”

Align
Force the image to float left or right. Optional; the default is left aligned. Specify “left” or “right” here ,as in “align=right″

Style
Supply your own CSS to attach to the thumbnail

If there is no image associated with the post, FeedBlitz will use the icon image associated with the feed. If there isn’t one, it will use a blank image to fill the space.
<$BlogDeletableItemThumbnailImage$>Exactly the same as <$BlogItemThumbnailImage$> (including the optional extra parameters), except that in the event no featured image is found, a blank image is always inserted.
<$BlogItemFeaturedImage$>Inserts the URL of the first non-trivial image into the template, and removes that image from the content inserted by <$BlogItemBody$>
<$BlogFloatImagesRight$>Place this tag once inside the <$BlogPosting$> area to cause FeedBlitz to try and align allimages in the article to the right. Useful for wrapping text around images (such as thumbnails) when the underlying RSS does not.
<$BlogFloatImagesLeft$>Place this tag once inside the <$BlogPosting$> area to cause FeedBlitz to try and align allimages in the article to the left. Useful for wrapping text around images (such as thumbnails) when the underlying RSS does not.
<$BlogFlowTease$>Place this tag once inside the the <$BlogPosting$> area and, if you truncate your articles the call to action “teaser” text will be appended to the end of the article without any additional line breaks. Otherwise the default behavior is used, where the teaser text is placed in a new paragraph by itself.
<$BlogItemTag$>Picks one tag from the post, if there. If there is more than one tag or category then a single tag is picked randomly.
<$BlogItemTags$>Places a | separated list of all the post’s tags and categories into the mail
<$BlogItemTags sep=”separator“$>Places a separator separated list of all the post’s tags and categories into the mail. Enclose the separator you want with single or double quotes.
<$BlogViewOnline$>Creates the link to the lists’s online archive. Depending on use, the link is either to the main public archive index or to the subscriber’s personal archive.
<$BlogPreferencesLink$>Pastes in the URL to the subscriber’s preferences page, where they can edit non-hidden custom fields and access a portal with all the lists you offer without logging in.
<$BlogUnsubLink$>Pastes in the URL to the subscriber’s unsubscribe page. FeedBlitz automatically adds unsubscription links at the foot of the page, but you can use this URL to add removal links elsewhere in the template if you wish.
<$BlogNoTransactionalEmail$>Text between a pair of these tags is removed from transactional (i.e. subscriber dual opt-in activation) emails, but will otherwise appear on landing pages and broadcast email blasts. 

There must be an even number of <$BlogNoTransactionalEmail> tags. 

If you have an odd number of these tags, all elements after the trailing tag will be removed from activation emails.
<$BlogItemAd$>Forces the position of an ad FeedBlitz inserts as part of our ad program, overriding the placement set in your ad profile.
<$FieldLookup FieldName$>When a custom field is inserted into the mailing, the value stored in the database is used. For multi-select custom fields, FeedBlitz allows you to define the value stored in the database (e.g. an SKU #) and friendly text (e.g. the product name associated with the SKU). This short code inserts the associated friendly name, not the database value. If no description for the field value has been entered, the field value is inserted as if it were a normal custom field mail merge.
<$BlogSiteFeedUrl$>Inserts the RSS feed URL powering the list’s automated campaign settings.
<$BlogArchivesLink$>Links to the mailing’s archive personalized for the recipient.