Developing emails for Gmail

Gmail HTML Email Development: Why Your CSS Is Not Working (and More) 


In the ever-changing world of email marketing, understanding the ins and outs of Gmail is paramount.

We probably don’t have to tell you that a lot of people use Gmail… but we will. According to Sinch Mailjet’s new report, The path to email engagement 2024, 71% of consumers in its global survey said they have a Gmail account. That’s why mastering the art of crafting emails tailored specifically for Gmail is non-negotiable.

In this article, we’ll delve into the specific hurdles encountered when coding HTML emails for Gmail, shedding light on practical strategies for overcoming these Gmail obstacles.

Gmail CSS Support

Despite its popularity, Gmail presents unique challenges for email developers, particularly in its support – or lack thereof – of certain CSS properties. But before we get too far, it’s important to understand that there are different some types of Gmail users.

Understanding GANGA and Its Impact on Gmail Email Rendering

Whenever we’re discussing Gmail’s CSS support it’s important that we make the distinction between GANGA and non-GANGA.

GANGA (Gmail Android with Non Gmail Accounts) represents a subset of Gmail users who access their emails through non-Gmail email accounts on the Gmail app. This distinction is important because the Gmail apps render emails differently compared to the Gmail web interface, often leading to variations in email display and functionality.

Gmail’s CSS Support: Navigating the Limitations

It’s essential to consider Gmail’s CSS support and its implications on email rendering. Here’s a breakdown of a few key Gmail CSS support notes, and the challenges they present:

  1. Embedded CSS – Gmail does support embedded CSS, allowing for styling within the <style> tags directly within your <head> section of the email, but it’s not supported on the GANGA accounts we mentioned above.
  2. Dark mode limitations – Unfortunately, Gmail does not support the prefers-color-scheme media query, which many developers use for dark mode optimization. This limitation can affect the readability and visual appeal of emails for users who prefer dark mode settings.
  3. Gmail doesn’t support web fonts – Despite Google owning the largest repository of web fonts, using their own Google fonts in an email is not supported. The only two fonts that are supported are Robot and Google Sans.

13 tips for coding HTML emails for Gmail

We’ve compiled our top tips for coding HTML emails for Gmail. If you’re having issues or you just want to optimize your email creation process for Gmail, this list has you covered!

1. Gmail clips messages larger than 102kB

This is by far one of the most common Gmail tricks utilized for email developers. If your email’s size exceeds 102kB, Gmail will display the first 102kB along with a message that reads:

[Message clipped]  View entire message

If you’re close to 102kB, you can save a few bytes by removing any unnecessary spaces, line breaks, or comments. You also want to avoid embedded images and documents when sending HTML emails.

Additionally, if your email has special characters that aren’t properly encoded, Gmail will clip it. Make sure all special characters are encoded correctly to prevent this from happening. Below are a couple of examples of special character encoding.

  • Copyright symbol ©: &copy;
  • N dash: &ndash;

If you’re working with larger emails, you’ll want to make sure you condense your code as much as possible. If you need more help getting your email under 102kb check out our Gmail clipping guide.

2. Gmail has several email clients

Usually when you’re coding emails, you’re only worrying about the differences between Desktop and Mobile clients, the GANGA issue with Gmail that we discussed earlier adds an extra layer of complexity.

While Gmail has simplified its interfaces over the years, there are still several different email clients with different levels of CSS support and other quirky variations when rendering HTML emails.

3. Gmail apps for non-Gmail accounts (GANGA) does not support embedded styles

Whenever the Gmail app is accessed with a non-Gmail account, embedded styles will no longer be rendered.

Luckily, in 2017 Google added support for background images. Although we can’t use the background-size CSS that we utilize for a lot of email clients we can use short-hand CSS like so:

background: url(‘image.jpg’) center / cover no-repeat #3ab97d;

If you test this and see that your background image is still not rendering for GANGA emails in Gmail’s Android or iOS app, it may be because of another little rendering quirk. On both apps, images are blocked by default for GANGA emails.

Normally, you will see a link to display the blocked images, but if your email only uses a background image and doesn’t include any other images, this link will not display. Make sure that if you’re using a background image you also include a regular image so that the “display images” link will appear.

4. Gmail only supports <style> in the <head>

Gmail does support embedded styles (<style>). However, Gmail style tags support is limited to the head of your HTML document. Gmail, Android, and iOS apps do not support <style> at all when rendering emails retrieved through non-Gmail accounts (GANGA).

5. Gmail removes your entire <style> block if it encounters an error

Gmail will strip all of your <style> block if it encounters anything it considers an error. The most common occurrence of this is when you’re nesting @ declarations (placing @ within @s), this is often used when declaring web fonts or declaring a viewport for Windows mail.

If you’re using these declarations in your code, wrap them in their own style tags and put the styles that are Gmail-safe in the top block.

Gmail also eliminates your style block if it exceeds 8192 characters. If your style block exceeds this character limit, split it into two parts. Gmail will remove the first block that exceeds the 8192-character threshold and any blocks after it (the character count includes all of your style blocks).

6. Gmail doesn’t support web fonts other than Roboto and Google Sans

It might seem crazy, but Gmail does not support its own Google Fonts. Gmail exclusively supports Roboto and Google Sans as web fonts. While this limitation may come as a surprise, it’s essential to adapt by utilizing font stacks to declare preferred fonts in emails. This approach ensures compatibility across email clients.

Read our complete guide on utilizing font stacks for cross-client font support.

7. Gmail lacks support for attribute selectors and pseudo-classes

If your Gmail CSS is not working correctly, check whether you’re using attribute selectors and pseudo-classes in your code.

Although attribute selectors (like the one below) allow for more flexibility when selecting elements in CSS, Gmail doesn’t support them.

div[class="content"]{ color: red }

Gmail also doesn’t support pseudo-classes like :checked and :active and only supports :hover in their webmail client. Therefore, interactive email support in Gmail is very limited or non-existent unless you use AMP for Email.

8. Avoiding image download icons in Gmail

If an image isn’t wrapped in a URL, Gmail will overlay an icon that lets recipients download the image. At worst, this icon could obscure important information in your image. At best, it just looks unprofessional.

Gmail download images icon

The best solution for removing this annoying icon is to ensure all your images have a link. There are a few other solutions if this isn’t doing the trick for you, including setting the image as a background image or using something known as a sibling selector. Find out more in our handy guide on preventing Gmail from displaying the image download icon.

9. Gmail does not allow negative CSS margin values

Using negative margin values in CSS is a very common web development technique to overlap page elements. Unfortunately, it’s not supported at all in Gmail.

To achieve this overlapping effect in your emails, you’ll need to use the Faux-positioning technique, though this itself is not supported in GANGA. Make sure you take a deep dive into your analytics before you employ any of these techniques.

10. Coding phone numbers and emails in Gmail

Gmail streamlines user experience by automatically converting phone numbers, email addresses, and URLs into clickable links, enhancing convenience. However, for email developers, this feature adds to the catalog of elements that may not display as intended in Gmail. For instance, Gmail transforms “name@test.com” into:

<a href=“mailto:name@test.com”>name@test.com</a>

Worse yet, the links will be default blue and underlined. Mostly, this auto-linking issue is just a bit of an eyesore, but it can cause problems if you’re using fake domains for the purpose of creative expression (e.g. dabomb.com) or if you simply don’t want a piece of information to be clickable.

Here are three potential fixes, depending on the results you’re after:


Use an HTML entity that Gmail doesn’t recognize

If you don’t want certain phone numbers, emails, or URLs in your email to be automatically wrapped in a link, use an HTML that Gmail does not recognize, such as &#173;. This will keep Gmail from recognizing the text as something that should be auto-linked.

For phone numbers, you would insert this entity before each dash. So the phone number 212-389-3934 would be coded as:

212&#173;-389&#173;-3934

For an email address like name@test.com, you can add the entity before the period preceding the domain type:

name@test­&#173;.com

To prevent a URL from being automatically converted to a link, you would code it like you would an email address and add the entity to the period preceding the domain type and after the http://. So http://www.mydomain.com would be written as:

http:&#173;­//www.mydomain­&#173;.com

Insert an anchor tag around your text and style it

If you just want your text to look as if it hasn’t been converted to a link, you can always wrap it in an anchor tag and style it to match the surrounding text. For example:

<a href=“#” style=“color:#000; text-decoration:none”>name@test.com</a>

It will still be a clickable link on hover, but it won’t look like a link and will be much less likely to be clicked on.

11. Gmail uses the HTML5 DOCTYPE

If you specify a DOCTYPE other than HTML5 in your email, you’ll find that it won’t render the same way in Gmail as it does in a browser or in an email client that respects your DOCTYPE. This is because Gmail renders all emails using the HTML5 DOCTYPE.

This is an issue that is not exclusive to Gmail. Many other email clients force HTML5, including Yahoo! Mail, Outlook.com, and Yandex on Mobile and Desktop Webmail; Inbox and Yahoo! Mail on iOS; and Inbox on Android. Apple Mail and Outlook both support whatever DOCTYPE you want to use, but since most other email clients support only HTML5, it’s best to just stick with the HTML5 DOCTYPE for your emails.

If you’re interested in reading more about how Doctypes affect your email code, you can check our guide here.

12. Gmail DOCTYPE causes extra space around images

Gmail’s HTML5 DOCTYPE can create extra space under your images. This is especially problematic if you’re using sliced images (although it’s probably best to avoid using sliced images anyway). Extra spacing where it’s not wanted can also detract from your email’s aesthetic and make reading it more difficult. 

To avoid this issue, here are a few workarounds (these work in Outlook.com and Yahoo! as well):

1. Add style display:block to the image element
<img src=“test.jpg” style=“display:block”>

2. Add align absbottom in the image element
<img src=“test.jpg” align=“absbottom”>

3. Add align texttop to the image element
<img src=“test.jpg” align=“texttop”>

4. Add line-height 10px or lower in the containing TD
<td style=“line-height:10px”>

5. Add font-size 6px or lower in the containing TD
<td style=“font-size:6px”>

Still having image spacing issues and the above fixes are not working? Learn about other workarounds for image spacing.

13. Gmail’s dark mode inconsistencies

Gmail encounters several challenges with dark mode compatibility across Android and iOS platforms.

Among these, a significant concern arises when Gmail compels light-colored text to transition into dark text on iOS. For instance, if an email is composed with white text against a black background, iOS’s dark mode reverses it to black text on a white background, undermining the essence of dark mode.

This behavior isn’t limited to white text but extends to any light-colored text, leading to potential accessibility and readability complications.

Rémi Parmentier wrote a very thorough article about how to combat dark mode inconsistencies in Gmail for Android and iOS using CSS blend modes. His example code is included below:

<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Fixing Gmail’s dark mode issues with CSS Blend Modes</title>
    <style>
        u + .body .gmail-blend-screen { background:#000; mix-blend-mode:screen; }
        u + .body .gmail-blend-difference { background:#000; mix-blend-mode:difference; }
    </style>
</head>
<body class="body">
    <div style="background:#639; background-image:linear-gradient(#639,#639); color:#fff;">
        <div class="gmail-blend-screen">
            <div class="gmail-blend-difference">
                <!-- Your content starts here -->
                Lorem ipsum dolor, sit amet, consectetur adipisicing elit.
                <!-- Your content ends here -->
            </div>
        </div>
    </div>
</body>
</html>

The solution is limited to white text only, but it should still be helpful if you need to come up with a workaround for the dark mode issues in iOS.

Learn more about dark mode email development challenges and how to tackle them.

What about Gmail and AMP for Email?

AMP (short for Accelerated Mobile Pages) is an open-source framework launched by Google in 2015. It provides a straightforward way to create web pages that are fast, smooth-loading, and prioritize user-experience. AMP for Email was publicly released for Gmail Web in 2019, allowing users to include AMP components within emails.

AMP for Email functions via a novel mark-up and infrastructure which allows interactive elements like carousels, forms, dynamic data, and APIs to be inserted in the email body.

Email developers seeking to elevate their campaigns beyond traditional static content can harness the power of AMP for Email to deliver more engaging and personalized experiences to their subscribers. With AMP developers can create emails that dynamically adapt to user interactions, providing tailored content and functionalities based on recipient actions. This not only enhances user engagement but also enables email marketers to track and analyze recipient interactions in real-time, facilitating data-driven campaign optimization.

If you’re interested in experimenting with AMP for email you can read our post about it here or check out the official AMP documentation.

Gmail’s sender guidelines for 2024

In early October 2023, Gmail and Yahoo announced new requirements for bulk senders looking to deliver mail to those using their services. While the strictest standards mainly impact those who send thousands of emails every day, even those with lower send volumes should consider updating their practices.

The new bulk sender requirements mainly deal with the following areas:

We took a deep dive into what you’ll need to do to get delivered to Gmail and Yahoo.

If you’re looking for an email deliverability solution that can help you reach Gmail inboxes, check out Mailgun Optimize. It’s a complete deliverability suite that integrates with Google Postmaster Tools, helps you monitor authentication protocols, and much more.

Conquer Gmail with Sinch Email on Acid Testing

Between GANGA, image changes, link styling, doctypes and more we covered a lot of Gmail CSS support intricacies that can affect the way your email campaigns render in subscribers’ inboxes.

That’s where Sinch Email on Acid testing comes into play, it’s crucial that you run extensive tests for everything we’ve discussed in this article. Our testing tools allow you to quickly and efficiently check these different versions of Gmail and ensure your emails are rendering as you intend.

Our Email Previews include Gmail options on a wide range of Android operating systems and devices as well as dark mode previews. Looking good on Gmail matters and Email on Acid helps you deliver your best.

Do More in Less Time with Email on Acid

Stop switching back and forth between platforms during pre-deployment and QA. With Sinch Email on Acid you can find and fix problems all in one place. Double check everything from content to accessibility and deliverability. Plus, with accurate Email Previews on more than 100 of the most popular clients and devices, you can confidently deliver email perfection every time.

Start for Free