We have already solved the problem of getting UGC in to emails but how do you refresh content after you've hit send? 

Email plugin provides you with a URL to embed, which means you are able to choose (and replace) the content that appears there dynamically. To refresh an embedded media display, you simply publish fresh content to the Placement Tag that controls that URL.

We even let you automate content refreshing on a schedule – every day, every hour or every 5 mins – Candid will look for recently published content and refresh your emails. This means your recipients will always see the latest content at the time they open your email. 

Not just for email, these dynamic images can be used anywhere, including on-site banner implementations.

Getting Started

There are three steps to integrating dynamic UGC into your templates:

  1. Select Render Format
  2. Select Inclusion Criteria
  3. Embed Image Link

Render Formats

You can render a single image, a horizontal or vertical strip, or a grid with variable columns and rows. The following format strings should demonstrate the range of support:

Format Syntax
Renders a grid of 4 rows, where each cell is center cropped using a square rectangle of 600 pixels. From there 5 pixels of bottom, right margin are added.
Same as the above except all media is rendered on a single row.
Same as the above except all media is rendered in a single column.
Returns a single image in its original resolution.

The pageSize parameter controls the number of images included and is typically capped at 16. The format parameter is a combination of "<style>,<rows>,<cell-dimensions>,<margin>,<cropStyle>,<maxWidth>,<skip>,<rounded>,<label>" (all separated by commas) where maxWidth is used to restrict the size of the combined image, <skip> accepts true or false indicating whether cells should render in an alternating series, <rounded> indicates whether images in each cell should have rounded corners, and <label> allows text labels to be rendered within each cell.

Select Inclusion Criteria

The full range of query options are available in deciding what images should be used in the composite that you're embedding. You can use one or more placement tags, target specific accounts, or keywords, products, date ranges, etc. The resulting set can also be sorted by the full range of sort options that are available on the web plugins, including: Date, Published, Likes, Comments, Random, Tags, MappingTags and Custom.

Embed Image Link

Embedded image URLs share a common format that always starts with:


From there, the image format and the inclusion criteria follow a standard pattern used across the entire platform.

High-Performance Homepage Banners

High-performance homepage banners like the one below can easily be implemented using 2 image requests (one to serve the 2x2 image on the left and one to serve the 1x2 image on the right). The result is a dynamic UGC implementation that does not require any JavaScript and dramatically reduces the number and size of requests

Common Examples

The top 16 most recently approved assets from the collection displayed over 4 rows with a margin of 5px separating each cell:

<img src="//api.getcandid.com/stream/page/?id=42a0b243-61ff-4d58-bf2f-2a8591954e32&approvalFilter=Approved&format=grid,4,600,5,centercrop" />

The top 8 most recently approved assets displayed over 3 rows in an alternating series with margin of 5px separating each cell:

<img src="//api.getcandid.com/stream/page/?id=42a0b243-61ff-4d58-bf2f-2a8591954e32&approvalFilter=Approved&format=grid,3,600,5,centercrop,800,true&pageSize=8" />

The top 4 most recently approved assets from displayed in a 2x2 grid with a margin of 5px separating each cell:

<img src="//api.getcandid.com/stream/page/?id=42a0b243-61ff-4d58-bf2f-2a8591954e32&approvalFilter=Approved&format=grid,2,600,5,centercrop&pageSize=4" />

The top 5 most recently approved assets displayed in a single row with a 5px margin:

<img src="//api.getcandid.com/stream/page/?id=42a0b243-61ff-4d58-bf2f-2a8591954e32&approvalFilter=Approved&format=grid,1,600,5,centercrop&pageSize=5" />

The top 5 most recent approved content excluding the brand account:

<img src="//api.getcandid.com/stream/page/?id=42a0b243-61ff-4d58-bf2f-2a8591954e32&notterm=27852760&type=Username&approvalFilter=Approved&format=grid,1,600,5,centercrop&pageSize=5" />

The top 5 most recently approved assets displayed in a single column with a 5px margin and rounded corners:

<img src="//api.getcandid.com/stream/page/?id=42a0b243-61ff-4d58-bf2f-2a8591954e32&approvalFilter=Approved&format=grid,5,600,5,centercrop,200,false,true&pageSize=5" />

Frequently Asked Questions (FAQ)

How often does the image refresh?

By default, all images will refresh every 30 minutes. More aggressive synchronization schedules are available but must be configured at the collection level via a support ticket.

How do we implement this in Mailchimp? 

You can use the "code" content block to add this to a campaign in Mailchimp, simply select "Code" and then type in the image URL like this:

<img src="http://api.getcandid.com/stream/page/?id=c74de7b3-0d88-4480-bf8e-1e5cc7b8a590&approvalFilter=Approved&format=grid,1,600,5,centercrop&pageSize=5"></img>

Why are the images served in PNG?

Background transparency is an important consideration and not available in JPEG images.

How do we enable compression to reduce the banner size?

You can append &compress=true to the image endpoint and compare the size of the compressed versus the original. We are looking to enable more granular options on the compression algorithm but at the moment only 1 compression level is supported.

Can we serve images automatically using AI concepts found in the image?

Yes, as mentioned in the blog post Image & Video Recognition APIs To Automate Your Visual Marketing, all endpoints support the AI concept parameter.