Sections

Images

Foreground images

Section titled Foreground images

All email clients can display .png, .gif, and .jpg images displayed with the <img> tag. .svg images are not well supported, regardless of how they’re referenced, so avoid using these.

Most images should be coded responsive by default, meaning they’ll scale down proportionately in small viewports. It’s safest to code all images this way, even if they don’t end up scaling in practice. However if we’re confident that an image will never scale, we can display a non-responsive image using less code.

Foreground image attributes

Section titled Foreground image attributes
Name Type Notes
src attribute Always set and use full https:// reference.
width attribute Always set to intended desktop width.
height attribute Optional. Use only for images that won’t scale.
border attribute Always set to 0 to avoid blue outlines on image links.
alt attribute Always include but can be left empty if image is ornamental (Eg. alt="").
width inline CSS [Responsive] Always set to 100% for responsive images. Optional for static images.
max-width inline CSS [Responsive] Always set to intended desktop width. Optional for static images.
height inline CSS [Responsive] Always set to auto for responsive images. Optional for static images.
display inline CSS Generally good practice to use `display:block;` when possible since it negates a few pixels of unwanted space below images in some clients.
.g-img class Advisable for images larger than ~300px wide. Prevents gmail from displaying an image download icon over images.

Foreground image examples

Section titled Foreground image examples
/* Responsive */
<img src="https://placehold.it/1280x600" width="640" height="" alt="alt_text" border="0" style="width: 100%; max-width: 640px; height: auto; display: block;" class="g-img">

/* Static */
<img src="https://placehold.it/256" width="128" height="128" alt="alt_text" border="0" style="display: block;">
alt_text
alt_text
Note: Every image that should scale down in small screens should have a width: 100%; max-width: (desktop-width)px; in it's style="" attribute. (desktop-width)px; is the largest size an image should appear in on desktop. This allows images to scale down when their desktop width exceeds the width of its container.

Background images

Section titled Background images

Background images allow us to place additional HTML content on top of them, one of the few reliable ways to provide layering possibilities in email. A benefit of using background images over foreground images is, when paired with a background color, the HTML content on top of the background image remains accessible even when images are disabled.

Background images can be complicated to implement in email, as many properties need to be defined once in CSS and again in VML for Windows Outlook and Win10 Mail.

Background image attributes

Section titled Background image attributes
Name Type Notes
background-image inline CSS Always set and use full https:// reference.
background-position inline CSS Optional to set the size of the image.
background-size inline CSS Optional to set the position of the image.
background-color inline CSS Always set to make foreground HTML legible if background image doesn’t load.
width VML in <v:rect> Always set to full container width. VML doesn’t account for padding, adjust as necessary.
height VML in <v:rect> Always set to full container height. VML doesn’t account for padding, adjust as necessary.
src VML in <v:fill> Always set and use full https:// reference.
color (background color) VML in <v:fill> Always set to make foreground HTML legible if background image doesn’t load.

Background image examples

Section titled Background image examples
<td valign="middle" style="background-image: url('https://d2axdqolvqmdvx.cloudfront.net/857c3f94-f791-401e-85a8-e041ec72569e/bgheropatternblue.png'); background-position: center center; background-size: cover; background-color: #117FF1; text-align: center;">
    <!--[if gte mso 9]>
    <v:rect xmlns:v="urn:schemas-microsoft-com:vml" fill="true" stroke="false" style="width:680px;height:220px;">
    <v:fill type="tile" src="https://d2axdqolvqmdvx.cloudfront.net/857c3f94-f791-401e-85a8-e041ec72569e/bgheropatternblue.png" color="#117FF1"/>
    <v:textbox inset="0,0,0,0">
    <![endif]-->
    <div>
        <!-- Foreground Content : BEGIN -->
        <table align="center" border="0" cellpadding="0" cellspacing="0" role="presentation">
            <tr>
                <td style="padding: 60px; color: #ffffff; font-family: arial, sans-serif; font-size: 15px; text-align: center;">
                    Foreground HTML content.
                </td>
            </tr>
        </table>
        <!-- Foreground Content : END -->
    </div>
    <!--[if gte mso 9]>
    </v:textbox>
    </v:rect>
    <![endif]-->
</td>
Foreground HTML content.
Note: Windows Outlook and Win10 Mail cannot scale background images, so the image referenced in VML should be prepared @1x. Most other email clients can scale background images defined in CSS, so using @2x images is advisable.

How should images be prepared?

Section titled How should images be prepared?

Email has largely standardized on PNG, JPG, and GIF file formats. Animated GIFs are supported in all email clients, though Windows Outlook and Win10 Mail only display its first frame.

SVG is not well supported in most web email clients, including Gmail (which accounts for most of our email opens) and are completely blocked in Outlook. This includes base64 encoded images.

  • Foreground images should be saved at @2x since they scale reliably in all major email clients. @2x images display crisply on high-definition displays when scaled down to @1x in code.
  • Background images should be saved at @1x since they don’t scale reliably in all major email clients.

Ideally, images should be under ~100KB. Tools like Image Optim, Krackin, and TinyPNG help bring down a file size. Keep in mind that animated GIFs tend to get very large, so it’s a good idea to keep them simple and use them sparingly.

Images should be hosted within their respective ESP. Upload images in Iterable for Iterable emails, add images in GitHub for StackMail emails, etc. Images should not be referenced using services like Imgur or Dropbox, as they have a greater chance of being marked as spam.

Animated GIFs

Section titled Animated GIFs

Animated GIFs can help explain an interaction or add a bit of delight that isn’t possible with static email designs. However there are a couple things to consider when designing and preparing animated GIFs.

  1. Support: Every email client displays animated GIFs, but some don't animate them. Windows Outlook shows only the first frame, so it's important that all vital information is included in the first frame of the GIF.
  2. File size: Animated GIFs are prone to excessive file sizes. The rule of thumb is to try to keep animated GIFs under ~1MB. However, it's OK to include a good-looking animated GIF with a large file size provided the rest of the email is relatively small.
Edit on GitHub