Developing HTML Emails for Gmail: 14 Tips for Coding
While Outlook tends to get the most criticism for being temperamental, Gmail has its own share of issues that cause headaches for HTML email developers.
Gmail is one of the most popular email platforms in the world, with over 1.8 billion users. It’s also the second most popular email client, accounting for 28% of the global market share. Look at your email analytics and see what percentage of the addresses are Gmail (it’s probably a lot). If your HTML email is not displaying properly in Gmail you may be losing out on critical leads and revenue.
Ensuring that your HTML emails look great in Gmail clients can be tricky, though. Remembering to test your email can help you catch some of these, but starting with the right code and some knowledge about Gmail-specific issues will prevent hours of troubleshooting.
When coding for Gmail users, there are a few things to keep in mind
Jump to a section to find out more:
- Gmail has several email clients
- Gmail app for non-Gmail accounts (GANGA) does not support background images
- Gmail clips messages larger than 102Kb or if there are special characters
- Gmail only supports <style> in the <head>
- Gmail removes your entire <style> block if it encounters an error
- Gmail doesn’t support web fonts other than Roboto and Google Sans
- Gmail displays preheader text in the email preview
- Gmail does not support attribute selectors and most pseudo-classes
- Gmail displays an image download icon over large unlinked images
- Gmail does not allow negative CSS margin values
- Gmail automatically converts phone numbers, emails, and URLs to links
- Gmail uses the HTML5 DOCTYPE
- Gmail’s DOCTYPE can create extra space under images
- Gmail has dark mode inconsistencies between Android and iOS
1. Gmail has several email clients
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.
- Gmail webmail for desktop
- Gmail webmail for mobile
- Gmail for iOS
- Gmail for Android
- (There is no standalone desktop version)
The most problematic one is Gmail’s Android client when configured for POP/IMAP access (see tip #2), but Gmail’s issues with dark mode in iOS are also a big problem (see tip #14).
2. Gmail apps for non-Gmail accounts (GANGA) does not support embedded styles
Both Android and iOS Gmail apps contain a feature for accessing non-Gmail accounts (e.g. Yahoo! Mail, Proton Mail, etc.) using POP and IMAP. Unfortunately, emails accessed through this setup lack support for embedded styles (<style>). As of 2017, both apps added support for background images. However, background images still require a little extra effort because background-size is not supported.
To work around this, you can use shorthand CSS, which is supported:
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.
3. Gmail clips messages larger than 102kB or if there are special characters
If your email’s size exceeds 102kB, Gmail will display the first 102kB along with a message that reads:
[Message clipped] View entire message
When the subscriber clicks to view the entire message, your email will be displayed in a new window.
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 ©: ©
- N dash: –
Read more about how to avoid email clipping.
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 strips HTML formatting entirely if it encounters even one error. For example, Gmail doesn’t like an ‘@’ declaration within an ‘@’ declaration. There are a couple of situations where you might find yourself declaring an ‘@’ within an ‘@’ – when declaring a web font and when declaring a viewport for Windows Phone 8.1. 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.
Example of a web font declaration:
@media { @font-face {font-family: 'Roboto'; src: url('roboto-regular-webfont.woff') format('woff'), url('roboto-regular-webfont.ttf') format('truetype'); font-weight: normal; font-style: normal; color:#3ab97d; } }
Example of a viewport declaration:
@media only screen and (max-width:320px) { @viewport { width:320px; } }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
The idea of Google’s own web fonts not working in Gmail seems surprising and baffling, but it’s true. The only web fonts that Gmail supports are Roboto and Google Sans. You can still use web fonts in your emails, of course, just remember to use a font stack to declare fonts in order of preference and to account for varying font support across email clients.
Font stack example:
style=“font-family: ‘Roboto’, Helvetica, Arial, sans-serif;”Learn more about font stacks and the best fonts for email.
7. Gmail preheader text is displayed in the email preview
Like many modern clients, the email preheader is automatically shown after the subject in Gmail’s preview text without the recipient having to open the message. Preheader text can be a visible part of your email body or it can be specially crafted to only display before the subscriber opens your email (hidden preheaders).
Learn more about how to code hidden preheaders.
8. Gmail does not support attribute selectors and most pseudo-classes
Gmail CSS 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.
While AMP email has limited support across other clients (Gmail, Yahoo!, and Mail.ru support it, but Outlook removed support back in 2020), it’s still a great option if you have a lot of subscribers who use Gmail, Yahoo!, and Mail.ru.
Check out some examples of interactive emails using AMP for Email. Then you can use this guide from the open source AMP project to get started with AMP emails.
9. Gmail displays an image download icon over large unlinked images
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 distracting.
The simplest solution is to ensure that images larger than 300×150 are wrapped with a link, but there are several other options you can try to prevent Gmail’s image download button in HTML emails.
10. Gmail does not allow negative CSS margin values
If you’re trying to overlap page elements in your HTML email using negative margin values, you’ll find Gmail CSS not working as you intended. While negative margin values are often used in CSS for web development, they are not supported in most webmail clients like Gmail, Outlook.com, or Yahoo! Mail.
To get elements to overlap, you can try using faux absolute positioning, although this method will not work for Gmail apps with non-Gmail accounts (GANGA).
11. Gmail automatically converts phone numbers, email addresses, and URLs to links
Gmail automatically converts phone numbers, email addresses, and URLs into links – presumably for the added convenience of email users. But for email developers it’s yet another item to add to the long list of things not displaying as intended in Gmail. For example, Gmail will convert name@test.com to:
<a href=“mailto:name@test.com”>name@test.com</a>
Worse yet, the links will be default blue and underlined, which is really bad news if your background is blue. 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 ­. 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­-389­-3934
For an email address like name@test.com, you can add the entity before the period preceding the domain type:
name@test­.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. So www.mydomain.com would be written as:
www.mydomain­.com
If using the full url with http or https, also add the entity after the http: or https:. So http://www.mydomain.com would be coded as:
http:­//www.mydomain­.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.
Globally style all automatic links
If you don’t mind that Gmail is automatically applying links, but you’d just like to change their appearance to match your other links, you can use the following CSS:
<!-- wp:paragraph -->
<p><br> u+#body a {<br> color: inherit !important;<br> text-decoration: none !important;</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p> font-size: inherit !important;<br> font-family: inherit !important;<br> font-weight: inherit !important;<br>line-height: inherit !important;<br>}</p>
<!-- /wp:paragraph -->Note: Gmail will also apply the default blue, underlined link to your button links if their styles aren’t inlined.
12. 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.
Another added benefit of using the HTML5 DOCTYPE is that the code is much shorter than HTML4. In the world of email development, keeping your code as short as possible for the amount of content you need to convey is important.
HTML4:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
HTML5:
<!DOCTYPE html>
13. Gmail’s DOCTYPE can create extra space under 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.
14. Gmail has dark mode inconsistencies between Android and iOS
There are a few issues that Gmail has with dark mode between Android and iOS. The most troublesome one is that Gmail forces any light colored text to change to a dark text color in iOS. So if you created an email with white text on a black background, iOS’s dark mode will actually turn it to black text on a white background (which sort of defeats the purpose of dark mode).
Since Gmail does this not just with white text, but with any light colored text, this can create some serious accessibility and readability issues.
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:
<!DOCTYPE html>
<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.
More tips and tricks for coding for Gmail
The above are just a few examples of the biggest issues email developers face when coding for Gmail. You can learn more workarounds and helpful hints in our Tips and Tricks sections for Gmail and Google Apps and the Gmail App.
Of course, the landscape of what Gmail does and doesn’t support changes periodically, so if you have any other tricks or workarounds for Gmail, feel free to share them in the comments section below! Or, if you’re a member of the Email Geeks Slack channel, you can reach out to our own email dev, Megan Boshuyzen.
Gain confidence with email testing
No matter how experienced you are in HTML email development, it’s still important to test your email to make sure it renders correctly in Gmail and all other major email clients.
With Email on Acid, you’ll get unlimited email testing and previews on more than 70 clients and devices. Our pre-deployment checklist uses an email readiness workflow that covers end-to-end content checks, deliverability, and previews to streamline your testing process and help you get your emails out the door faster, with less stress, and looking great every time.
This post was updated on March 23, 2022. It was also updated in April 2018 and March 2017. It was originally published in June 2013.
Author: The Email on Acid Team
The Email on Acid content team is made up of digital marketers, content creators, and straight-up email geeks. Connect with us on LinkedIn, follow us on Facebook, and tweet at @EmailonAcid on Twitter for more sweet stuff and great convos on email marketing.
Author: The Email on Acid Team
The Email on Acid content team is made up of digital marketers, content creators, and straight-up email geeks. Connect with us on LinkedIn, follow us on Facebook, and tweet at @EmailonAcid on Twitter for more sweet stuff and great convos on email marketing.
13 thoughts on “Developing HTML Emails for Gmail: 14 Tips for Coding”
Comments are closed.
Hello
I like this article .
Is it possible to use these html codes on a blog.
I need your reply please.
Point number 7 is partly wrong, Gmail is reading my attribute styling, is this a new thing?
This is the CSS that it is reading (and shouldn’t be)
[class~=fallback] { display:none; }
[class~=interactive] { height:auto !important; max-height:none !important; display:block !important; font-size:inherit !important; line-height:inherit !important; }
Got any work arounds?
Hi Jade, Gmail doesn’t like [class=””], simply switching to .class will resolve this
Gmail Imap on android app
Line height is bloated. Can’t seem to stop it. Send more sanity. Help!
Imap gmail android is increasing my line height. I want to cry. Nothing works. It seems to be adding about 20%.
Is it true that Gmail strips out IDs and Classes?
Hi Al –
Good question! Support for IDs in email can be spotty, but classes should be there. Gmail may still strip the whole head tag, though, so inline styling is always needed in Gmail. Hope that helps!
Awesome tip to add display:block to images! was driving me crazy!
Cheers
Glad we could help, Steve!
Hii,
I have a question.
I want to change font of gmail which i use in HTML tag. when i sent a mail to user i want my own font show in to mail, it is possible? if yes then how?
Please suggest me.
Thank you.
What about the issue of Gmail app resizing fonts on some clients (I mostly have to deal with it on newer iPhones), and how to solve it?
does Gmail remove clip-path style?
I added `clip-path: polygon…` to my email style but when it goes to Gmail the clip-path is missing from style when I inspect it.
Is gmail support external css?