while outlook tends to get the most criticism for being temperamental, gmail has its own 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 is 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 addresses are gmail (it’s probably a lot). If your HTML email isn’t displaying correctly in Gmail, you may be missing out on critical leads and revenue.
However, making sure your html emails look good in gmail clients can be tricky. remembering to test your email can help you spot some of these, but starting with the right code and some knowledge of gmail-specific problems will save hours of troubleshooting.
When programming for gmail users, there are a few things to keep in mind
jump to a section for more information:
- gmail has multiple email clients
- gmail app for non-gmail accounts (bargain) does not support background images
- gmail clips messages from more than 102 kb or if there are special characters
- gmail only supports <style> in the <head>
- gmail remove all the <style> block if error
- gmail doesn’t support web fonts other than roboto and google sans
- gmail shows preheader text in 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 css margin values negatives
- gmail automatically converts phone numbers, emails and urls into links
- gmail uses html5 document type
- gmail document type can create extra space below images
- gmail has dark mode inconsistencies between android and ios
1. gmail has multiple email clients
Although gmail has simplified its interfaces over the years, there are still several different email clients with different levels of css support and other wacky variations when processing html emails.
- gmail webmail for desktop
- gmail webmail for mobile
- gmail for ios
- gmail for android
- (there are not a standalone desktop version)
Most problematic is gmail android client when configured for pop/imap access (see tip #2), but gmail issues with dark mode on ios is also a big issue (see tip #2). #14).
2. gmail apps for non-gmail (bargain) accounts don’t support embedded styles
The Gmail apps for Android and iOS contain a feature to access non-gmail accounts (eg yahoo! mail, proton mail, etc.) via pop and imap. Unfortunately, emails accessed through this setting do not support embedded styles (<style>). As of 2017, both apps added support for background images. however, background images still require a bit of extra effort because background size is not supported.
To avoid this, you can use shorthand css, which is supported:
If you try this and see that your background image is still not displaying for bargain emails in the gmail android or ios app, it may be due to another small rendering quirk. In both apps, images are blocked by default for bargain emails.
Normally, you will see a link to display blocked images, but if your email only uses a background image and does not include any other images, this link will not be displayed. make sure that if you are using a background image, you also include a regular image so that the “show images” link appears.
3. gmail trims messages larger than 102 kb or if there are special characters
if your email size exceeds 102kb, gmail will display the first 102kb along with a message that says:
[message cropped] view full messageWhen the subscriber clicks to view the full message, their email will be displayed in a new window.
if you are close to 102 kb, you can save some bytes by removing unnecessary spaces, line breaks or comments. you also want to avoid embedded images and documents when sending html emails.
Also, if your email has special characters that are not encoded correctly, gmail will trim it. make sure all special characters are encoded correctly to prevent this from happening. below are a couple of examples of encoding special characters.
- copyright symbol ©: ©
- n dash: –
read more about how to prevent email clipping.
4. gmail only supports <style> in the <head>
gmail supports embedded styles (<style>). however, support for gmail style tags is limited to the header of your html document. gmail, android and ios apps do not support <style> at all when processing emails retrieved through non-gmail accounts (bargain).
5. gmail deletes all your <style> block if it finds an error
gmail removes the html formatting altogether if it finds a single error. for example, gmail doesn’t like an ‘@’ statement within an ‘@’ statement. There are a couple of situations where you might find yourself declaring an ‘@’ inside 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 your own style tags and put the gmail-safe styles in the top block.
example of a web font declaration:
example of a viewport declaration:
gmail also removes your style block if it exceeds 8192 characters. if your style block exceeds this character limit, split it into two parts. gmail will delete the first block that exceeds the 8192 character threshold and any subsequent blocks (character count includes all of your style blocks).
6. gmail does not support web fonts other than roboto and google sans
The idea of google web fonts not working in gmail seems surprising and puzzling, but it’s true. the only web fonts supported by gmail 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 account for variable font support in email clients.
source stack example:
Learn more about font stacks and the best fonts for email.
7. gmail preheader text is displayed in email preview
Like many modern clients, the email preheader is automatically displayed after the subject in the gmail preview text without the recipient having to open the message. the preheader text can be a visible part of the body of your email or it can be specially designed to be displayed only before the subscriber opens your email (hidden preheaders).
learn more about encoding hidden preheaders.
8. gmail doesn’t support attribute selectors and most pseudo-classes
gmail css not working properly? check if you are using attribute selectors and pseudo classes in your code. Although attribute selectors (like the one below) allow more flexibility when selecting elements in css, gmail doesn’t support them.
gmail also doesn’t support pseudo-classes like :checked and :active and only supports :hover in its webmail client. therefore interactive email support in gmail is very limited or nonexistent unless you use amp for email.
While amp email has limited support in other clients (gmail, yahoo!, and mail.ru support it, but outlook dropped support in 2020), it’s still a great option if you have a lot of subscribers who use gmail. yahoo! and mail.ru.
see 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 is not wrapped in a url, gmail will overlay an icon that will allow recipients to download the image. In the worst case, this icon could hide important information on your image. at best, it just seems distracting.
The simplest solution is to make sure images larger than 300×150 are wrapped with a link, but there are several other options you can try to avoid the gmail image download button in html emails.
10. gmail does not allow negative css margin values
if you are trying to overlay page elements in your html email using negative margin values, you will find that gmail css doesn’t work as expected. While negative margin values are often used in CSS for web development, they are not supported by most webmail clients such as Gmail, Outlook.com, or Yahoo! mail.
To make the elements overlap, you can try using fake absolute positioning, though this method won’t work for gmail apps with non-gmail accounts (bargain).
11. gmail automatically converts phone numbers, email addresses, and urls into links
gmail automatically converts phone numbers, email addresses, and urls into links, presumably for the convenience of email users. but for email developers, it’s yet another item to add to the long list of things not displaying as expected in gmail. for example, gmail will convert name@test.com to:
Worse yet, links will default to blue and be underlined, which is really bad news if your background is blue. For the most part, this autolinking issue is just a bit annoying, but it can cause problems if you’re using fake domains for creative expression purposes (eg dabomb.com) or if you just don’t want a piece of information that can be done click.
here are three possible solutions, depending on the results you are looking for:
uses 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 included in a link, use an html that gmail doesn’t recognize, like . this will prevent gmail from recognizing the text as something that should be linked automatically.
for phone numbers, you would insert this entity before each hyphen. so the phone number 212-389-3934 would be encoded as:
212-389-3934
for an email address like name@test.com, you can add the entity before the dot before the domain type:
name@test.com
To prevent a url from automatically becoming a link, I would encode it like an email address and add the entity to the dot before the domain type. so www.mydomain.com would be written as:
www.mydomain.com
if you use the full url with http or https, also add the entity after http: or https:. then http://www.mydomain.com would be encoded as:
http://www.mydomain.com
insert an anchor tag around your text and style it
If you just want your text to look like it hasn’t been converted into a link, you can always wrap it in an anchor tag and style it to match the surrounding text. for example:
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.
globally style all autolinks
if you don’t mind gmail applying links automatically, but would like to change their appearance to match your other links, you can use the following css:
note: gmail will also apply the default underlined blue link to your button links if their styles are not aligned.
12. gmail uses the html5 document type
if you specify a document type other than html5 in your email, you will find that it will not display the same way in gmail as it would in a browser or email client that respects your document type. this is because gmail processes all emails using the html5 document type.
this is a problem that is not unique to gmail. many other email clients force html5, including yahoo! mail, outlook.com and yandex on desktop and mobile webmail; inbox and yahoo! mail on ios; and inbox in android. apple mail and outlook support any document type you want to use, but since most other email clients only support html5, it’s best to stick with the html5 document type for your emails.
Another benefit of using the html5 document type is that the code is much shorter than html4. In the world of email development, it’s important to keep your code as short as possible for the amount of content you need to convey.
html4:
html5:
13. gmail document type can create extra space below images
gmail’s html5 document type can create extra space below your images. this is especially problematic if you’re using split images (although it’s probably best to avoid using split images anyway). extra space where you don’t want it can also detract from the aesthetics of your email and make it difficult to read.
To avoid this problem, here are some solutions (also works on outlook.com and yahoo!):
1. add display:block style to image element
2. add align absbottom on image element
3. add align top of text to image element
4. add a line height of 10px or less in the container td
5. add a font size of 6px or less in the td container
Still having issues with image spacing and the above fixes don’t work? Learn about other workarounds for image spacing.
14. gmail has dark mode inconsistencies between android and ios
there are some problems that gmail has with the dark mode between android and ios. the most problematic is that gmail forces any light colored text to change to a dark text color on ios. So if you created an email with white text on a black background, iOS Dark Mode will actually convert it to black text on a white background (which defeats the purpose of Dark Mode).
Because gmail does this not only with white text, but also with any light-colored text, this can create some serious accessibility and readability issues.
rémi parmentier wrote a very comprehensive article on how to combat dark mode inconsistencies in gmail for android and ios using css blended modes. The sample code for it is included below:
The solution is limited to white text only, but it should still be useful if you need to find a solution for dark mode issues on ios.
Learn more about the challenges of dark mode email development and how to address them.
more tips and tricks for coding for gmail
The above are just a few examples of the biggest problems email developers face when coding for gmail. You can get more workarounds and helpful tips in our tips and tricks sections for gmail and google apps and 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 very own email developer, megan boshuyzen.
gain confidence with email testing
Regardless of how experienced you are with developing html email, it’s still important to test your email to make sure it displays correctly in gmail and all other major email clients.
With Email on Acid, you get unlimited email previews and proofs on 70+ clients and devices. our pre-deployment checklist uses an email preparation workflow that covers content checks, deliverability, and end-to-end 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 March 23, 2022. It was also updated April 2018 and March 2017. It was originally published June 2013.