Click to Sign Up for a 7 Day Free Trial!

Email Development

Developing HTML Emails for Gmail: 12 Things You Must Know

Email On Acid

This post was updated on April 12, 2018. It was last updated in March 2017 and originally published in June 2013.

Many email developers know how tricky Gmail can be – it’s one of the more temperamental clients out there (although it’s no Outlook).

Remembering to test your email can help you catch some of these problem areas, and starting with the right code and some knowledge will help, too. It’s also important to look at your email analytics to find out how many of your subscribers use Gmail. Luckily, Email on Acid can help you do both.

If you find yourself coding for Gmail users, here are a few things to keep in mind:

  1. Gmail has several email clients.
  2. Gmail app for non-Google accounts (GANGA) does not support background images.
  3. Gmail clips your messages larger than 102Kb.
  4. Gmail only supports <style> in the <head>
  5. Gmail removes your entire <style> block if it encounters an error.
  6. Gmail displays preheader text in the subject line.
  7. Gmail does not support attribute selectors and most pseudo-classes.
  8. Gmail displays an image download icon over large unlinked images.
  9. Gmail does not allow negative CSS margin values.
  10. Gmail automatically converts phone numbers and URLs to links.
  11. Gmail uses the HTML5 DOCTYPE.
  12. Gmail's DOCTYPE can create extra space under images.

1. Gmail has several email clients.

Although many people most often associate Gmail with webmail and mobile apps, Gmail has many different versions and incarnation. This includes Gmail's inbox client, G Suite for businesses, as well as a particularly problematic version of their Android client that's configured for POP/IMAP access (see tip #2 for more information).

Want to learn more? Check out this article from Remi Parmentier has published an article on the different Gmail clients.

2. Gmail app for non-Google accounts (GANGA) does not support background images.

The Gmail Android app that comes pre-installed with most new Android phones contains a feature to access non-Google accounts using POP and IMAP. Unfortunately, emails accessed through this setup lack the embedded style (<style>) support as well as the support for background images.

As of December 2017, the iOS Gmail app also supports IMAP accounts. However, like the Android app, the iOS version does not support embedded CSS or the style tag.

3. Gmail clips messages larger than 102kB.

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 user 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, carriage returns or comments. You also want to avoid embedded images and documents when sending HTML emails.

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

Gmail does support embedded styles (<style>). However, embedded styles are only supported in the head of your HTML document. The Gmail Android and iOS apps does not support <style> at all when rendering emails retrieved through non-Google accounts (GANGA).

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

Gmail is very finicky when it comes to parsing embedded styles. If it encounters even one error, it throws away the entire block. 

For example, Gmail does not like an '@' declaration within an '@' declaration. One way to deal with this is to use multiple style blocks and put the styles that are Gmail safe in the top block.

@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 8192 characters, 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 displays preheader text in the email preview.

Like many modern clients, the email preheader is automatically shown after the subject without the recipient having to open the email 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). This article explains how to code hidden preheaders.

7. Gmail does not support attribute selectors and most pseudo-classes.

Attribute selectors (like the one below) allow for a more flexibility when selecting of elements in CSS. Although they are supported in modern email clients such as iOS and Apple Mail, Gmail does not support them.

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

Gmail also does not 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.

Gmail did announce in early 2018 that it will be rolling out Accelerated Mobile Pages (AMP) for Email, which will allow for fully interactive emails in Gmail.

8. Gmail displays an image download icon over large unlinked images.

Gmail will overlay an icon that lets recipients download images that are not wrapped with a URL. This can be frustrating to designers who would rather Gmail not mess when their email designs.

The simplest solution is to ensure that images larger than 300x150 are wrapped with a link, but there are several other options you can try.

9. Gmail does not allow negative CSS margin values.

Most webmail clients such as and Yahoo! Mail do not allow negative margin values and Gmail is no exception.

10. Gmail automatically converts phone numbers and URLs to links.

Both the desktop and mobile versions of Gmail now insert an anchor link around phone numbers. In the desktop version, the link opens Google’s new voice/chat console which is displayed along the right column of the Gmail interface.

To block this, use an HTML entity in your phone number that Gmail does not recognize such as “&#173;”


In the above example, we inserted this entity before each dash.

Check out this article for more examples and fixes.

If you have a URL or email address listed without a link, Gmail will add it for you.  For example, Gmail will convert within this paragraph will get converted to:

<a href=“”</a

Here are two potential fixes:

1.) Insert an HTML entity that Gmail does not recognize, like:


Which means you should change to:


Change to:


Change to:


2.) Insert an anchor around the URL or email address and format it like the rest of your text.  For example:

<a href=’#’ style=“color:#000; text-decoration:none”</a

11. Gmail uses the HTML5 DOCTYPE.

Regardless of the DOCTYPE specified in your email, the email will be rendered using the HTML5 DOCTYPE in Gmail. This may cause your email to render differently than if you loaded your email in a browser.

12. Gmail's DOCTYPE can create extra space under images.

This space is also caused by the DOCTYPE.  Here are a few workarounds (these work in and Yahoo! Beta, 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”

For more workarounds, check out this blog article: 12 Fixes for Image Spacing

Do You Have Other Gmail Tips?

If you have any other tricks or workarounds for Gmail, feel free to share them in the comments section below! Or, you can hit us up on Facebook or Twitter.

But remember, even with these workarounds, it is still important to test your email to make sure it renders correctly in Gmail and all the other major email clients. With Email on Acid, you'll get unlimited email testing and previews on more than 70 clients and devices. Try our platform free for seven days and see for yourself.

About the Author

Justin Khoo

Justin Khoo

Justin Khoo (@freshinbox) is an email developer and writes about email techniques and new innovations. He has been involved in many aspects of email over the past decade, everything from building webmail clients and email campaign services to coding HTML emails.

Join the Discussion

I've noticed the Gmail app on the App Store for iPhone (currently using 4S) is very clunky to use and a nightmare to code for. Some of the issues are random texts displaying in green, weird padding from nowhere and random image slices seem to have a margin added on the right. I'm baffled because the desktop and native Mail app for the iPhone displays the same mail perfectly.
After a few hours of testing, I finally found the issue:

Our emails are designed in 650px. However, the Gmail App automatically makes images resize to 600px, percentage-based. If you have a nested table on a row with copy and a image, the does not resize, causing this weird margin on the right to appear. I've brought it up to my company that we should probably adopt a 600px composition to avoid this issue. I did a quick test and reverted the composition to be 600px and it works fine.

As for the weird green text, it's a gmail thing. If you send the same email 2 times or more to a testing email within a certain time frame, gmail displays random copy in different colors.

I hope this helps someone having the same issue.
Gmail does accept the style tag in the head section, subsequently it does accept css*...

your example:

<style type=“text/css”>
/*This is for all clients except Gmail,
Gmail gets the same declarations from the body tag */
table, tr, td, p, span {
font-family:Arial, Helvetica, sans-serif;
color:#333; font-size:11px;

actually works too in the head section btw.

BUT....their are limitations to the css*

this feature was made live in june.

*there maybe a workaround, but i havent found it yet....
This is really helpful for email marketers to know why Gmail is displaying things in certain ways. Thanks.
Nate Goodman
I just did a couple tests and it seems that Gmail is still stripping the style block. What CSS did you get it to accept in the style block?
Geoff Phillips
Great, the trick with the special character stopped gmail from displaying links where there shouldn't be any. Thanks!
Wow! I have long been looking for a step by step guide on how to exactly do this. You're genius!
Jim Barracael
very nice article. understand this problem
gmail sign in
Hey does anybody know how to display html stuff on gmail. I tried- <Paragraph> and it just prints <Paragraph> instead of :(
Does anyone know how to solve this issue ?
Mohit Kumar
Great guide, thanks for the info.
Matt C
Woah! I'm really loving the templatetheme of this website. It's simple, yet effective. A lot of times it's hard to get that perfect balance between usability and visual appeal. I must say you have done a great job with this. In addition, the blog loads super quick for me on Firefox. Excellent Blog! dkddeabagkad
I was just seeking this info for some time. After six hours of continuous Googleing, at last I got it in your web site. I wonder what is the lack of Google strategy that don't rank this kind of informative websites in top of the list. Generally the top sites are full of garbage.
Gibum, I had the green text problem too when viewing emails on the Gmail app on iOS. In my case, changing the CSS colour definition to the full hex value fixed it.

Before: #FFF; // Shows up green
After: #FFFFFF; // Shows up white

Hope that helps anyone else with the same problem
Michael Voong
Hi I am doing a responsive email and the email generates fine for every provider even on my phone except for GMAIL. I have to add a background color in the pre-header area and everytime i do that it extends longer than the email. is there a media query or fix for that?

Jennifer Navarro
Gmail also appears to remove padding on header, main and footer tag.

Fixed this by putting a div inside them and do the styling there.
Albert Diones
Very helpful, thanks! If you need to hide elements with media queries you can use this solution:

<!--// The Invisible Div //-->

@media all and (max-device-width: 480px) {
*[class*="mobile-only"] {
display: block !important;
max-height: none !important;

<!--[if !mso]><!-->
<div class="mobile-only" style="font-size: 0; max-height: 0; overflow: hidden; display: none">
<!--// Everything inside is invisible to desktop //-->

This came from zerocents:
Great article. I make advanced css html signature and your post is really helpful.

Would be helpful to know if there is a work around for the minus on margin padding.
Yann de Champlain
this is really helpful, thanks a million!!!
You say in your article that
style=“display:none !important;”
will work in Gmail but it doesn't work on the Gmail app on iPhones - I've tried using it in conjunction with:
max-height: 0px; font-size: 0px; overflow: hidden;

in various guises on the wrapping table, the image and even wrapping the table in a div and nothing is working - does anyone have any ideas?
Thanks.... it really works perfect as I want smile
Muhammad Ahmad
great guide! Thanks for this helpful post
Hey Guys, did you know how gmail mobile app responsive work ? if, yes please let me know. not show hide.
Hi, I can't seem to find the right fix to stop Gmail for android auto sizing and yet keep my email responsive for other clients. I've read that by adding the style="min-height" property to the container table that is the same width and has the fixed width will stop Gmail for android auto sizing, and it does indeed work by stopping it.
However, now I've noticed the email clients that would normally be responsive on a mobile device stop working. The min-height that was added to the container table now takes precedence over the media query width of that same container table.

If anyone has overcome this hurdle for Gmail for android auto sizing and keeping email responsive please reply! Only thing I can think is possibly adding some sort of gmail class that gets hidden in a media query.
It seems like my photos are now becoming too saturated when I embed them in gmail. I've made them RGB and I never had this problem before.
ilene y kulk
How can i get rif od the margin Gmail adds to paragrahps. Ive tried inline tool and also set all margins manually. BUt gmail keeps adding and replacing my own
Excellent. "display:none !important" is most useful. Thank you for this.

More ... "<body style=" ..." " most valuable.

Good show.
Hi all

Im having on going issues with Gmail app displaying the very small desktop view of my email rather than responsive version displayed in all other mobile email clients. The template i am using is 2 column thats breaks in 2 places: @media only screen and (max-width: 680px) and @media only screen and (max-width: 480px) {

Any tips much appreciated.

is the actual mail responsive and did you add this to the header " <meta name="viewport" content="width=device-width, initial-scale=1">
Hi, create a (1row, 5 col) table inside a full width td, and put blank image in all column (same width), don't for get to hide the table for mobile view. Thank you
Md Hashem
Any recommendations on e-mail forwarding out of g-mail? It will completely lost all of the css in the head element.
Hilary Engelbrecht
Thank you for this article. Fixed my image spacing issue in gmail!
Thanks for this article, but it's way too much extra work (sticking w/inline styles) - Google needs to get their stuff together, for real.
One day Google will hire programmers that actually know what they're doing and support something called STANDARDS (if not a standard, then support the common design patterns). Just about every email client on the planet can read style tags (properly). Unbelievable we still have to write spaghetti HTML to fit their poor design. Google's lost their innovators, for sure.
Beefy Dog
I liked your article. Did you know that Google has introduced Gmail Go? Go not only takes up significantly less space on your phone, but uses less data than the standard Gmail app.
Rae Trac
Such a great article, with the help of your post it makes advanced CSS HTML signature it would be very helpful to know if there is a workaround for the minus on margin padding. thanks for sharing
Yandex Customer Service

Leave a Comment