Ad placements

The ad placement code consists of HTML link and image tags pointing to your instance's delivery domain. These can be included on any email deployment, and should (ideally) be loaded into a system that supports setting custom values on the backend, as Javascript is not available in most email clients.

If you do not have a system that can support dynamically injecting values into the link and image URLs, you will need to manually generate the [...params] reference used below.

URI Parameters

• adUnitId The id of the ad unit you would like to include on the page.

• [...params] A url-encoded set of query parameters such as date=some_date&rand=1234.

  • date An ISO-8601 formatted date/time string

  • email The email address or unique identifier of the user. This should be a merge variable filled in by your ESP, such as @{encrypted_customer_id}@ or *|EMAIL|*.

  • rand A random value. This value helps ensure that views and clicks are correlated properly.

  • send An optional merge variable for the send identifier, used for future reporting efforts.

Example Implementations

Raw HTML

Placement Code

<a href="https://[mydomain].serve.email-x.io/click/[adUnitId]?[...params]" title="Advertisement">
  <img src="https://[mydomain].serve.email-x.io/view/[adUnitId]?[...params]" alt="Advertisement" width="600" height="100" border="0" />
</a>

HTML Source

// Variables used with the placement code above
[mydomain]:  test
[adUnitId]:  123456
[...params]: date=2019-01-27T10%3A16%3A09-06%3A00&email=%40%7Bencrypted_customer_id%7D%40&rand=9689172420

<a href="https://test.serve.email-x.parameter1.com/click/123456?date=2019-01-27T10%3A16%3A09-06%3A00&email=%40%7Bencrypted_customer_id%7D%40&rand=9689172420" title="Advertisement">
  <img src="https://test.serve.email-x.parameter1.com  /view/123456?date=2019-01-27T10%3A16%3A09-06%3A00&email=%40%7Bencrypted_customer_id%7D%40&rand=9689172420" alt="Advertisement" width="600" height="100" border="0" />
</a>

PHP

<?php

function getAdUnit($adUnitId, $width, $height) {
  $domain = 'https://demo.serve.email-x.io';
  $template = '<a href="%s" target="_blank"><img src="%s" width="%s" height="%s" alt="Advertisement" border="0"></a>';
  $params = [
    'date'  => date('c'),
    'email' => '*|EMAIL|*',
    'rand'  => rand()
  ];
  $linkUrl = sprintf('%s/click/%s?%s', $domain, $adUnitId, http_build_query($params));
  $imageSrc = sprintf('%s/image/%s?%s', $domain, $adUnitId, http_build_query($params));
  return sprintf($template, $linkUrl, $imageSrc);
}


echo getAdUnit('123456', 600, 100);

Handlebars

Controller

const httpBuildQuery = o => Object.keys(o)
  .map(k => `${k}=${encodeURIComponent(o[k])}`).join('&');
  
const domain = 'https://demo.serve.email-x.io';
const queryString = httpBuildQuery({
  date: new Date().toISOString,
  email: '*|EMAIL|*',
  rand: Math.floor(Math.random() * 10000),
});

module.exports = ({ adUnitId: 123456, width: 600, height: 100 }) => {
  width,
  height,
  linkUrl: `${domain}/click/${adUnitId}?${queryString}`,
  imageSrc: `${domain}/image/${adUnitId}?${queryString}`,
};

Template

<a href={{linkUrl}} title="Advertisement">
  <img src={{imageSrc}} alt="Advertisement" width={{width}} height={{height}} border="0" />
</a>

HTTP Request Definition

Ad Request

GET https://[mydomain].serve.email-x.parameter1.com/image/:adUnitId

The ad request endpoint.

Path Parameters

Name	Type	Description
adUnitId	string	ID of the Ad unit to use

Query Parameters

Name	Type	Description
date	string	An ISO-8601 formatted date/time string. This date should not be filled by an ESP, and should reflect the date the email deployment was sent.
email	string	The email address or unique identifier for the user. This value must be filled in by an ESP, and must be unique per send/open.
rand	string	A random number/string to ensure that requests are correlated properly. This value should not be filled by an ESP.

204 No image available to serve -- no line items are eligible.

302 Image served -- an eligible line item and ad was selected, the request is correlated.

HTTP 1.1 302 FOUND
Location: https://cdn.serve.email-x.parameter1.com/tenantKey/ads/e0ba03aa-11d8-457a-be48-4d249fae40e2.jpg

404 The adUnitId parameter was invalid.