# Weekly digest
A weekly digest email template with a headline number, a short list, a one-click unsubscribe, and List-Unsubscribe headers. Table-based HTML, a text alternative, and code in TypeScript, Python, and curl.
A digest is the one email in this set that the reader did not ask for individually, so it carries the obligations that come with that: a visible unsubscribe, the List-Unsubscribe headers, and a headline worth the interruption.
The structure that survives is a number at the top and three items under it. A digest that lists everything gets skimmed to nothing, and a digest with no number at the top gets opened for the first month and then filtered.
Topics: weekly digest, summary email, unsubscribe, list-unsubscribe.
## When it sends
On a schedule, to people who are opted in and have something to show. An empty week is a week you skip, not a week you send an empty digest.
## What you need
- **An emails.sh API key**: Created in the dashboard, starting with esh_. It stays on your server.
- **A sending domain**: Verified with three DNS records, or send from onboarding@emails.sh until yours is ready.
- **An opt-in you can prove**: When and how each recipient agreed. This is the email somebody will complain about.
- **A working unsubscribe**: One click, no login, effective on the next run. Both in the body and in the headers.
## Subject
```text
Your week on {{PRODUCT_NAME}}: {{HEADLINE_STAT}}
```
## HTML body
```html
Your weekly digest
```
## Plain text body
```text
{{HEADLINE_STAT}}
{{PRODUCT_NAME}}, {{WEEK_RANGE}}
{{FIRST_NAME}}, here is what moved this week.
{{ITEM_ONE_TITLE}}
{{ITEM_ONE_DETAIL}}
{{ITEM_TWO_TITLE}}
{{ITEM_TWO_DETAIL}}
See the full week:
{{DIGEST_URL}}
You are getting this weekly digest because you turned it on in
{{PRODUCT_NAME}}. Unsubscribe, one click and no sign-in:
{{UNSUBSCRIBE_URL}}
```
## Placeholders
| Placeholder | What it is | Example |
| --- | --- | --- |
| {{PRODUCT_NAME}} | Your product, as the reader knows it. | Acme |
| {{FIRST_NAME}} | What to call them. | Ada |
| {{WEEK_RANGE}} | The week covered. | 24 to 31 July |
| {{HEADLINE_STAT}} | The one number worth the interruption. | 48 deploys, 2 rollbacks |
| {{ITEM_ONE_TITLE}} | First item. | Checkout latency down 18% |
| {{ITEM_ONE_DETAIL}} | One line about it. | The p95 moved from 840ms to 690ms after the cache change on Tuesday. |
| {{ITEM_TWO_TITLE}} | Second item. | 3 failed jobs need a look |
| {{ITEM_TWO_DETAIL}} | One line about it. | All three are the nightly export, failing on the same malformed row. |
| {{DIGEST_URL}} | The full version in the app. | https://acme.com/reports/weekly |
| {{UNSUBSCRIBE_URL}} | One click, no login. Also goes in List-Unsubscribe. | https://acme.com/u/9f21ab |
## How it works
1. **A job runs weekly** It gathers the week per recipient and drops anyone with nothing to say.
2. **You check consent** Opted in, not suppressed, not bounced. A digest to a dead address is reputation.
3. **You send in a batch** POST /v1/emails/batch, up to 100 per call, with the unsubscribe headers on each.
4. **Unsubscribes take effect** Before the next run, without a login, including the one-click header path.
## Code
### TypeScript
`npm install @emails.sh/sdk`
```
import { readFileSync } from 'node:fs';
import { Emailssh } from '@emails.sh/sdk';
const mail = new Emailssh({ apiKey: process.env.EMAILSSH_API_KEY });
// What changes per send. In your app these come from the row you just
// wrote, not from literals.
const vars: Record = {
PRODUCT_NAME: 'Acme',
FIRST_NAME: 'Ada',
WEEK_RANGE: '24 to 31 July',
HEADLINE_STAT: '48 deploys, 2 rollbacks',
ITEM_ONE_TITLE: 'Checkout latency down 18%',
ITEM_ONE_DETAIL: 'The p95 moved from 840ms to 690ms after the cache change on Tuesday.',
ITEM_TWO_TITLE: '3 failed jobs need a look',
ITEM_TWO_DETAIL: 'All three are the nightly export, failing on the same malformed row.',
DIGEST_URL: 'https://acme.com/reports/weekly',
UNSUBSCRIBE_URL: 'https://acme.com/u/9f21ab',
};
const fill = (body: string) =>
Object.entries(vars).reduce(
(out, [name, value]) => out.replaceAll('{{' + name + '}}', value),
body
);
const { id } = await mail.send({
from: 'Acme ',
to: ['ada@example.com'],
subject: fill('Your week on {{PRODUCT_NAME}}: {{HEADLINE_STAT}}'),
html: fill(readFileSync('email.html', 'utf8')),
text: fill(readFileSync('email.txt', 'utf8')),
// Both headers, so Gmail and Outlook show their own unsubscribe
// control and a tired reader never has to reach for the spam button.
headers: {
'List-Unsubscribe': '<' + vars.UNSUBSCRIBE_URL + '>',
'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click'
},
tags: { type: 'weekly-digest' }
});
// Queued, not delivered. Ask for the id later, or take the webhook.
console.log(id);
```
### Python
`pip install emailssh`
```
import os
from emailssh import Emailssh
mail = Emailssh(api_key=os.environ["EMAILSSH_API_KEY"])
# What changes per send. In your app these come from the row you just
# wrote, not from literals.
values = {
"PRODUCT_NAME": "Acme",
"FIRST_NAME": "Ada",
"WEEK_RANGE": "24 to 31 July",
"HEADLINE_STAT": "48 deploys, 2 rollbacks",
"ITEM_ONE_TITLE": "Checkout latency down 18%",
"ITEM_ONE_DETAIL": "The p95 moved from 840ms to 690ms after the cache change on Tuesday.",
"ITEM_TWO_TITLE": "3 failed jobs need a look",
"ITEM_TWO_DETAIL": "All three are the nightly export, failing on the same malformed row.",
"DIGEST_URL": "https://acme.com/reports/weekly",
"UNSUBSCRIBE_URL": "https://acme.com/u/9f21ab",
}
def fill(body: str) -> str:
for name, value in values.items():
body = body.replace("{{" + name + "}}", value)
return body
with open("email.html", encoding="utf-8") as f:
html = f.read()
with open("email.txt", encoding="utf-8") as f:
text = f.read()
sent = mail.send(
# from_ rather than from, which is a Python keyword.
from_="Acme ",
to=["ada@example.com"],
subject=fill("Your week on {{PRODUCT_NAME}}: {{HEADLINE_STAT}}"),
html=fill(html),
text=fill(text),
# Both headers, so Gmail and Outlook show their own unsubscribe
# control and a tired reader never has to reach for the spam button.
headers={
"List-Unsubscribe": "<" + values["UNSUBSCRIBE_URL"] + ">",
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
},
tags={"type": "weekly-digest"},
)
# Queued, not delivered. Ask for the id later, or take the webhook.
print(sent["id"])
```
### curl
`Anywhere with curl and jq`
```
export EMAILSSH_API_KEY=esh_live_...
# The API substitutes nothing, so fill the placeholders before you post.
fill() {
sed \
-e 's|{{PRODUCT_NAME}}|Acme|g' \
-e 's|{{FIRST_NAME}}|Ada|g' \
-e 's|{{WEEK_RANGE}}|24 to 31 July|g' \
-e 's|{{HEADLINE_STAT}}|48 deploys, 2 rollbacks|g' \
-e 's|{{ITEM_ONE_TITLE}}|Checkout latency down 18%|g' \
-e 's|{{ITEM_ONE_DETAIL}}|The p95 moved from 840ms to 690ms after the cache change on Tuesday.|g' \
-e 's|{{ITEM_TWO_TITLE}}|3 failed jobs need a look|g' \
-e 's|{{ITEM_TWO_DETAIL}}|All three are the nightly export, failing on the same malformed row.|g' \
-e 's|{{DIGEST_URL}}|https://acme.com/reports/weekly|g' \
-e 's|{{UNSUBSCRIBE_URL}}|https://acme.com/u/9f21ab|g' "$1"
}
curl -sS https://emails.sh/v1/emails \
-H "Authorization: Bearer $EMAILSSH_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n \
--arg subject 'Your week on Acme: 48 deploys, 2 rollbacks' \
--arg html "$(fill email.html)" \
--arg text "$(fill email.txt)" \
'{from: "Acme ",
to: ["ada@example.com"],
subject: $subject,
html: $html,
text: $text,
headers: {"List-Unsubscribe": "", "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"},
tags: {type: "weekly-digest"}}')"
```
## Questions
### Why do the List-Unsubscribe headers matter?
They put an unsubscribe control in the client interface, next to the sender. Gmail and Outlook both require them for bulk senders now, and the reader who would otherwise press the spam button uses them instead, which protects the domain the rest of your mail goes out on.
### Should the digest go from a different subdomain?
Yes, once you have any volume. Keep bulk mail on its own subdomain so a bad digest week cannot damage delivery of password resets sent from the main one.
### What if there is nothing to report?
Skip the send. A digest with nothing in it teaches people that the email is not worth opening, and that lesson holds for the weeks when it is.
Docs: https://emails.sh/docs.md
All templates: https://emails.sh/templates.md