{"id":19050528,"url":"https://github.com/blakek/how-to-write-html-emails","last_synced_at":"2026-02-08T19:02:52.716Z","repository":{"id":77618494,"uuid":"50465324","full_name":"blakek/how-to-write-html-emails","owner":"blakek","description":"A guide helping everyone get what is needed from the client, designer, and developer when making an HTML email.","archived":false,"fork":false,"pushed_at":"2016-02-15T20:48:59.000Z","size":65,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-28T05:09:45.964Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blakek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-26T22:55:35.000Z","updated_at":"2022-03-03T13:37:53.000Z","dependencies_parsed_at":"2023-05-02T14:31:15.501Z","dependency_job_id":null,"html_url":"https://github.com/blakek/how-to-write-html-emails","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/blakek/how-to-write-html-emails","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fhow-to-write-html-emails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fhow-to-write-html-emails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fhow-to-write-html-emails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fhow-to-write-html-emails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blakek","download_url":"https://codeload.github.com/blakek/how-to-write-html-emails/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fhow-to-write-html-emails/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29240138,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T18:06:38.086Z","status":"ssl_error","status_checked_at":"2026-02-08T18:06:09.124Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T23:15:13.720Z","updated_at":"2026-02-08T19:02:52.158Z","avatar_url":"https://github.com/blakek.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Email Template Overview\n\u003e A guide helping everyone get what is needed from the client, designer, and developer when making an HTML email.\n\nEmails are one of the most [over-]used forms of communication, and the technology and standards that make them work is archaic. Creating a good email is _nothing_ like making a good web page. This guide is aimed at helping everyone involved in creating emails get the best results possible with the fewest number of surprises possible. This guide is a non-exhaustive list of necessary information from the client, realistic expectations from HTML emails, best practices in designing emails, and unanticipated gotchas for developers.\n\n\n#### Contents:\n\n* [Information for Account Managers and Project Managers](#information-for-account-managers-and-project-managers)\n  - [Required Information Before Design and Dev Can Begin](#required-information-before-design-and-dev-can-begin)\n  - [Optional Information and Extra Tricks](#optional-information-and-extra-tricks)\n  - [Email systems we commonly use](#email-systems-we-commonly-use)\n* [Design Best Practices](#design-best-practices)\n* [Development Tips and Best Practices](#development-tips-and-best-practices)\n  - [General tips, tricks, and gotchas](#general-tips-tricks-and-gotchas)\n  - [Responsive Emails and Issues for Mobile Clients](#responsive-emails-and-issues-for-mobile-clients)\n* [Stuff to Add](#stuff-to-add)\n\n\n## Information for Account Managers and Project Managers\n\n### Required Information Before Design and Dev Can Begin\n\n* What is the subject of the email? Please provide this explicitly with the body text.\n* There will be links in the email. Please provide where the links are expected to go (i.e. the complete URL) along with the copy text.\n* Who is will need to review the email before it is sent? Please provide the names and email addresses of everyone that will be involved.\n* Is this an email template or a one-off email? These are developed differently, so please let the developer know.\n* Who will be sending the email? Our firm, or another?\n  - If __another firm__ is sending:\n    * Who will be hosting the images for the email? If we are, we will need to know - otherwise, no images in the email will show.\n    * Who will add the unsubscribe links?\n    * What service is the other firm using to send the email? This is not always required, but it **is** required if we are to add an unsubscribe link or if we are delivering a reusable template (as opposed to a one-off email).\n\n\n### Optional Information and Extra Tricks\n\nIt is possible to have text that is shown in the email list preview area, but is hidden in the email itself. The text in the preview area could be a way of generating interest (and email opens) from the end users. It can also get a key idea across in a content-heavy email. If this is desired, please let the dev team know. Remember, this needs to be very short!\n\n#### Example\n![example of text only in preview area](./images/hidden-preview-text.png)\n\nWill the email include any links to social accounts? If so, please let design and dev know:\n\n* what social accounts are going to be used\n* a list of links (i.e. the full URL) to the social accounts\n\n\n### Email systems we commonly use:\n* [Campain Monitor](https://www.campaignmonitor.com/)\n* [MailChimp](http://mailchimp.com/)\n* [Emma](https://myemma.com/login)\n\n\n\n## Design Best Practices\n\nWhat is the purpose of the email? Is it to get users to read the content, to buy something, or to join an event and/or subscription? [MailChimp][mc-layout-and-purpose] does a great job of describing the differences, but the takeaway is there are three main types of emails that should be designed with different purposes in mind:\n\n* __Read Me__ emails encourage readers to learn more using the content within the mail. These need:\n  - well written copy\n  - fewer images\n  - good/readable typography\n  - an attention-grabbing \"hook\" in the leading sentences of the email\n* __Buy Me__ emails try to encourage an action based on a product. These need:\n  - interesting, focused, well-cropped images (e.g. product photos)\n  - simple copy\n  - easy-to-find links to product pages\n  - an attention-grabbing \"hook\" - usually before each product\n* __Join Me__ emails try to encourage another type of action - often to attend an event. These need:\n  - very short, clear copy\n  - specific details, e.g. an event date and location, should __always__ be prominently placed at the top of the message\n  - the call-to-action should be easy to understand and easy to see\n\n[According to][cm-max-width-2] [very reputable][cm-max-width] [email creators][mc-basics], emails should be **no more than 600-650 px wide**. While everyone at an agency may have a huge, high-pixel-density monitor, a vast majority of email users use a preview pane to read email, which is commonly only ~750-800px wide.\n\nTypography should be limited to [standard system typefaces][mc-typography]. On a website, we can import fonts from e.g. Google, but, sadly, popular email clients such as Gmail, Outlook, and Yahoo! Mail **do not support web fonts** at all. If the client really wants a particular typeface used, an image of the text _can_ be used, but [several email clients][cm-image-blocking] block images by default. It's generally not a good idea to use images to show any key information.\n\n\u003e **NOTE:** remember that anyone with Microsoft Office installed will have the base font set supplied with Office.  While this is nice to take advantage of, it is still _highly_ recommended to test the design with a standard system font as a fallback.\n\nAs mentioned in the previous point about typography, images are [blocked by default][cm-image-blocking] on several, popular email clients. **It's generally not a good idea to use images to show any key information.**\n\nWhile your list of fonts is limited, email clients have good support for things such as the line-height (vertial character spacing), letter-spacing (e.g. tracking, e.g. horizontal character spacing), word-spacing, etc.\n\nEmail client support for margins and general positioning is very poor. Where this has the biggest effect is text and images cannot overlap without putting copy inside \"sliced\" images.\n\n#### Expected result (Apple Mail)\n![correctly displayed margins](./images/negative-margin-apple-mail.jpg)\n\n#### Most email clients (Gmail)\n![incorrectly displayed margins](./images/negative-margin-gmail.jpg)\n\n#### Links\nThere will be links to web pages in emails. Please explicitly tell the dev team what is expected to be a link.\n\nKeep in mind that using a plain image as a link is not intuitive. Instead, use buttons as the primary calls to action that demands attention, and use links for everything else. Try to restrict using buttons to a couple key links and use links for everything else. If images must be used, please make sure they indicate to the user in some way they can be clicked on (e.g. using text in the image that says \"view now \u0026raquo;\" tends to be better)\n\nAlso, keep in mind that, unlike a web page, there is almost no control over what looks \"clickable\" by using hover states. That means that there is no way of making a link darker/lighter when a user hovers over it, and there is little control over what the cursor looks like when hovering over a link.\n\nA link to allow users to unsubscribe is **required** for all emails. Usually, this is an entire area below the footer. Please keep this section in mind during design. Other optional links that may also be in the unsubscribe area of the email include:\n\n* \"Edit your subscription\" or \"Email preferences\" link\n* A link to see the web version of the email\n* Perhaps social links - they usually end up around this area\n\n\n\n## Development Tips and Best Practices\n\nWhat developers need to be aware of greatly overlaps what designers should be aware of. It is recommend you read over the [design best practices](#design-best-practices) section. As a brief recap:\n\n* Emails should be **600-650px wide** due to the size of preview panes.\n* Web fonts **cannot** be used due to the [low support from email clients][mc-typography]. Desktop Outlook even defaults to Times New Roman when it sees a web font reference. Use [standard system fonts][mc-typography].\n* It's generally not a good idea to use images to show any key information because [several email clients][cm-image-blocking] block images by default.\n\nIn addition to the look and feel, differences and bugs in email clients are far worse and prolific than those found in web browsers. The following list is by no means comprehensive, and at best scratches the surface of what you should be aware of.\n\n\u003e **Please keep in mind**: Apple's email clients have by far the best support for almost everything you would normally use when making a webpage. That means testing your results on an iPhone on in Mail isn't the best idea because they will show you what you'd expect to see. Test in Gmail, and, if available, Outlook. If you have a Litmus subscription or something similar, that is by far the best way to test.\n\n\n\n\n### General tips, tricks, and gotchas\n\n**Several** CSS selectors and features are simply not supported on various email clients (e.g. even the element selector - such as `body { }` - is not supported in Outlook.com, Yahoo!, Gmail, or AOL).  In some cases (e.g. Outlook.com), support is getting WORSE (e.g. Outlook.com has recently dropped support for CSS margins and floats).\n\nYou can have hidden text that gets shown in the email list preview area, but isn't shown in the email itself.\n\nSupposedly, margins are supported in Gmail, but I have never gotten it them work correctly -  especially negative margins.\n\nAlmost all styles should be inlined as several, very popular email clients do not read styles in a style tag. There are several tools for helping you do this, so use whatever works best for you. The exception to this rule would be styles in media queries.\n\nIt is possible to have text that is shown in the email list preview area, but is hidden in the email itself. The text in the preview area could be a way of generating interest (and email opens) from the end users. It can also get a key idea across in a content-heavy email. If this is desired, please let the dev team know. Remember, this needs to be very short!\n\n#### Example\n![example of text only in preview area](./images/hidden-preview-text.png)\n\n\n\n### Responsive Emails and Issues for Mobile Clients\n\n\u003e Responsive emails are _possible_, but they require more planning. No popular desktop mail app supports media queries (except Apple Mail), but media queries tend to work well on native mobile email clients. The Gmail and Yahoo! Mail apps do NOT support media queries, but all Apple Mail clients, Android 2.2+ clients, and BlackBerry OS 6+ clients support media queries. Funnily enough, the Windows Phone 7.5 email client was the first Microsoft email client to support media queries, but support was dropped again in Windows Phone 8.\n\nThe minimum font size on some devices is 13px, but [you can override this][cm-min-font].\n\nThe contents of the `\u003ctitle\u003e` tag is important, as it shows in some client notifications (e.g. Android 4.4).\n\nMedia query styles should not be inlined (how would you do that, anyway??). There is no such thing as \"mobile-first\" in email development, so make everything work on desktop first, and then add extra styles for mobile devices that support it.\n\n\n\n## Stuff to Add\n\n  * you can optionally show content if you are in Outlook:\n\n  ```html\n  \u003c!--[if mso]\u003e shown only in Outlook \u003c![endif]--\u003e\n  \u003c!--[if !mso]\u003e don't show in Outlook \u003c![endif]--\u003e\n  ```\n\n  * design and dev: prefer html buttons over images\n\n[dev-cerberus-home]: http://tedgoas.github.io/Cerberus\n[dev-cerberus-github]: https://github.com/TedGoas/Cerberus\n[mc-basics]: http://templates.mailchimp.com/getting-started/html-email-basics/ \"MailChimp Designer/Developer Reference\"\n[mc-typography]: http://templates.mailchimp.com/design/typography/ \"MailChimp Typography Reference\"\n[mc-layout-and-purpose]: http://templates.mailchimp.com/design/layout-and-purpose/ \"MailChimp Layout and Purpose\"\n[cm-min-font]: http://www.campaignmonitor.com/blog/how-to/2010/12/save-your-layout-by-overriding-the-minimum-font-size-on-the-iphone-and/\n[cm-css]: https://www.campaignmonitor.com/css/\n[cm-image-blocking]: https://www.campaignmonitor.com/dev-resources/will-it-work/image-blocking/\n[cm-max-width]: https://www.campaignmonitor.com/blog/email-marketing/2005/04/maximum-width-for-html-emails/\n[cm-max-width-2]: https://www.campaignmonitor.com/blog/email-marketing/2011/06/how-wide-are-html-email-designs-today/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblakek%2Fhow-to-write-html-emails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblakek%2Fhow-to-write-html-emails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblakek%2Fhow-to-write-html-emails/lists"}