Documentation menuAnnounce
Announce
E-mail digest and chat posts for new releases.
@weber-development/derivative-announce turns new releases into an e-mail and chat messages, in
English, German, French or Italian.
E-mail digest
npx derivative-announce digest --feed public/changelog.json --product "Acme" \
--url https://acme.example/changelog --lang de \
--logo https://acme.example/logo.png --color "#0f766e" \
--unsubscribe https://acme.example/unsubscribe --footer "Acme AG, Bahnhofstrasse 1, 8001 Zürich" \
--state .announce-mail.json --out digest.html
This writes digest.html and digest.txt and prints the subject line. The layout uses tables and
inline styles, so it renders in Outlook and Gmail. A release with an image (feed format 2) shows its first image, and its links appear as call-to-action links; with --lang the digest uses the translations in the feed. Sending is up to you: hand the files to
Postmark, Resend, SES or your newsletter tool.
Chat
DERIVATIVE_WEBHOOK_URL=https://hooks.slack.com/... \
npx derivative-announce post --to slack --feed public/changelog.json --product "Acme" \
--state .announce-slack.json
--to accepts slack, teams, discord, mattermost and google-chat. Use --dry-run to print
the payload instead. Keep webhook URLs in your CI secrets.
Mastodon
DERIVATIVE_MASTODON_TOKEN=... npx derivative-announce post --to mastodon \
--instance https://mastodon.social --feed public/changelog.json --product "Acme" \
--hashtag changelog --state .announce-mastodon.json
Each release becomes one public status of at most 500 characters: title, the first summary
paragraph and as many entries as fit, then the changelog link and hashtags. Create the token under
Preferences → Development with only the write:statuses scope. The instance can also come from
DERIVATIVE_MASTODON_URL.
Bluesky
DERIVATIVE_BLUESKY_APP_PASSWORD=... npx derivative-announce post --to bluesky \
--handle acme.bsky.social --feed public/changelog.json --product "Acme" \
--hashtag changelog --state .announce-bluesky.json
Each release becomes one post of at most 300 characters with the changelog as a link card and the
hashtags as real tags. Create an app password under Settings → Privacy and security → App
passwords; never use the account password. The handle can also come from
DERIVATIVE_BLUESKY_HANDLE.
DERIVATIVE_LINKEDIN_TOKEN=... npx derivative-announce post --to linkedin \
--author urn:li:organization:123456 --feed public/changelog.json --product "Acme" \
--hashtag changelog --state .announce-linkedin.json
Each release becomes one post on your company page, with the summary and entries as text and the
changelog as a link card. Texts are escaped so characters like (, # or _ show up as typed. The
access token needs the w_organization_social scope (or w_member_social for a personal profile with
urn:li:person:…); LinkedIn issues it after you add the "Share on LinkedIn" product to your app.
The author can also come from DERIVATIVE_LINKEDIN_AUTHOR. The API version header is set to last
month's YYYYMM; pin another one with DERIVATIVE_LINKEDIN_VERSION. Tokens expire (60 days by
default), so renew the secret in your CI before then. Use --dry-run to see the post first.
Subscribers
The digest above leaves the sending to you. For a real subscriber list, Derivative Pro runs the whole cycle with double opt-in: sign-up form, confirmation e-mail, one-click unsubscribe and the sending itself, through Resend, Postmark, Amazon SES or any SMTP server. There is no third-party list to maintain and no tracking: a subscriber is an e-mail address, a language and the timestamps of the request and the confirmation.
1. The handler
One Fetch API handler (Next.js route handler, Hono, Remix, Deno, Bun, Cloudflare Workers) answers
POST /subscribe, /confirm and /unsubscribe below the URL where you mount it:
// app/api/news/[action]/route.ts (Next.js)
import { createSubscribeHandler, resendSender } from "@weber-development/derivative-announce";
import { fileSubscribers } from "@weber-development/derivative-announce/node";
const handler = createSubscribeHandler({
store: fileSubscribers(".data/subscribers.json"),
secret: process.env.DERIVATIVE_SUBSCRIBE_SECRET!, // 32+ random characters, keep it secret
send: resendSender(process.env.DERIVATIVE_RESEND_KEY!),
from: "Acme <news@acme.ch>", // the domain must be verified at your provider
product: "Acme",
baseUrl: "https://acme.ch/api/news",
lang: "de",
});
export { handler as GET, handler as POST };
Your form posts email (and optionally lang) to /api/news/subscribe, as a form or as JSON
with Accept: application/json. The answer is the same for known and unknown addresses.
What the handler takes care of, so you do not have to:
- Double opt-in. An address is only mailed after its owner clicked the link. The link carries a signed token that expires after seven days and works for confirming only.
- Mail scanners. Corporate scanners open every link in a mail. The confirm and unsubscribe
links therefore show a button, and only the click on it (a
POST) changes anything. - One-click unsubscribe. The same
POSTanswers the request that Gmail and Yahoo send for theList-Unsubscribe-Postheader (RFC 8058), which both require from bulk senders. - No mail bombing. An unconfirmed address is not mailed again within ten minutes, and a confirmed one is never mailed by the form.
- Header injection. Addresses with line breaks or other special characters are rejected.
Without a disk (Vercel, Workers), keep the list in Postgres or SQLite with
sqlSubscribers(query, { dialect }); store.setup() creates the table. It takes the same
driver-free query function as sqlStore in derivative-insights.
2. Sending
DERIVATIVE_SUBSCRIBE_SECRET=... DERIVATIVE_RESEND_KEY=... npx derivative-announce send \
--feed public/changelog.json --subscribers .data/subscribers.json \
--from "Acme <news@acme.ch>" --provider resend --base-url https://acme.ch/api/news \
--product "Acme" --lang de --state .announce-mail.json
Each confirmed subscriber gets one e-mail with a personal unsubscribe link and the
List-Unsubscribe headers. --provider postmark uses DERIVATIVE_POSTMARK_TOKEN and the
broadcast message stream. --provider ses uses Amazon SES with AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY (and AWS_SESSION_TOKEN) and AWS_REGION; the AWS user needs only
ses:SendEmail, and requests are signed in the package, without the AWS SDK.
--provider smtp uses any SMTP server through DERIVATIVE_SMTP_URL, for example
smtps://user:password@smtp.example.com:465 (TLS from the start) or
smtp://user:password@smtp.example.com:587 (STARTTLS); percent-encode special characters in the
password. TLS is required: the password is never sent over a connection without it. In code:
sesSender(credentials, { region }) and, from /node, smtpSender({ host, port, user, pass }). --dry-run counts the recipients. With --state, each release goes
out once. Addresses that fail are listed and the exit code is 1; the others have their mail.
In code, call sendDigest({ releases, brand, store, send, secret, baseUrl, from }).
3. Managing the list
npx derivative-announce subscribers list --file .data/subscribers.json
npx derivative-announce subscribers export --file .data/subscribers.json --status confirmed > consent.csv
npx derivative-announce subscribers remove --file .data/subscribers.json --email max@example.ch
export writes the evidence of consent: when each address was requested and confirmed. remove
deletes an address completely, for erasure requests.
Legal notes
This is a technical aid, not legal advice. In Germany, Austria and Switzerland the double opt-in with a stored confirmation time is the usual proof that the owner of the address agreed. Mention the newsletter in your privacy policy (purpose, provider, how to unsubscribe) and your e-mail provider as a processor, and sign a data processing agreement with them. The confirmation e-mail and the digest contain no tracking pixels and no click tracking.
Each release once
--state <file> stores the newest announced release. The next run only picks up releases after
it, so a CI job can run on every deploy. Use one state file per channel. Without a state file,
--since <date> and --limit <n> select the releases.
In code
import {
chatPayload,
postWebhook,
renderDigest,
selectReleases,
} from "@weber-development/derivative-announce";
const releases = selectReleases(feed, { after: lastAnnounced });
const { subject, html, text } = renderDigest(releases, { name: "Acme", url }, { lang: "de" });
await postWebhook(webhookUrl, chatPayload("teams", releases[0], { product: "Acme", url }));