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
Mar 8, 2017 Update:
This article has been updated to reflect the big Gmail update that included support for responsive email.
  1. Gmail has several email clients.
  2. Gmail app for non-google accounts (GANGA) does not support background images.
  3. Gmail clips your message at 102K.
  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 Gmail is most often identified with their Webmail and mobile apps, Gmail has many different versions and incarnation. This includes Gmail's Inbox client, G Suite for business as well as a particularly problematic version of their Android client thats configured for POP/Imap access (see #2).

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. Emails accessed through this setup lack the embedded style (<style>) support as well as the support for background images.

3. Gmail clips your message at 102K.

If your email exceeds 102K, Gmail will display the first 102K 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 are close to 102K, you might save a few bytes by removing any unnecessary spaces, carriage returns or comments. 

We recommend that you avoid embedded images and documents when sending HTML emails.

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

Gmail now supports embedded styles (<style>). However embedded styles are only supported in the head of your HTML document. The Gmail Android app 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. 

Gmail does not like an '@' declaration within an '@' declaration.(see details here). 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 eliminates your style block if it exceeds 8192 characters.

If your style block exceeds 8192 characters, split it into two parts as Gmail will only remove the latter block that exceeds the treshold (the 8192 character limits is a sum of all your style blocks).

6. Gmail displays preheader text in the subject-line.

Like many modern clients, parts of the text in your body - the preheader - is automatically shown after the subject without the recipient having to open the email message. This text can be a visible part of your email body or it can be specially crafted to only display before the email is opened. This technique is covered in this article.

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

Attribute selectors like the one below allow for a more flexible selection of elements in CSS. Although they are supported in modern email clients such as iOS and Apple Mail, they are not supported by Gmail.

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

Gmail also does not support pseudo-classes like :checked and :active and only supports :hover in their Webmail email client. Therefore interactive email support in Gmail is very limited or non-existent.

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 your images larger than 300x150 are wrapped with a link, however this article goes into several other options as well.

9. Gmail does not allow negative CSS margin values.

Most webmail clients such as Outlook.com 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 version(s) 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;”

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

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

Click here 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 name@test.com within this paragraph will get converted to:

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

Here are two possible fixes:

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

&#173;­ 

So change name@test.com to:

name@test­&#173;.com 

Change www.mydomain.com to:

www.mydomain­&#173;.com 

Change http://www.mydomain.com to:

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

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”> test@test.com</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.

Similar to #7, this space is also caused by the DOCTYPE.  Here are a few workarounds (these work in Hotmail 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

Got another tip?

Got any more tips and tricks for Gmail? Feel free to share below!

Make sure your email renders nicely not just with Gmail but with all the other major email clients as well. Get started for free with our 7 day trial of Email on Acid.

TEST TODAY!

About the Author

Justin Khoo
Twitter

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.
Gibum
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.
Gibum
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;
}
</style>

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....
RJ
This is really helpful for email marketers to know why Gmail is displaying things in certain ways. Thanks.
Nate Goodman
RJ,
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!
Whatts
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
Johnb888
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.
Johne489
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?

thanks,
jennifer
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 //-->

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

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

This came from zerocents:
https://www.campaignmonitor.com/forums/topic/7405/how-to-hide-mobile-content-in-desktop-clients/
nils
Hi,
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!!!
antonio
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?
creativeass
Thanks.... it really works perfect as I want smile
Muhammad Ahmad
great guide! Thanks for this helpful post
webworldatom
Hey Guys, did you know how gmail mobile app responsive work ? if, yes please let me know. not show hide.
chintan
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.
Thanks!
Mike
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
Rombout
Excellent. "display:none !important" is most useful. Thank you for this.

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

Good show.
Schroder
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.
Alec
@Alec,

is the actual mail responsive and did you add this to the header " <meta name="viewport" content="width=device-width, initial-scale=1">
"
Rombout
@Alec
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!
Michelle

Leave a Comment