# Newsletter ads (beta)

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](https://support.google.com/admanager/topic/10478086).
2. Create or select an [Ad Manager line item](https://support.google.com/admanager/answer/9405477). Remember the following guidelines:
   - [Expected creatives](https://support.google.com/admanager/answer/9405477#expected-creatives) must contain all of the sizes of the ad creatives you expect to appear in newsletters.
   - [Targeting](https://support.google.com/admanager/answer/9405477#targeting) must include the ad unit from step 1.
   - Only image creatives are supported for newsletter ads.
3. (Recommended) Configure a [house line item](https://support.google.com/admanager/answer/79305) to serve as a backup, in the event an ad doesn't fill.
4. Craft a [newsletter ad tag](https://developers.google.com/publisher-tag/tagless/newsletter-ads#newsletter-ad).
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](https://support.google.com/admanager/answer/2695279)
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=https://developers.google.com/publisher-tag/tagless/newsletter-ads#ptt&iu=https://developers.google.com/publisher-tag/tagless/newsletter-ads#iu&sz=https://developers.google.com/publisher-tag/tagless/newsletter-ads#sz&clkk=https://developers.google.com/publisher-tag/tagless/newsletter-ads#clkk&clkp=https://developers.google.com/publisher-tag/tagless/newsletter-ads#clkp&url=https://developers.google.com/publisher-tag/tagless/newsletter-ads#url&t=https://developers.google.com/publisher-tag/tagless/newsletter-ads#t ` |

> [!IMPORTANT]
> **Important:** **AD_PARAMETERS** for the anchor `href` and img `src` of a newsletter ad tag and it's "About this ad" link must match.

See the [example section](https://developers.google.com/publisher-tag/tagless/newsletter-ads#example-tag) 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](https://support.google.com/admanager/answer/177203), 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` - <var translate="no">network-code</var> is a [unique identifier](https://support.google.com/admanager/answer/7674889#network-code) for the Ad Manager network the ad unit belongs to. When using [Multiple Customer Management (MCM)](https://support.google.com/admanager/answer/9579170), both parent and child network identifiers should be provided as `parent,child`. - <var translate="no">parent-ad-unit-code</var> are the codes of all parent ad units (only applies to non-top level ad units). - <var translate="no">ad-unit-code</var> 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](https://support.google.com/admanager/answer/1628457#ad-unit-codes) specified by Ad Manager. <br /> |---|---| | **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](https://support.google.com/admanager/answer/9405477#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](https://www.w3schools.com/tags/ref_urlencode.ASP). |---|---| | **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. > [!CAUTION] > **Caution:** If you don't provide a unique clkk value for each individual newsletter ad, users may be directed to an incorrect or blank page, and you may see inaccurate reporting. 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. <br /> > [!WARNING] > **Warning:** You must not pass any information to Google that Google could use or recognize as [personally identifiable information (PII)](https://support.google.com/admanager/answer/7686480). IP addresses cannot be used as `clkk` input. |---|---| | **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` | <br /> 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. <br /> |---|---| | **Required** | Yes | |
| `t` | Targeting [key-values](https://support.google.com/admanager/answer/188092). 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](https://www.w3schools.com/tags/ref_urlencode.ASP). Existing restrictions for key-values apply to newsletter ads. See [Get started with key-values](https://support.google.com/admanager/answer/188092) for details. > [!WARNING] > **Warning:** You must not pass any information to Google that Google could use or recognize as [personally identifiable information (PII)](https://support.google.com/admanager/answer/7686480). IP addresses cannot be used as key-value input. |---|---| | **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](https://developers.google.com/publisher-tag/tagless/newsletter-ads#clkk).

### 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:

- [Adobe Marketo](https://experienceleague.adobe.com/docs/marketo/using/product-docs/demand-generation/landing-pages/personalizing-landing-pages/tokens-overview.html)
- [Bloomreach](https://documentation.bloomreach.com/engagement/docs/jinja)
- [HubSpot](https://knowledge.hubspot.com/website-pages/personalize-your-content)
- [Mailchimp](https://mailchimp.com/help/all-the-merge-tags-cheat-sheet/)
- [SailThru](https://getstarted.sailthru.com/developers/zephyr-syntax/zephyr-syntax-overview/)
- [Salesforce Marketing Cloud](https://help.salesforce.com/s/articleView?id=sf.mc_es_personalization_strings.htm&type=5)

### 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](https://developers.google.com/publisher-tag/tagless/newsletter-ads#newsletter-ad) 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](https://developers.google.com/publisher-tag/tagless/newsletter-ads#clkk) 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](https://developers.google.com/publisher-tag/tagless/newsletter-ads#clkk) 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](https://developer.mozilla.org/en-US/docs/Web/CSS/@media) 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>