Build a Modern, Responsive Email with Inkcite

Published in

Inkceptional

16 min readNov 12, 2015

In this tutorial, I’m going to show you how to build a modern, responsive email using Inkcite, a free, open-source email framework. You will learn about:

Creating a new Inkcite project
Previewing your email in your browser and on a mobile device
Inkcite’s Table, Image, Anchor and Button Helpers
Keeping your email code DRY (don’t repeat yourself)
Using Fluid-Hybrid techniques to make it mobile friendly
Automatic image optimization
Using Google Fonts in your email
Minifying your email’s HTML

Before I begin, if you haven’t installed Inkcite 1.8 (or later), instructions can be found here.

Open a terminal or command prompt, and initialize a new email project:

$ inkcite init tutorial --empty
Created tutorial/images
Created tutorial/config.yml
Created tutorial/source.html
Created tutorial/helpers.tsv
Created tutorial/source.txt

This creates a new subdirectory called tutorial and pre-populates it with Inkcite project files. Normally Inkcite would also include example email markup, but by specifying — empty, I’ve instructed Inkcite to start from scratch — leaving us with a blank canvas to work from. You’ll learn more about these files as you go through this tutorial, but at a high level:

Images in your email go in the images/ directory
Project settings and secrets go in config.yml
The content and markup for your email goes in source.html
Reusable colors, markup and custom tags go in helpers.tsv
The plain-text version of your email goes in source.txt

Preview Server

While we are here, let’s start Inkcite’s preview server by changing directories into the new tutorial directory and running inkcite server:

$ cd tutorial
$ inkcite serverInkcite 1.7.0 is starting up ...
Documentation available at http://inkcite.readme.ioYour email is being served at http://0.0.0.0:4567
Point your mobile device to http://192.168.1.195:4567
Press CTRL-C to exit server mode

Inkcite's server allows you to preview your email in your browser and on your mobile device as you are building it. Open your web browser and enter http://0.0.0.0:4567 in your address bar. As long as you see an empty gray grid, you know that Inkcite is live and ready for you to start adding markup. Also, grab your mobile device and point its browser at the second IP address output by Inkcite. Now, as we're building the email, you can preview the responsive version simultaneously.

The Wrap

Okay, we're ready to start building this email. First, let's add a wrapping container to enforce a consistent background color in all email clients. For this we're going to use Inkcite's Table Helper. Inkcite's Helpers are syntactically similar to their HTML counterparts and produce HTML that is designed to work consistently across all major email clients. To differentiate them from regular HTML, Helper tags are sandwiched between curly brackets rather than greater-than, less-than symbols.

Open source.html in your favorite text editor and add this markup:

{table bgcolor=#fff width=100%}
  {td font-family="sans-serif" align=center}
    Your email content here.
  {/td}
{/table}

Save your work and return to your browser. Inkcite features live reload so the browser (on both your desktop and your mobile device) will automatically refresh after any project file is updated. You should now see something like this:

Note! In my screenshots, the desktop version of the email appears in the left side of the browser window. On the right, I've opened Chrome's Developer Tools' source view to expose the HTML that Inkcite has generated. My screenshots also include the email as it appears on my iPhone 5S.

Notice that Inkcite has already taken care of everything outside of the <body> tag - e.g. setting the doctype, meta tags and kicking things off on the right foot by including the HTML Email Boilerplate reset along with a variety of other fixes and resets to protect against common email client rendering quirks. The markup you added to source.html is preprocessed and injected between the <body> tags.

Let's look at the HTML output from your first {table} Helper - which I have highlighted in the source view of the screenshot:

<table bgcolor=#ffffff border=0 cellpadding=0 cellspacing=0 width=100%><tr>
  <td align=center style="font-family:sans-serif">
    Your email content here.
  </td>
</tr></table>

Inkcite's Helpers transform the attributes you provide into HTML markup and populates its attributes and CSS styles to ensure maximum compatibility in modern email clients.

Inkcite automatically added border, cellpadding and cellspacing attributes and set them to zero
Abbreviated hex colors (e.g. #fff) were automatically expanded to 6-digits (because some clients don’t support shorthand)
The cells of the table were automatically wrapped in a <tr> element
CSS styles are white-space minified

Inkcite Helpers allow you to type less markup, which makes your email source files smaller, cleaner and easier to maintain. Also, you spend less time tracking down obscure HTML and CSS tricks to fix rendering problems in various email clients. This will become more apparent as I build out the rest of this email.

Preheader

Next, let's add a stylized preheader area to our email. Return to your text editor and replace the "Your email content here." with the following code:

{table width=600 padding=10 bgcolor=#cdedf3}
  {td font-size=12 align=center}
    Register now to earn your free nights in the Caribbean!
  {/td}
{/table}

Once again, save your changes and return to your web browser.

Inspect the HTML generated by this second Table Helper and you'll see how Inkcite Helpers are superior to regular HTML.

<table bgcolor=#cdedf3 border=0 cellpadding=10 cellspacing=0 width=600><tr>
  <td align=center style="font-size:12px;padding:10px">
    Register now to earn your free nights in the Caribbean!
  </td>
</tr></table>

One of the new attributes you specified in the preheader markup is padding. For consistent padding in all email clients, Inkcite knows you need to specify it as both a <table> attribute and as a CSS style on each <td>. This is an example of keeping your email source DRY. You specified padding once, but the Helper uses it several times when generating output HTML. Hand-coding a table with padding and multiple columns provides lots of opportunity for error.

Another attribute we specified in the preheader markup was a background color. You'll notice in the HTML output, it appears as a regular HTML table attribute. Whenever possible, Inkcite uses attributes, rather than CSS styles, as they tend to have maximum compatibility across email clients. There are plenty of exceptions to that rule, and in those cases, Inkcite Helpers do their best to automatically deal with those quirks.

Make it Responsive

Inkcite makes it easy to make responsive emails. If you've been previewing your work on your mobile device or if you look carefully at the previous screenshot, you'll see the preheader isn't mobile-friendly yet - it's wider than the available space. To fix that, I'm going to add the the mobile attribute to the preheader markup in source.html:

{table width=600 padding=10 bgcolor=#cdedf3 mobile=fluid}
  {td font-size=12 align=center}
    Register now to earn your free nights in the Caribbean!
  {/td}
{/table}

The mobile attribute is one of Inkcite's most powerful Helper features. Tables, Images and other Helpers support the mobile attribute and put a number of powerful responsive techniques at your disposal. In this case, by specifying fluid, Inkcite will use the Fluid-Hybrid technique to create a table with a maximum width of 600px and which scales naturally on mobile devices.

If you save your work and view the email in both your browser and on your mobile device, you'll see something like this:

Inkcite did a fair bit of heavy-lifting for you - and produced all of the HTML necessary to make this table responsive:

<!--[if mso]>
    <table border=0 cellpadding=0 cellspacing=0 width=600><tr>
        <td>
<![endif]-->
    <table bgcolor=#cdedf3 border=0 cellpadding=10 cellspacing=0 style="max-width:600px" width=100%><tr>
        <td align=center style="font-size:12px;padding:10px">
        Register now to earn your free night in the Caribbean!
    </td>
  </tr></table>
<!--[if mso]>
        </td>
  </tr></table>
<![endif]-->

By setting the mobile attribute to fluid, Inkcite takes care of:

Setting the table’s width to 100% so it scales fluidly
Setting the table’s max-width CSS attribute to enforce a maximum width on modern clients
Wrapping the table in an Outlook-targeted conditional table (required because Outlook doesn’t support the max-width style)

Logo & Primary Navigation

Now, let's add my fictional company's logo and some primary navigation to the header of this email. Switch back to your text editor and add the following HTML immediately beneath the preheader markup.

{table width=600 padding=15}
  {td}
    {a id="logo" href="http://domain.com"}
      {img src=logo.gif height=50 width=247 alt="Lagrange Point Hotels &amp; Resorts"}
    {/a}
  {/td}
  {td font-size=12 color=#ccc align=center}
    {a id="plan" href="http://domain.com/plan/"}PLAN YOUR VACATION{/a} ::
    {a id="rewards" href="http://domain.com/your-account/"}YOUR REWARDS{/a}
  {/td}
{/table}

This new markup makes use of Inkcite's Image and Anchor Helpers. Like the Table Helper, they are designed to be syntactically similar to their HTML counterparts making them easy for you to adopt into your workflow but include powerful benefits beyond traditional HTML <img> and <a> tags. Before I go into detail, save your changes and view your work in the browser.

When you use Inkcite's Image Helper, it looks in the project's images/ folder for the referenced source. If the image is missing, Inkcite inserts a placeholder image instead. This is helpful when you're rapidly prototyping a new design - you can experiment with different image sizes to see how they affect your layout.

Download logo.gif and save it to your project's images/ folder. Now that Inkcite can find logo.gif in your images/ folder it is able to automatically optimize it and save the compressed version inside of images-optim/ which should appear in your project directory. Inkcite encourages you to work in maximum quality and let it optimize and compress your images automatically. Learn more about Inkcite's image optimization features.

Now let's take a closer look at the HTML that Inkcite's {a} Helpers created. Here's the code output for vacation planner link:

<a href="http://domain.com/plan/?email=caribbean-rewards&link=plan" style="color:#0099cc;text-decoration:none" target=_blank>
  PLAN YOUR VACATION
</a>

Inkcite's Anchor Helper disables underlines and sets the display color to the value specified under #link in helpers.tsv (a file we'll explore later in the tutorial). Back in source.html you may have noticed the extra ID attribute. Although it is like a CSS ID in that it uniquely identifies the link, Inkcite uses it in a different way. If automatic link tagging is enabled (as it is in this example) Inkcite will automatically append a customized query string that includes the link's ID. This makes it easy to harvest click-through information from Google Analytics or other log analysis tools if you otherwise have no click-tracking capabilities. Learn more about Inkcite's link tagging features.

The link's ID has additional uses, which will become apparent later in this tutorial.

Make it Responsive

Like I did with the preheader, I'm going to use the mobile attribute to make this area of the email responsive. Because this section includes multiple columns, I'm going to use fluid-drop, which drops (or stacks) adjacent columns vertically on mobile devices. This requires me to specify exact widths on the participating columns like this:

{table width=600 padding=15 mobile="fluid-drop"}
  {td width=247 align=center}
    {a id="logo" href="http://domain.com"}
      {img src=logo.gif height=50 width=247 alt="Lagrange Point Hotels &amp; Resorts"}
    {/a}
  {/td}
  {td width=353 font-size=12 color=#ccc align=center}
    {a id="plan" href="http://domain.com/plan/"}PLAN YOUR VACATION{/a} ::
    {a id="rewards" href="http://domain.com/your-account/"}YOUR REWARDS{/a}
  {/td}
{/table}

Save your changes and review your progress in your browser and on your mobile device.

The HTML required to support fluidly rearranging columns is substantial - involving floating <divs> and multiple nested conditional and non-conditional tables. I'm going to save some space and not post the resulting HTML but you should inspect it. Notice that Inkcite has manipulated the colors, padding, fonts and widths into the correct spots to execute the technique on desktop and mobile devices.

Billboard Image

The next section of this email is a large, eye-catching billboard image. Download it here and save it to your local project's image/ directory (not the new image-optim/ directory). Add the following code to source.html:

{img src=billboard.jpg height=269 bgcolor=#cdedf3 width=600 font-size=40 line-height=269 alt="Free Caribbean Nights"}
<br>

As I mentioned earlier, Inkcite doesn't care if you use regular HTML inside of your project - so I've included a line break for extra space between the image and the next section. As a general rule, if Inkcite provides a Helper, you should use it - but you are more than welcome to mix standard HTML into your project at any time. In this case, there really isn't any way to improve on the line-break tag so there is no need to provide a replacement Helper.

Save your work and return to your browser. Our email is starting to come together now.

Those extra font-related attributes I included on the Image Helper allow you complete control over the style of image's alt-text. This ensures your email looks great when images are disabled (which happens more than any of us would like to admit. Here's what our email looks like with images disabled:

Styling your images' alt-text and background colors are easy ways to ensure your email looks great no matter how it is viewed.

Make it Responsive

Like Tables, the Image Helper supports the mobile attribute. In source.html, set the billboard image's mobile behavior to fluid so it scales nicely on smaller screens.

{img src=billboard.jpg height=269 bgcolor=#cdedf3 width=600 font-size=40 line-height=269 alt="Free Caribbean Nights" mobile=fluid}

Save your work and view your work on both desktop and mobile:

Another feature of Inkcite's Image Helper is its ability to show a different image on mobile devices using the mobile-src attribute. There are two common use cases for replacing images:

Show a higher resolution image on mobile devices
Show an image better composed for a small screen

For the purposes of this tutorial, some of the text in the original billboard image is too small to be legible on a small mobile screen. Download the mobile billboard, which features prominent lettering, and save it to your project's images/ directory. Then update the billboard's markup like this:

{img src=billboard.jpg mobile-src=billboard-mobile.jpg height=269 bgcolor=#cdedf3 width=600 font-size=40 line-height=269 alt="Free Caribbean Nights" mobile=fluid}

Save your work and return to the browser to inspect your work.

Billboard (With alternate version on mobile)

Note! Swappable images are only supported on mobile devices and, on desktops, in Chrome and Safari. It will gracefully fallback to the original billboard image for devices and browsers that do not support swappable images.

Primary Messaging

Next I'll add the primary messaging and a call-to-action to our email. Return to your text editor and append this HTML below the billboard image:

{table width=600 padding=15}
  {td width=180 font-size=32 line-height=32 valign=top}
    EARN YOUR FREE NIGHTS
  {/td}
  {td font-size=15 border-left="2px solid #cdedf3"}    Fuga unde eligendi expedita. Vero non rem in cumque labore nulla
    repellat. Architecto iste ea voluptatem.<br><br>    {a id="register" href="http://domain.com/register-now/"}Register
    by July 31{/a} quia iste libero. Nisi incidunt explicabo aut ut
    id. Sit rem consequuntur sit autem vero velit.<br><br>    Ea fuga officiis facere. Laboriosam aut repellat facilis 
    dolorum sunt quae enim. Accusantium quidem aut eos rerum
    voluptatem quibusdam.<br><br>    {button id="register" bgcolor=#fff color=#5eafbd border="2px
    solid #5eafbd" border-radius=5 padding=8 width=175}REGISTER
    &rarr;{/button}  {/td}
{/table}
<br>

This markup introduces us to the bullet-proof Button Helper. I've customized the look and feel by passing in a number of attributes including its background and text colors, added a border with rounded corners, some padding and set a specific width. Learn more about Inkcite's Button Helper.

The one thing I didn't explicitly set was its href. Remember when I was talking about link IDs have additional functions earlier? I'm taking advantage of one of them here. At the beginning of the second paragraph of text, an {a} is declared with the "register" link ID and its href is assigned. The first time you declare a link ID, Inkcite remembers the URL allowing you to assign it to additional {a} or {button} tags in the same email simply by reusing the ID. It is very common to have the same link multiple times in an email, so not having to repeat the URL over and over keeps your email code DRY and minimizes risk of errors.

Web Fonts

While we're here, let's make use of Google Fonts' Open Sans Condensed to dress up the call-to-action message. Inkcite makes it easy to use web fonts in your email projects. The first thing we need to do is to grab the URL for the 300 weight, provided by Google:

https://fonts.googleapis.com/css?family=Open+Sans+Condensed:300

Next, open the config.yml file in your text editor. We haven't spent much time in this file but there are tons of settings enabling powerful workflow features in this file. Locate the fonts section and uncomment it by removing the leading # character. Add a line like this:

fonts:
 - 'https://fonts.googleapis.com/css?family=Open+Sans+Condensed:300'

Now, per Google's instructions we can simply reference the Open Sans Condensed as a font family anywhere in our email source. For our purposes, adding a font-family declaration in the headline text section is all it takes:

{td width=180 font-family="'Open Sans Condensed', sans-serif" font-size=32 line-height=32 valign=top}
  EARN YOUR FREE NIGHTS
{/td}

Save your work and inspect the email in your browser and mobile device:

Any email client that supports web fonts will show the EARN YOUR FREE NIGHTS messaging in Open Sans Condensed. All other clients gracefully fallback to sans-serif. Learn more about Inkcite's web fonts support.

Make it Responsive

I'll make this section mobile friendly by applying the fluid-drop mobile attribute to the main table. As I discussed earlier, fluid-drop requires explicit widths on each column, and some additional text alignment around the main body text.

{table width=600 padding=15 mobile="fluid-drop"}
  {td width=180 font-size=32 line-height=32 valign=top align=center}
    EARN YOUR FREE NIGHTS
  {/td}
  {td width=420 align=left font-size=15 border-left="2px solid #cdedf3"}
      ...
  {/td}
{/table}

Also, to ensure readability on small screens, I'm going to make the font larger on mobile devices. This is accomplished by specifying a mobile-font-size and mobile-line-height like this:

{table width=600 padding=15 mobile="fluid-drop"}
  {td width=180 font-size=32 line-height=32 mobile-font-size=38 mobile-line-height=38 valign=top align=center}
    EARN YOUR FREE&nbsp;NIGHTS
  {/td}
  {td width=420 align=left font-size=15 mobile-font-size=19 border-left="2px solid #cdedf3"}
      ...
  {/td}
{/table}

Complete these changes and view them in your browser and on your mobile device:

Responsive body content with larger fonts

These changes will ensure that the primary messaging is clean and readable on mobile devices. Compare the desktop version in your browser to the version on your mobile device to see these powerful features in action.

Footer

The last content section we're going to add is the footer. Add this content to source.html:

{table width=600 padding=10 bgcolor=#cdedf3 mobile="fluid"}
  {td font-size=12}
    {a id="plan"}PLAN YOUR VACATION{/a} ::
    {a id="rewards"}YOUR REWARDS{/a}
    <br><br>Perspiciatis adipisci ut. Vel velit ea adipisci. Ut perferendis omnis
    aspernatur temporibus. Consequatur atque quia beatae quia saepe ut.
    Pariatur consequuntur et ut. Qui doloribus odio ut cumque.<br><br>{a id="tos" href="http://domain.com/terms/"}TERMS OF USE{/a} ::
    {a id="privacy" href="http://domain.com/privacy/"}PRIVACY POLICY{/a} ::
    {a id="unsubscribe" href="http://domain.com/your-account/?goto=email_preferences"}UNSUBSCRIBE HERE{/a}
    <br><br>&copy; 2015 Lagrange Point Resorts, Inc.<br><br>
  {/td}
{/table}

As you can see, along with other standard content you'd find in an email footer, I have referenced a pair of previously declared links (plan and rewards) that will automatically share the same hrefs. I've also included attributes to make it responsive. Save these changes and view the finished result in your browser and on your mobile device.

Congratulations! You just built your first modern, responsive email with the Inkcite framework.

Minifying Your Email

With the email's content complete, it's time to build minified HTML. This is accomplished by returning to the terminal or command prompt and running the following command. (You may need to CTRL-C the preview server, or start a new terminal window if you want to leave it running.)

$ inkcite build

When the build command is triggered, Inkcite creates a minified version of your email's HTML and places it, along with the optimized images in a new build/ directory. Minification reduces the amount of extraneous white space, compresses and optimizes the CSS.

Comparing the source.html to the completed build/email.html really illustrates Inkcite's value. Your source markup is clean, easy to maintain and tiny (around 2k) compared to the completed, responsive, cross-client compatible code which weighs in at over 8k.

Note! If this was a real project, you should set your project's sftp and image-host properties in config.yml file. During the build process, Inkcite would automatically inject fully-qualified image URLs, producing HTML that is ready-to-send.

Next Steps

This concludes my tutorial on building a modern, responsive Fluid-Hybrid email. You learned how Inkcite's Helpers allow you to create emails faster by typing less, keeping your code DRY and help protect against common quirks in major email clients. You applied cutting-edge responsive techniques with just a few keystrokes. You also learned about automatic image optimization, web fonts, and how to use Inkcite's live preview server to preview your email live on your desktop and mobile devices.

Now that you are familiar with the Inkcite workflow, there are lots of additional features for you to discover:

The astute email coder will notice that there are still plenty of opportunities to DRY out the code — repeated padding values, font sizes, background colors and more. Additional Helper variables can be used to centralize these values. Custom tags can further reduce the amount of markup in your source files.
Setup your SMTP or Mailgun account information in config.yml to send email previews to custom distribution lists using the inkcite preview command.
Setup your Litmus account information in config.yml to enable instant compatibility tests and automatic analytics tracking code assignment.
Setup the sftp information in config.yml so Inkcite can automatically upload the project’s optimized images to your image host or CDN.
Perform A/B testing and generate multiple versions of an email from a single source file

Consider reviewing the Inkcite documentation to discover all of its features.

Thanks for following along!

Build a Modern, Responsive Email with Inkcite

Preview Server

The Wrap

Preheader

Logo & Primary Navigation

Billboard Image

Primary Messaging

Web Fonts

Complete these changes and view them in your browser and on your mobile device:

Footer

Minifying Your Email

Next Steps

Written by Jeffrey D. Hoffman