Working with emails

Sign up forms in iframes

The email sign up forms include the Guardian Today footer, and the iframe embeds used by editorial in Composer. They are also used in the email sign up interactive atoms, examples here and here.

They live in routes like this: www.theguardian.com/email/form/<type>/<listID>

The form type can be article, footer, plain, plaintone, or plaindark:

• article >> Commonly used as embed in articles (example here). Button defaults to blue but tone overrides can be applied.
• footer >> This is the one used in the footer on every page.
• thrasher >> This is the one used within thrasher atoms. They don't include privacy wording or explanatory content as this should be included as part of the thrasher design.
• plain >> No header or description. Button will always be guardian-brand blue
• plaintone >> No header or description. Submit button splits from input on widescreen. Button defaults to blue but tone overrides can be applied. Used in email interactives.
• plaindark Used by Documentaries. Deprecated in favour of plaintone (which has a dark option) and potentially removable, however, only if all usages can be found.

The listID is the primary key of the email in ExactTarget. Editorial should know the listID. Any tone applied to the form will be determined by the listID (see later section).

When the form is submitted, the email address will be passed through Identity to ExactTarget, along with the ListID.

N.B. For email sign ups to work, the listID must be set up in ExactTarget by Editorial

The email preferences centre and the newsletters page

The email preferences centre and the email newsletters page both pull data from EmailSubscriptions.scala

The email newsletters page does not use iframed forms

Adding, removing or otherwise altering the emails listed

When adding a new EmailSubscription:

• theme >> Section of the email preferences page that this email will appear in
• teaser >> Short (~120 char) description used on the newsletters page
• description >> Longer description used on the email preferences page
• frequency >> Text that appears next to the clock icon
• subheading >> Currently used for the region specific emails (UK, AUS, US)
• tone >> Determines the tone colours of the card on the newsletters page

Adding colour and tones to the email sign up forms

1. In the EmailSignupController.scala add an email name to ListIds, and assign it the value of the listID.

2. Within emailSignUp.scala.html map the email name to a tone in listIdTones

Email sign up atoms

These interactives have their own repo and readme.

Writing a new email sign up form

If you are adding a custom email sign up form somewhere, you will want to POST an email address and listID to https://www.theguardian.com/email.

An example implementation of this can be found in newsletters.scala.html.

How to do email address validation

1. Don't use regular expressions to validate email addresses:

• http://nullprogram.com/blog/2008/12/24/
• https://davidcel.is/posts/stop-validating-email-addresses-with-regex/
• http://www.ex-parrot.com/~pdw/Mail-RFC822-Address.html

2. If you want to provide some helpful feedback to the user, just check the address has at least one @

function validate(form) {
  var emailAddress = $('.' + classes.textInput, form).val();
  return typeof emailAddress === 'string' &&
  emailAddress.indexOf('@') > -1;
}

3. Let the browser support validation efforts; some browsers support type="email" on inputs:

• https://davidwalsh.name/html5-email

4. If all else fails, ExactTarget has checks in place for valid emails and also cleans the lists.

Email rendering

Fronts and articles can be rendered in email-friendly HTML by appending the URL parameter format=email. The response from these endpoints can be put into an email body and will render well in a wide variety of email clients.

For curating emails, you'll normally want to set up a custom front rather than co-opting an existing front. For this purpose, we have a notion of "Email fronts" (in addition to Commercial, Editorial, and Training). Content can be placed into email fronts in the same way as for web fronts, via the fronts tool.

As for web fronts, other properties of email fronts can be configured via the fronts config tool. This includes creating containers and choosing their layout types.

There are some differences between web fronts and email fronts.

• Email fronts always render in email-friendly format, regardless of the format parameter
• Email fronts have a much smaller set of layout types than web fronts:
  • Fast is for news-like content which is expected to be scanned quickly. Cards are smaller, containing just the headline.
  • Slow is for more long-form/feature/opinion content which might be consumed more slowly. Cards are larger, containing headline and standfirst.
  • Medium is somewhere in between

The use cases given (news-like vs feature-like) are just suggestions. In reality you can use whatever layout looks best for your design of email. For instance, longer emails will typically contain more containers with the fast layout since the email would take too long to scan from top to bottom otherwise.

Here's an example of each layout type along with a table summarising their differences:

Slow

Medium

Fast

Table summarising differences between slow/medium/fast

LAYOUT | CARD   | IMAGE?   | STANDFIRST? | HEADLINE?
----------------|-----------------------------------
slow   | 1st    | big      | yes         | big
       | others | none     | yes         | small
----------------|-----------------------------------
medium | 1st    | big      | yes         | big
       | others | none     | no          | small
----------------|-----------------------------------
fast   | 1st    | small    | no          | small
       | others | none     | no          | small

Writing CSS for email

Only a very limited subset of CSS will work in certain email clients. See here for a guide: https://www.campaignmonitor.com/css

Some key points:

• Use <tr> for new rows rather than <div>, <p>, or anything else you might use if you've written HTML in the last decade
• For spacing, use only padding on <td> elements. Margins don't work properly in Outlook.
• For positioning items horizontally next to one another, wrap in <td> with percentage width
• Do not wrap block-level elements in <a> elements as this will break in Outlook (see https://github.com/guardian/frontend/pull/15634).