Newsletter ads (beta)

  • Google Ad Manager enables the display of reservation and Programmatic Guaranteed ads within email newsletters through newsletter ads.

  • Implementation involves creating an ad unit and line item in Ad Manager, along with a backup house line item, crafting a newsletter ad tag, and inserting it into your newsletter.

  • The newsletter ad tag comprises an HTML image element nested within an anchor element, accompanied by an "About this ad" link, and uses specific parameters for ad serving and tracking.

  • Several parameters, including ptt, iu, sz, clkk, clkp, url, and t, are used within the ad tag to define the ad request and targeting.

  • Detailed instructions and examples are provided to guide users through the setup and troubleshooting process for newsletter ads.

Newsletter ads can be used to display Google Ad Manager reservation and Programmatic Guaranteed ads in email newsletters. This guide describes how to implement newsletter ads in your email newsletters.

Overview

Here's the high level workflow for implementing a newsletter ad:

  1. Create or select an Ad Manager ad unit.
  2. Create or select an Ad Manager line item. Remember the following guidelines:
    • Expected creatives must contain all of the sizes of the ad creatives you expect to appear in newsletters.
    • Targeting must include the ad unit from step 1.
    • Only image creatives are supported for newsletter ads.
  3. (Recommended) Configure a house line item to serve as a backup, in the event an ad doesn't fill.
  4. Craft a newsletter ad tag.
  5. Insert the newsletter tag at the spot where you want the ad to appear in your newsletter.

Newsletter ad tag format

A newsletter ad tag consists of an HTML image (img) element, nested inside of an HTML anchor (a) element. Each newsletter ad tag must be followed by an "About this ad" link, to provide information to users about the ad displayed.

<!-- Newsletter ad tag -->
<a href="JUMP_URL?AD_PARAMETERS" target="_blank">
  <img src="AD_URL?AD_PARAMETERS">
</a>

<!-- "About this ad" link -->
<a href="JUMP_URL?AD_PARAMETERS&click_type=wta">About this ad</a>

The formats of the anchor href and image src URLs are as follows:

JUMP_URL https://securepubads.g.doubleclick.net/gampad/jump
AD_URL https://securepubads.g.doubleclick.net/gampad/ad
AD_PARAMETERS ptt=21&iu=AD_UNIT_PATH&sz=CREATIVE_SIZES&clkk=CLKK_VALUE&clkp=CLKP_VALUE&url=URL&t=TARGETING_KEY_VALUES

See the example section for a complete newsletter ad tag example using mock values.

Here is a detailed explanation of the supported newsletter ad parameters:

Parameters
ptt

Must always be set to 21 to indicate this is a newsletter ad request.

Required Yes
iu

An ad unit path, which identifies the Ad Manager ad unit to display.

Ad unit paths must have the following format:

/network-code/[parent-ad-unit-code/.../]ad-unit-code

  • network-code is a unique identifier for the Ad Manager network the ad unit belongs to. When using Multiple Customer Management (MCM), both parent and child network identifiers should be provided as parent,child.
  • parent-ad-unit-code are the codes of all parent ad units (only applies to non-top level ad units).
  • ad-unit-code is the code for the ad unit to be displayed.
All ad unit codes included in the ad unit path must adhere to the formatting rules specified by Ad Manager.

Example Top-level ad unit: /123/homepage
Multi-level ad unit: /123/sports/baseball
MCM: /123,456/homepage
Required Yes
sz

The sizes of the ad creatives eligible to appear in this ad slot.

Make sure the sizes listed here match the sizes selected in the Expected creatives field of your selected line item.

Multiple sizes may be specified, separated by a pipe (|) character. The entire value for this parameter must be URL-encoded.

Example Sizes: 216x36, 300x50, or 320x50
Size string: 216x36|300x50|320x50
Parameter value: 216x36%7c300x50%7c320x50
Required Yes
clkk

A string that is unique per recipient, per email campaign.

Every newsletter ad included in your email must specify a unique clkk value. However, each individual newsletter ad tag must specify the exact same clkk value in both its anchor href and image src URLs.

To generate the clkk value, you need to use the merge tag feature provided by your email service provider (ESP). “Merge tags” are dynamic and customizable variables in emails such as *|DATE:d/m/y|*. The exact name of the merge tag feature varies by ESP.

The clkk value is, in short, a concatenation of multiple merge tag variables and will look something like *|UNIQID|*_*|CAMPAIGN_UID|*_*|DATE:d/m/y|*. The available variables and syntax are ESP-dependent, so your clkk value might not follow this format exactly.

To generate a clkk value:

  1. Locate your ESP's documentation on “merge tags”.
  2. Determine the combination of merge tag variables that, when concatenated, produce a string that is unique per user and per email campaign.
  3. Concatenate these variables to form the clkk value.

Required Yes
clkp

A string that uniquely identifies a single newsletter ad placement.

This parameter is required when multiple newsletter ads are included in an email. If your newsletter contains only a single ad placement, this parameter may be omitted.

Example 1, 2, top, middle, bottom
Required Yes, when multiple ad placements are present
url

The “view in browser” URL for the current newsletter.

The url value should be populated from the "view in browser" URL merge tag provided by your email service provider (ESP). “Merge tags” are dynamic and customizable variables in emails such as *|ARCHIVE|*. The exact name of the "view in browser" URL merge tag varies by ESP.

Required Yes
t

Targeting key-values.

Keys and values are separated by an equals (=) character, and multiple key-value pairs are separated by an ampersand (&) character. Each key and value, as well as the complete targeting string, must be URL-encoded.

Existing restrictions for key-values apply to newsletter ads. See Get started with key-values for details.

Example
Key Value
genre comedy
movie Lilo & Stitch
Targeting string: genre=comedy&movie=Lilo%20%26%20Stitch
Parameter value: genre%3Dcomedy%26movie%3DLilo%2520%2526%2520Stitch
Required No

Example

Here's an example of what a complete newsletter ad tag would look like for a set of mock values.

Ad unit path (iu) /1/example_ad_unit
Creative sizes (sz) 216x36|300x50|320x50
Unique string per email (clkk) *|UNIQID|*_*|CAMPAIGN_UID|*_*|DATE:d/m/y|*
Ad position (clkp) top
Targeting (t) genre=comedy&movie=Lilo & Stitch
View in browser URL (url) *|ARCHIVE|* 
<!-- Newsletter ad tag -->
<a
  href="https://securepubads.g.doubleclick.net/gampad/jump?ptt=21&iu=/1/example_ad_unit&sz=216x36%7c300x50%7c320x50&clkk=*|UNIQID|*_*|CAMPAIGN_UID|*_*|DATE:d/m/y|*&clkp=top&url=*|ARCHIVE|*&t=genre%3Dcomedy%26movie%3DLilo%2520%2526%2520Stitch"
  target="_blank">
  <img
    src="https://securepubads.g.doubleclick.net/gampad/ad?ptt=21&iu=/1/example_ad_unit&sz=216x36%7c300x50%7c320x50&clkk=*|UNIQID|*_*|CAMPAIGN_UID|*_*|DATE:d/m/y|*&clkp=top&url=*|ARCHIVE|*&t=genre%3Dcomedy%26movie%3DLilo%2520%2526%2520Stitch">
</a>

<!-- "About this ad" link -->
<a
  href="https://securepubads.g.doubleclick.net/gampad/jump?ptt=21&iu=/1/example_ad_unit&sz=216x36%7c300x50%7c320x50&clkk=*|UNIQID|*_*|CAMPAIGN_UID|*_*|DATE:d/m/y|*&clkp=top&url=*|ARCHIVE|*&t=genre%3Dcomedy%26movie%3DLilo%2520%2526%2520Stitch&click_type=wta">
  About this ad
</a>

Frequently asked questions

How do I generate a valid clkk value?

Refer to the clkk parameter reference.

What combination of merge tag variables should I use to form the clkk value?

Since available merge tag variables and appropriate syntax vary depending on your Email Service Provider (ESP), we can't advise on or verify your clkk values. We recommend that you refer to your ESP's documentation to identify a combination of variables that will give you an string which is unique per user and per email campaign.

Here's the documentation for some commonly used ESPs:

How do I know if my clkk value is correct?

When your clkk value is correct, it generates a string that's unique per user and per email campaign. To verify this, you should generate test emails, click the ads contained within them, ensure you're directed to the correct destination URL, and that clicks are being reported in Google Ad Manager.

If you haven't already, we strongly recommend that you review the newsletter ad tag reference to learn more about generating correct clkk values. Here are some important requirements:

  • The combination of "merge tags" that make up a clkk value must be unique per user and per email campaign. If your clkk value contains only one variable (for example, clkk=%UMF_MD5), it is most likely not unique enough.
  • An individual ad placement must specify the same clkk value in both its anchor href and image src URLs. If the href and src for a given newsletter ad don't have the same clkk value, the ad won't serve properly and may have unexpected behaviors.

Why are ads not appearing in my newsletters?

Here are some common issues that might cause newsletter ad insertion to fail:

  • The newsletter ad tag is incorrect.
    • The HTML anchor href and image src parameters don't match.
    • The ad URL does not include the ptt=21 parameter.
    • The tag contains empty spaces.
    • There are typos or parameters not concatenated with an ampersand (&).
    • Merge tags introduce invalid characters when rendered by your ESP.
    • Contains PII such as email address or credit card number.
  • The ad unit path is incorrect.
  • The line item is not active.

Why are users landing on an incorrect page after clicking an ad?

This is likely due to a clkk value that isn't unique. Refer to the clkk parameter reference for details.

Why are clicks not being reported in Ad Manager reporting?

Here are two possible reasons:

  1. Your ESP's click tracking feature has been turned on, impacting Google's ability to record clicks.
  2. Your clkk value is incorrect. Refer to the clkk parameter reference for details.

How do I know if my ESP's click tracking feature is turned on?

Refer to your ESP's documentation or reach out to their customer support for more information.

How can I show different creative sizes depending on the type of device or screen size?

You can use CSS @media queries to dynamically size creatives based on browser viewport size. In the following example, when the viewport width is at most 480px, the ad img element (identified by class="ad") occupies 100% of its parent container width; when the viewport width is at least 480px, it occupies only 50% of its parent container width. The aspect ratio of the ad remains the same in both cases, as long as no other size is specified for the HTML img element.

<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <style>
      @media only screen and (max-width: 480px) {
        .ad {
          width: 100%;
        }
      }
      @media only screen and (min-width: 480px) {
        .ad {
          width: 50%;
        }
      }
    </style>
  </head>
  <body></body>
</html>