Overview
Patterns and guidelines for creating and sending emails to Stack Overflow users & customers.
Introduction
Emails are a great opportunity to showcase the brand’s personality to loyal users or perspective customers who may otherwise only interact with the product itself.
From transactional updates to editorial moments, every email is a chance to strengthen familiarity with the brand and build a more connected experience.
These guidelines are designed to provide a foundation for what those emails can be, while leaving room to evolve and expand over time.
Creating emails
Our documentation is built from components built with MJML – an open-source email framework that abstracts away the need to manually code email HTML. Read the full documentation.
Templates
We have a range of email templates, each serving a distinct purpose while demonstrating how communication can scale from functional to expressive.
Transactional
A transactional email is functional. It is triggered by an event and usually is a short single message and call to action.
Newsletter
A newsletter is a recurring pieces of comms that may contain various items and call to actions.
Promotional
Typically single-message communications - short, punchy, and to the point — designed to quickly capture attention and drive engagement.
Components
Each email is built from reusable component blocks. The set below is the canonical starting library.
Usage
Warning: This functionality is experimental and may change.
If you are running the @stackoverflow/stacks-email package, you can compose and render email markup by POSTing a JSON block list to the compile API.
POST /api/compile
Paramaters
template: currently supports"transactional".target: one of"preview","dotnet", or"braze".blocks: ordered array of block definitions.previewText: optional template preheader/inbox snippet text.
Example request:
{
"template": "transactional",
"target": "preview",
"previewText": "Reset your password in one click.",
"blocks": [
{
"type": "headline",
"variant": "highlight",
"props": {
"textContent": "Reset your password",
"textHighlight": true
}
},
{
"type": "text",
"variant": "body",
"props": {
"textContent": "Hi [[FIRST_NAME]], click below to continue."
}
},
{
"type": "button",
"variant": "primary",
"props": {
"href": "[[CTA_URL]]",
"text": "Reset password"
}
}
]
}Response
Successful responses include compiled html, final mjml, renderedMjml, compile errors, and metadata such as template, target, and blockCount.
Target clients
Litmus publishes a regularly updated list of email clients and their observed market share, you can use this as a rough guideline when testing and making decisons about compatability.
| Client | Share (%) |
|---|---|
| Apple | 45.51 |
| Gmail | 23.54 |
| Outlook | 5.67 |
| Yahoo Mail | 2.06 |
| Google Android | 1.34 |
| Outlook.com | 0.40 |
| Thunderbird | 0.17 |
| Orange.fr | 0.08 |
| Bell Email | 0.02 |
| Samsung Mail | 0.02 |
Other resources
Email gallery
Our own gallery of email designs. These templates are used to build the examples in this section lives along side the email components so feel free to add your templates back in to serve as inspiration for others.
Can I email?
On occasion you may need to hard code some elements of email, if straying from the components here or implementing something ourside of the scope of MJML. ‘Can I email’ is a great resource for dealing with the eccentricities of email development.
Really Good Emails
A constantly evolving gallery of email designs from across the web. Espeically useful for designers or product managers planning out a new email.