Skip to main content

HTML technical guidelines

Specifications for a successful email​

If you want to create a newsletter or an email campaign directly in HTML, it is useful to know the specifications that are required to ensure content displays correctly on most mail clients and services (Outlook, Gmail, and similar) and devices.

These specifications are based on the many years of experience that Contactlab staff have gained, together with the countless number of deliveries our clients have sent.

Objective​

Here, you can learn high-quality HTML technical specifications that can be used with the Contactlab Marketing Cloud Send module.

General rule​

An email’s HTML code must be more ‘simple and clean’ than that of a website page. Webmail services and mail clients have difficulty managing certain elements, such as style sheets, JavaScript and similar, when compared with a browser.

The following specifications also highlight the items that should NOT be included in a message, to help avoid recipient visualization problems.

What is important for you to know​

The following sections describe the main technical requirements for creating HTML emails that display correctly across different email clients and devices.
They cover the recommended structure, HTML elements, styles, images, links, message size, and elements to avoid.

Content layout​

All message content must be inserted into a fixed-width table, specifying the width in the width attribute of the <table> tag. For each cell, you must specify the width (e.g., <td width="121">).

While the table described in Contents layout must have a fixed width, there is no real maximum size. However, it is better not to exceed 600 – 650px, to avoid tedious horizontal scrolls for the recipient.

There is no recommended length. However, for newsletters or marketing emails to be effective, you need to ensure that messages are not too long. As much content detail as practically possible should be included in web pages, with the appropriate links contained in the message.

Doctype​

To ensure that the HTML of the newsletter is correctly interpreted, use the following doctype:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<title> tag in the <head>​

Insert text in the <title> tag. Avoid leaving the default text assigned by the HTML editor (e.g., "Untitled1" or "New Page 1"). It’s better if it matches the subject of the email.

Bugfix in the head​

To ensure correct display and avoid text resizing on mobile devices or Outlook due to zoom, include the following code in the head tag:

<!–[if gte mso 9]>
<xml>
<o:OfficeDocumentSettings>
<o:AllowPNG/>
<o:PixelsPerInch>96</o:PixelsPerInch>
</o:OfficeDocumentSettings>
</xml>
<![endif]–>
<style type="text/css">@-ms-viewport\{width:device-width}\</style>
<style type="text/css">
html { -webkit-text-size-adjust:none;}
body, .ReadMsgBody, .ExternalClass, .multi-col .column {width: 100%; width:100% !important; margin: 0px !important; padding: 0px; display: block; -ms-overflow-style: none !important;}
.ExternalClass {line-height: 100%;}
table, tr, td {margin:0; padding: 0; border-collapse: collapse !important; mso-line-height-alt:0px; mso-margin-top-alt:0px; mso-table-lspace:0px; mso-table-rspace:0px; vertical-align: top; border-spacing: 0; }
td { font-size:0px; line-height: 0px; }
a img, img{margin: 0px; padding: 0px; display: block;}
</style>

Meta tags​

To ensure characters display correctly, including those in any online version, and to add information to any social shares on Facebook, include the following meta in the <head> tag:

<meta http-equiv="content-type" content="text/html; charset=UTF-8″>
<meta property="og:title" content="TITOLO" />
<meta property="og:description" content="DESCRIZIONE" />
<meta property="og:image" content="URL IMMAGINE" />

Stylesheets use​

Style sheets (CSS) should be used sparingly, as follows:

  • Do not use CSS to determine the position of an element (for example, the alignment of an image or a table, padding, float and similar).
  • In the message HTML, insert the CSS:
    • Internally (in the <head> tag).
    • Online (insert the CSS in the cells, within a link and a <div> tag – where the class is called).

CSS attributes commonly used in newsletters:​

  • Background-color (BACKGROUND COLOR): Hexadecimal color code, for example, # Ff0000.
  • Background-image: URL (‘IMAGE PATH’): background image.
  • Color (TEXT COLOR): Hexadecimal color code, for example, # Ff0000.
  • Text-align (HORIZONTAL TEXT ALIGNMENT): left, right, justify, center.
  • Text-decoration (UNDERLINED or NO): underline, none.
  • Font-family (FONT TYPE): Font name or “family” name [WEB SAFE].
  • Font-size (FONT SIZE): Expressed in pixels.
  • Line-height (INTERLINEA): Expressed in pixels.
  • Width (WIDTH): In pixels or %.
  • Height (HEIGHT): Expressed in pixels or %.
  • Vertical-align (VERTICAL ALIGNMENT): top, bottom, middle.
warning

The 2 style sheets must have the same characteristics.

Body​

Insert the following style in the <body> tag, to ensure that the message centering is not affected by the default client settings:

<body style="margin: 0; paddinge: 0px;">

Structure tags​

  • <table> Indicates the beginning of the table.
  • <tr> Indicates the beginning of a line.
  • <td> Indicates the beginning of a cell.
  • </td> Indicates the end of a cell.
  • </tr> Indicates the end of a line.
  • </table> Indicates the end of the table.

Usable newsletter attributes​

  • Dir (DIRECTION OF WRITING): rtl, ltr.
  • Cellpadding (CELL INNER SPACE): Expressed in pixels.
  • Cellspacing (SPACE BETWEEN THE CELLS): Expressed in pixels.
  • Border (DIMENSION EDGE OF TABLE): Expressed in pixels.
  • Align (ORIGINAL ALIGNMENT): left, right, center, justify.
  • Valign (VERTICAL ALIGNMENT): top, middle, bottom, baseline.
  • Bgcolor (BACKGROUND COLOR): Hexadecimal color code, for example, # ff0000 (or RGB, or color name).
  • Background (BACKGROUND IMAGE): Image link.
  • Width: Expressed in pixels or %.
  • Height (HEIGHT): Expressed in pixels or %.
  • Colspan (NUMBER OF CELLS GROUPED IN A COLUMN): Number that identifies the sum of the grouped columns.
  • Rowspan (NUMBER OF CELLS GROUPED IN ONE LINE): Number that identifies the sum of the grouped rows.

Tag attributes​

  • <body> class, dir, id, lang, style, title, bgcolor, background.
  • <table> align, bgcolor, background, border, cellpadding, cellspacing, width, height, class, dir, id,lang, style, title.
  • <tr> No attributes.
  • <td> align, bgcolor, background, colspan, width, height, class, dir, id, lang, nowrap, rowspan, valign style, title.

Font​

  • The fonts used in the newsletters must be web-safe to ensure they are displayed consistently across various operating systems. A list of safe fonts can be found here.
  • Font size should be defined in absolute pixel value.
  • To prevent mobile devices from modifying the font size, include the following in the internal CSS: -webkit-text-size-adjust: none;
  • Always use a font size greater than 9px and less than 23px. Exceeding this limit may increase the spam score.
  • Always declare line-height to be at least 4px greater than the font size.
  • The recommended size for readability on mobile devices is greater than 14px.

Preheader​

The preheader, also called an Eyebrow, is the first line of text in an email and allows recipients to immediately see the main content at a glance. It is visible even before opening the email in Gmail, Outlook, and most mobile devices. An invisible preheader that only appears in the inbox preview can be added using the following code:

<div class="preheader" style="display:none !important; visibility:hidden; opacity:0; color:transparent; height:0; width:0; color:#ffffff; font-size:1px; line-height:0; overflow:hidden; mso-hide:all;">TEXT</div>

And the following CSS class:

.preheader {
    display:none !important; 
    visibility:hidden; 
    opacity:0; 
    color:transparent; 
    height:0; 
    width:0; 
    color:#ffffff; 
    font-size:1px; 
    line-height:0; 
    overflow:hidden; 
    mso-hide:all;
}

<br> instead of <p>​

Use the <br> tag to break lines and avoid using the <p> tag, as it creates a paragraph. Each webmail/client applies different top and bottom margins, altering its appearance.

Images​

Images, if not already embedded, must be uploaded to a server (Send's server or another), and the absolute path must be inserted in the src attribute of the tag. The format should be jpg, gif (including animated), or png. It is highly discouraged to use mapped images. Each image should be as lightweight as possible to avoid impacting download time.

Background Images​

If the HTML contains background images, avoid writing the text in white or any color matching the <body> background. This is because users with image blocking enabled on their email client will not see the message until the images are downloaded. Background images cannot be added via the stylesheet; they must be inserted directly within the cell.
However, if possible, avoid using background images, as they may increase the chances of display issues.

For example

<td background="http://domain.it/images/bg_main.jpg" bgcolor="#dadada" align="center" style="padding: 0px; vertical-align:top; width:600px; height: 300px;" width="600" height="300">
    <!--[if gte mso 9]>
    <v:rect xmlns:v="urn:schemas-microsoft-com:vml" fill="true" stroke="false" style="width:600px;height:300px;">
    <v:fill type="tile" src="http://domain.it/images/bg_main.jpg"/>
    <v:textbox inset="0,0,0,0">
    <![endif]-->
    #CONTENT
    <!--[if gte mso 9]>
    </v:textbox>
    </v:rect>
    <![endif]-->
</td>

Text-Image balance​

It's better to avoid using only images in HTML, as this greatly increases the likelihood of the message ending up in the spam folder. It also helps prevent emails from appearing empty, since most webmail applications automatically block the download and display of images. Therefore, it's recommended to use text instead of images. The suggested composition of an email is 60% text and 40% images. Large images should be split into two or more parts and then assembled using a table.

Image naming​

Assign each image a name that reflects what it represents. Avoid generic names like: 001.gif, 002.gif, or photo1.jpg, photo2.jpg, etc. This helps reduce the risk of the message being marked as spam. Avoid using spaces or accented letters in image names. It’s acceptable to use characters like underscores (e.g., vacation_photo.jpg).

Characters​

Be cautious of characters from Word (e.g., quotation marks, ellipses, dashes, and apostrophes). Replace them with the corresponding symbols typed from the keyboard.

Link text​

Do not use the URL of the link as the link text. For example, avoid links like: <a href="https://www.contactlab.com/">www.contactlab.com</a>. Some widely used email programs run anti-phishing checks that might flag such links as suspicious. It’s better to replace them with text, like: <a href="https://www.contactlab.com">Contactlab</a>.

It is also recommended to:

  • Insert, at the beginning of the text, an option to view the content on the web: a link that leads to a fixed page on the server or the code ${online_version_url}$, to give all users the opportunity to view the communication correctly.
  • Add, at the bottom of the communication, a reference to the Data Protection Code regarding privacy.
  • Include, at the bottom of the communication, a link allowing all recipients to unsubscribe from the newsletter.

The maximum recommended size for the HTML is 60 KB. It is good practice to avoid exceeding 100 KB, to make sure the message is not cropped.

Elements to avoid:​

  • Mapped images: Do not insert images containing a map. Instead, split the image and reassemble it using a table, linking the individual pieces.
  • Javascript: Do not insert javascript in the message's HTML.
  • Flash: Do not insert flash files (.swf) in the HTML. If it’s necessary to include moving elements, use animated gifs.