Troubleshooting

Account settings

Before you begin troubleshooting a problem, check your account-level settings. Make sure you've enabled the following settings to test the latest experiences in the Gmail Promotions tab. These are the default settings.

  • Images: Always show.
  • Conversation view: On.
  • Enable bundling of top email: On.

Challenges with email construction

If you are having issues when building your email, the following sections might help:

Can't put code into the head

Depending on how your email construction works, the system responsible for the deal or product in the body of the email might be separate from the system that handles the HTML head, which might not know which deal to inject into the head. You can insert part or all of the script tag in the body of the email, so that the part of the system handling the deal information can inject the entire script tag or the part containing the deal <script>{"@type": "DiscountOffer", ...}</script> into the body.

Script tags get stripped by your email service provider

Schema.org provides Microdata markup that might be allowed if your ESP doesn't make an exception.

Instead of <head><script>...</script></head>, you can place Microdata anywhere in the HTML, as shown in the following example:

    <div itemscope itemtype="http://schema.org/DiscountOffer">
      <meta itemprop="description" content="20% off" />
      <meta itemprop="discountCode" content="PROMO" />
      <meta itemprop="availabilityStarts" content="2018-01-01T08:00:00-07:00" />
      <meta itemprop="availabilityEnds" content="2018-04-30T23:59:59-07:00" />
    </div>
    <div itemscope itemtype="http://schema.org/PromotionCard">
      <meta itemprop="image" content="https://www.google.com/gmail-for-marketers/promo-tab/markup-tool/sample.png" />
    </div>

You can also test this alternate method in the preview tool.

Separate script tag for easier implementation

You can split the annotation to avoid sending old content or if features come from a content block. Place a portion of the script tag in the head and the rest in a block of the body.

Here is an example of placing only the alternate subject line in the head, with the badges, expiration date, and image preview of the annotation in the body of the email:

In the <head>

<script type="application/ld+json">
  [{
     "@context": "http://schema.org/",
     "@type": "EmailMessage",
     // An alternative subject line shown when deal badge or discount code is
     // also displayed.
     "subjectLine": "Alternate Subject Line"
  }]
</script>

In the <body>

<script type="application/ld+json">
  [{
    "@context": "http://schema.org/",
    "@type": "DiscountOffer",
    "description": "20% Off",
    "discountCode": "PROMO",
    "availabilityStarts": "2019-01-01T08:00:00-07:00",
    "availabilityEnds": "2019-12-30T23:59:59-07:00"
  },{
     "@context": "http://schema.org/",
     "@type": "PromotionCard",
     "image": "https://www.google.com/gmail-for-marketers/promo-tab/markup-tool/sample.png"
  }]
</script>

Challenges viewing or testing emails

The following sections discuss common issues encountered when attempting to view or test email:

Email bundles don't appear

  • Make sure you are on a device with the latest version of the Gmail app. Refresh email by pulling down on the screen within the Promotions tab.
  • Try restarting your device.
  • Still not working? Try viewing on another device—for example, a tablet might have a different Gmail version and show the bundle differently.
  • Only consumers see the email bundles. The experience doesn't affect Google Workspace users.

Emails don't go to the Promotions tab

  • Check if the email was sent from the usual subdomain marketing emails are sent from. Sending from less recognized subdomains can confuse the Gmail tab classifier and prevent an email from being placed in the Promotions tab.
  • Make sure your account has no email filters that send email to the Primary tab.
  • Send from separate sender subdomains to ensure email ends up in the correct tab. See the Email sender guidelines for more details about the Gmail classifier.
  • If you're using a promotabtesting@gmail.com account, this is the intended behavior for the first email. Drag the email into the Promotions tab, and send an email from the same sender address, with a different subject line, to the testing account. You should now be able to view it.

Bundles appear, but annotated emails don't appear in a bundle

  • Check if the email is in the Gmail Promotions tab.
  • Ensure the email hasn't been opened yet and wasn't sent on a previous day.
  • If an email in a bundle is viewed on one device, then that email doesn't populate in a bundle again on another device. You must send a new test email to preview.
  • Create multiple testing accounts if you want to test on multiple devices. A team member might open the email, which prevents it from populating in the bundle for the rest of the team.
  • Make sure the annotation in the sent email's code is correct. If the offer is expired or hasn't started yet, the email doesn't display in a bundle.
  • Be sure you are using the latest version of the Gmail app. Try viewing on another device—for example, a tablet might have a different version of the Gmail app and show email differently.
  • Refresh the Gmail app by pulling down the Gmail Promotions tab screen.
  • Try restarting your device.
  • You can't use sensitive categories, such as adult content or debt collection, in the Gmail Promotions tab.

Image preview doesn't display when an image is included in the annotation

  • Check the script tag to ensure the correct URL is in the image property.
  • Refresh the Gmail app by pulling down the Gmail Promotions tab screen.
  • If your image involves a sensitive topic, such as adult content or debt collection, it might not display in the Gmail Promotions tab.

Bundle appears on one device, but not another

  • Make sure you are viewing from the same email account.
  • If an email is opened on one device first, it might change the ranking and not appear in a bundle on the other device.