Hypermatic Docs

# Troubleshooting Emailify

# Non-Emailify Modules

At the moment, if you add a frame or element to an Emailify frame, it will be treated as a full width image layer. We'll be working towards making it easier for you to create/add your own bespoke modules in a future release!

# Setting image format overrides

Emailify will automatically detect if a layer contains areas of full transparency and set PNG as the default export format, otherwise it will be set to JPG. You can override this to set the export format of any layer to JPG or PNG by adding your own export setting.

# Border radius not showing in Outlook

Unfortunately, the border-radius property isn't supported in Outlook, so it will always fall back to normal square edges instead. Please see the border-radius support list (opens new window) for a better idea of which email clients support this CSS property.

# The random "1px line" Outlook bug

There's a very annoying issue known as the Outlook 1px line bug (opens new window) that randomly appears in certain versions of Outlook where:

Outlook will add extra lines to our emails. These lines will inherit the background set on your <body> tag... to make matters worse, this bug seems to happen at random, although it does appear more regularly on Windows 10 machines, compared to Windows 7.

As mentioned in the article above, while it's quite random and there's no reliable fix for it; it can usually be solved with some trial and error of adjusting the font size for the text content above where the line shows up. For example (from the article):

For some folks, the fix is as simple as changing font sizes from odd numbers to even numbers. For example, if you have a font size of 13px or 15px, try converting it to 14px.

For a deeper dive, this Outlook 2016 madness and the weird 1px thin horizontal lines (opens new window) article goes into some more detail about the underlying issue, and this detailed Litmus forum discussion (opens new window) also speculates on possible causes and ways to try troubleshooting it.

# Adding links to normal Figma text layer paragraph/content

If you highlight the text you'd like to link in the Figma text layer, and then click on the native Figma "Link" icon button (opens new window) in the Figma header toolbar area, that will let you paste a URL in, which Emailify will automatically render.

Only use this for content text layers (not buttons or nav links)

Please note that this only works for normal content text layers; if you need to set a link on a button, social icon or navigation link layer that Emailify generates, you'll need to click on that Figma layer, then click the HTML & Mobile Settings button in the Emailify plugin header, then paste your URL into the link field.

# Optimizing the size of the HTML export

The biggest factor in the exported HTML is the number of "Row" components in your design; each time a "Row" is used, it creates a brand new set of <table> elements etc. The best way to optmize the size of your exported HTML is to try to avoid creating a new row if you don't need to.

For example, if you're adding a "heading" text layer, a "subheading" text layer, a "body" text layer and maybe a "button" layer; you can keep all 4 of these content layers inside of a single "Column" that's inside of a single "Row", so there's no need to create 4 seperate "Row" layers for each of these content layers.

# Columns stacking on desktop in Gmail

Some email service providers (like MailChimp) will try to modify your email's HTML before it gets sent out, which can cause some of the columns in your email to stack on Gmail when viewed on desktop, instead of being in a row.

Usually for the purpose of these platforms modifying your HTML is to ensure they're "inlining" styles onto your HTML elements; however, Emailify automatically pre-inlines all of the CSS styles, so that your emails are production ready. If you can find a setting in your email service provider's HTML/import options to "disable" this inlining or modification, this should resolve the issue.

If you're unsure if it's being caused by your email service provider or the code itself, please use a free service like PutsMail (opens new window) (which won't modify any of your HTML) to send yourself an email test. If the test works from PutsMail (opens new window), then your email service provider is modifying your HTML before it's sent out.

# Gmail clipping the email

Gmail clips emails (opens new window) that have a message size larger than 102KB, and hides the full content behind a "View entire message" link. To avoid this, use the Preview button to see the size of your HTML file before exporting, and remove as much content as possible to try and get the file size down.

If the email is still getting clipped, despite being under the HTML file size limit, it's most likely (opens new window) due to a UTF-8 character being used in the email content, which also can trigger Gmail to clip the email. The best solution here is to replace the UTF-8 character with its HTML encoded version (eg. by using &copy instead of ©).

# Buttons with white text turning black in Gmail mobile app in dark mode

Gmail (and other apps) will automatically apply dark mode styles to your email when the user's system theme is set to dark mode, which includes buttons.

To keep white button text white on dark mode in Gmail mobile apps, Emailify will automatically add some extra code to force this if you ensure the button text layer is set to pure white (eg. #fff) in Figma, and also has a dark mode override text color set to pure white (#fff) in the HTML & Mobile Settings panel when your Button component is selected.

# Image uploads being blocked on your network

If you've enabled the Upload Hosted Image URLs feature, or uploaded the HTML email to any email platform using the built-in Emailify export options, the plugin will automatically upload the images online to be hosted automatically.

If you're seeing a warning message in the plugin (Images uploads may be blocked on your current network), this means that the plugin isn't able to access the URL required to upload the images (https://app.hypermatic.com/api/getImageUploadUrl).

This is usually usually due to the network (eg. your company, which may have a firewall blocking certain URLs) or ISP (internet service provider) you're connected to restricting or blocking the URLs; to troubleshoot this:

  • Try tethering your mobile phone as a Wi-Fi hotspot to your machine, then re-run the Emailify Figma plugin again to see if this resolves the issue. If so, it means that your other network was blocking the requests.
  • You can also try using a VPN (opens new window), which should tunnel your network requests and get around any network blocking issues.
  • If you're already using a VPN, try turning that off, then re-run the Emailify Figma plugin again to see if this resolves the issue.

If you're still having issues, please feel free to get in touch (opens new window) via email.

# Converting videos into animated GIFs for your emails

While native <video> tags sadly aren't supported (opens new window) for HTML emails, the best way to add animated images or video content into your HTML email designs is to use GIFs instead; either using a GIF file downloaded from the internet, or one you've created yourself.

If you already have a video you'd like to use as a GIF, you can use a free app called Gifski (opens new window) to help convert short video files into animated GIF files to use in your email designs.

Then there's also a good walkthrough video tutorial (opens new window) that goes through the different ways that you can use GIFs in your Emailify designs and include them in your exports to HTML.

# Colors/gradients in GIFs look a bit grainy

GIFs are a bit different from normal JPG/PNG images, as they can only contain a maximum of 256 colors. If you're using highly detailed images or gradients with lots of color variation, it's expected that it won't look as sharp or have the same color accuracy as the original images used as the source of the GIF due to this limitation of the GIF format.

# Transparency isn't showing in GIFs

The GIF file format supports either 0% opacity or 100% opacity, but nothing in between. This means that you can have an animated GIF with a completely transparent background behind elements that are completely opaque and visible. This means that layers either need to be completely transparent or not; any layers with lower than 50% opacity will be transparent, while any layers with opacity greater than 50% will be opaque.

Flagging transparent GIFs

By default, your GIF exports won't include transparency. If your GIF does require transparency, please add the word transparent anywhere in your Figma layer's name.

# Keeping your original GIF file during export (by maintaining the aspect ratio)

If you drop your GIF into Figma and resize the layer proportionally to maintain the original aspect ratio, Emailify will automatically use the original GIF file in your exports.

Conversely, if you change the aspect ratio of your Figma layer to be different to the original GIF, Emailify will need to re-create your GIF to account for the cropped image area, which can lead to larger GIF file sizes and a slower export times.

# Adding superscript text

While Figma doesn't provide a way for plugins to detect superscript in text layers, the solution for getting it to work with Emailify exports is to manually add in a <sup> tag (eg. <sup>1</sup>) around the content of your text in that Figma text layer, and that will automatically get rendered as superscript in the HTML export from the plugin.

# Limited support for Form elements in emails

The support for <form> elements in HTML emails is still quite low (opens new window), and can cause the emails to be flagged as spam etc if they're included, so it's best to avoid using native forms inside of HTML emails at the moment.

The best workaround is to create a nice looking call to action (CTA) button in your Emailify design, and then link that off to an external form URL like Google Forms (opens new window) or Typeform (opens new window), and collecting the information from recipients there via the browser instead.

# GIF image not showing in Gmail

If you've used GIFs in your design, but aren't seeing them show up when you do a test send to a Gmail inbox, it's likely that the Gmail image caching limit of 20mb (opens new window) is being hit, which causes it to not render.

During export to HTML, Emailify will try to compress any GIFs over 20mb to get them underneath the 20mb file size limit for Gmail, which should resolve this issue in almost all cases (unless the GIF is exceptionally long, large in size, or contains a very high frame rate to begin with).

# Understanding how image blocking works in some clients

Thare a couple of really good articles below describing what image blocking is and which email clients enable it by default (mainly Outlook), whereas other clients like Gmail, Android, Apple/iOS etc all show images by default.

How Image Blocking Works in Email (opens new window)

Email Image Blocking: Answering the What, Why, Where, Who, and How (opens new window)

Unfortunately, it's not related to if the images are secure (SSL) or not, it's always just across the board for any images inside of the email.

The upside is that usually if the recipient is using one of the former email clients, they're fairly used to this happening and clicking the "show images" button, or more likely have already enabled images to show by default for incoming emails.

# Forwarding any HTML email templates breaks them

Unfortunately, if someone decides to forward a custom HTML email that they've received to someone else, this often visually breaks the email after it's forwarded on to somebody else.

The reason for this is that different email clients will modify (or remove) part of the HTML code when the email gets forwarded, causing it to break; as this When Forwarded Emails Break (opens new window) article from Litmus details:

It’s common knowledge that email clients all render email differently. When a subscriber forwards an email, some email clients make changes to the code of the forwarded message. This can include stripping out certain HTML elements, wrapping your email in a blockquote, or inserting additional classes to your code—all of which can break your design and make the email less functional for the recipient of the forwarded email.

# Certain VPNs may be blocked from displaying uploaded images

If you've enabled the Upload Hosted Image URLs feature, or uploaded the HTML email to any email platform using the built-in Emailify export options, there's a very rare edge case where certain IP addresses assigned by some VPNs are blocked by the image host and will prevent the image from loading.

If you're having any issues with images not loading, this is the likely cause (please temporarily turn off your VPN to verify this yourself).

# Dark mode overrides aren't supported everywhere

Currently, support for dark mode styles in email clients (opens new window) is still relatively low; so please be aware of this and try to design your emails with the "progressive enhancement" of these dark mode overrides in mind.

It's also worth using some other clever design techniques (opens new window) for creating your email with dark mode in mind as a fallback with other email clients, too.

# Google Fonts not showing up in some email clients

Currently, support for custom fonts in email clients is still quite varied (opens new window).

Also, certain email service providers (like MailChimp) actively strip them out before the email is even sent to ensure that only web safe fonts are used.

However, Emailify still includes Google Font @imports, and also sets a fallback websafe font (eg. "Arial", "Georgia" or "Courier") if a Google Font is being used for rich text. They'll be visible on any email clients that support the use of @font-face (opens new window) in emails.

Use custom fonts in your images

Please note that if you need to ensure a custom font is visually consistent across all email clients, it may be worth putting your text layers inside of an "Image" frame. This text content will be exported as part of the image itself, and therefore won't be relying on custom web font support to display correctly.

# 1px white line on "reversed order" rows in certain Outlook versions

There's a bug in some versions of Outlook when using the reverse column (opens new window) setting where a 1px white line shows up on the left hand side of the left column. This happens when the row with the "reverse" setting (which uses the dir="ltr" attribute in the HTML) also has padding applied to it. To resolve this, you can set the padding of the "Row" layer in Figma to "0" and add any padding onto the inner columns instead.

# Blank file extensions using Figma desktop app on Windows

There's a known issue with the Figma desktop app (only on Windows), which also happens for normal file exports from Figma. When you go to save your file, you may see an "all files" label. If you ignore this and continue by clicking "Save", it should still save the file with the correct extension and allow you to open it as expected after it has downloaded to your computer. If it still saves the file with a blank extension, you should be able to rename the file to manually append the correct extension to the file name.

# Extra padding around text blocks in editable Klaviyo templates

Due the Klaviyo updating their editor (opens new window), and forcing all templates to use it as of June 6th 2023; unfortunately, if you're exporting HTML emails with the "Editable Content" toggle enabled in Emailify, Klaviyo will automatically apply ~18px of additional padding around each text element by default, as an inline style attribute to a new <td> element that it injects into the HTML if it's an editable template.

Emailify does automatically add some extra CSS to remove this padding for all mobile clients and non-Outlook desktop clients like Gmail etc, however, Outlook will still render the padding unless each of the "Padding" values for any editable text blocks in your template are manually changed to "0" when editing the email for your Campaign in the Klaviyo editor.

While this seems to be rare, if you're having any issues with links to some social networks (eg. Facebook, Instagram) not opening correctly, this is the likely cause (please temporarily turn off your VPN to verify this yourself), and not an issue with the HTML email or the links themselves.

# Button height collapsing on Outlook.com (due to not having a real URL)

If you're seeing the height of a button component collapsing to the size of the text layer inside of it, Outlook.com does this if the href isn't set to a real URL (eg. [replaceLinkInHere] instead of a real URL like https://google.com). Setting a real URL on your button component by clicking on the button layer in Figma, and using the HTML & Mobile Settings button in the plugin, and paste in your URL there.

# Thin white line around image exports

Occassionally some images will contain a faint, thin white line around the edges. Figma does this (opens new window) if a layer isn't positioned on a rounded pixel value (eg. Y: 156.76 or X: 56.3) will automatically result in this sub-pixel line getting included in the export. To resolve the issue, please ensure that your layer positions are all rounded pixel values.

# Pixelated image exports

If you're exporting your email while the image assets in Figma are still progressively loading, they may be exported looking pixelated, as the image wasn't fully loaded in the Figma file before it was exported. To resolve this, please ensure that all of the images have loaded 100% and are looking sharp inside the Figma file before exporting your emails with the Emailify plugin.

To help further with solving this issue, you can use the "Downsizer" feature (opens new window) in TinyImage (opens new window) to shrink down your image fills to match their layer size, which will shrink their file size and ensure they load much faster in your Figma file.

# VPN may be required in China

Please note, if you're in China, the accounts server may be blocked by "The Great Firewall of China". If you're seeing a activation error, despite using a valid key, you will likely need to use a VPN (opens new window) to resolve the issue.

← Emailify Video Tutorials →