Best Practices

Email annotations let you include images, deals, expiration dates, and other offers to help bring your emails to life. By using high-quality images and the most relevant information, your emails are more likely to be highlighted at the top of the Gmail Promotions tab.*

This section outlines best practices for annotating your email messages.


Create a special Gmail testing account for your team ending in, for example This special account will have more aggressive email ranking and bundling to make testing easier and faster. We also enable features for these testing accounts before enabling them for the general public.

Single image preview

  • Avoid text only. This space was designed to highlight the visual components of your promotional email. To improve performance, try using product or lifestyle images.
  • Crop well. Any image size can work, and images are center-cropped automatically. Sample images are 538 x 138 pixels in size and have a 3.9 aspect ratio. GIF and WEBP images are not supported.
  • Avoid reusing images. Keep your promotional email fresh and engaging by using unique images. Email messages that reuse the same image may be disregarded as duplicates by users.

Deal Badge

Highlight any offerings such as "20% off" or "Free Shipping". Avoid using more than four words or full sentences in this space, as it competes with your subject line. There is no set character limit for the deal badge, however, when your email text space is full, the deal badge truncates (for example, "...").

  • Don’t repurpose. Use promotional offerings to ensure clarity and simplicity. Don't utilize the deal badge for other actions like "Open now".
  • Don’t use run-on sentences. Avoid saying things like "25% off unless you’ve already purchased from us in which case other ..." Long sentences are truncated.

Logo URL

Be sure to use an https (not http) URL. This logo selection only shows in the email preview.

Discount Code

Only use a discount code if you have it featured in the email. Don't repurpose this space, as it always says "Code" before the text.

Expiration Date

  • Using this feature allows an email two opportunities to preview at the top in a bundle: once when it is first sent and again within 3 days of the offer expiring.

  • Don’t leave an expired date in the annotation, as it will be read as an old offer and the email will not populate into a bundle.

  • Be sure to specify the time and timezone (for example, "availabilityEnds": "2018-12-30T23:59:59-0700"). For more information date formatting, see Format date and time.

* Emails are grouped automatically based on a number of factors.

Subject Line

Use this annotation to avoid duplicate text between the subject, deal badge, and discount code. This alternative subject is shown only when the discount code or deal badges are also shown. For example, if the original subject is "20% off sale ends today", and the deal badge is "20% off", set EmailMessage.subjectLine to "Sale ends today" to avoid repetition.