Platform

Notifications

How somebody finds out that something happened.

Two audiences: the people on a client's account, and Acrune operators. Creators are not notified. Acrune holds no creator email address and should not start — that relationship belongs to the partner whose product the creator actually uses, which is the premise of the partner API. Partners get webhooks, which are a different contract and do not exist yet.

The path an event takes

Text
apps/track          notification_outbox     apps/api             the reader
  something    ->     one row, unique   ->   resolve people  ->  feed + email
  happened            on a dedupe key        honour prefs

The tracker knows what happened and nothing about people. It writes a row into a table it owns and moves on. apps/api owns the people, the email queue and the templates, so it reads that table, works out who should hear, and delivers.

Reading across app ownership is what the dashboard already does with every tracker table. Writing across it stays forbidden, which is why this is an outbox and not a cross-app insert.

There is no queue, no event bus and no worker. The dispatcher runs on the same cron and the same opportunistic drain as the email queue.

Idempotency, twice

Producing is idempotent on a dedupe key the producer derives from the event — campaign.first_click:<campaign id>. The first-click producer sits on the redirect path and fires on every click, letting the unique index decide which one was first. Reading to find out would put a SELECT on the only hot path in the system to answer a question the index answers, and it is not awaited: a redirect that is slower because a bell did not light up is a bad trade.

Delivering is idempotent on (user_id, dedupe_key). A claim that failed halfway can be re-run and a digest can be recomputed on every cron without anybody's feed growing a second copy.

What is delivered

KindWhoEmails
campaign.first_clickThe accountYes
campaign.createdThe accountNo
api_key.issued / api_key.revokedThe accountNo
links.missing_postsThe account, weeklyNo
outbox.stalledOperators, and SlackNo

Only one kind emails. The feed costs a reader nothing; an email is an interruption that has to earn itself, and the default for a new kind is in-app only until somebody asks otherwise.

links.missing_posts is the one that does real work. A link with no post URL attached still counts clicks but cannot be ranked against the others, and nobody discovers that by looking — the links appear fine. It only counts links older than 48 hours, because telling somebody their hour-old campaign is broken is how a channel gets muted on day one.

outbox.stalled is the system watching itself. A dispatcher that quietly stops delivering is worse than none, because everybody downstream carries on believing they would have been told.

Preferences

A column per kind on notification_preferences, one row per person — not per organisation. Two people on the same account can want different things.

The column is part of the recipient query rather than a check after it, so a call site that forgets to filter is impossible to write. A missing row means every default, so nobody is backfilled and signing up costs no write.

email_enabled is a second axis, deliberately. Turning a kind off removes it from the feed too; turning email off keeps every notification and stops any of them leaving the building. Those are different wishes.

Sign-in links are unaffected by all of it. A sign-in link is not something anyone can meaningfully unsubscribe from, and withholding one because somebody left a notification stream would lock them out of their own account.

Deliverability

Three things protect the domain every sign-in link depends on:

  • Their own sender. Product notifications leave from EMAIL_FROM_NOTIFICATIONS, which falls back to EMAIL_FROM.

    Worth being precise about what this buys, because it is easy to overstate: mailbox providers track reputation per domain and per sending IP, not per local part. notifications@mail.acrune.com and hello@mail.acrune.com share one reputation, so a distinct address makes the sender legible to a human and does nothing for deliverability. Separating the two so a complaint about a digest cannot reach the sign-in link needs a second verified subdomain, and that is only worth doing once notification volume could carry a domain's reputation on its own — two cold subdomains are worse than one warm one.

  • Preview builds cannot mail a customer. In a preview deployment every recipient is rewritten to a sink address and the git branch is appended to the subject. A preview build has production credentials and real rows.

  • Bounces suppress themselves. Resend's webhook fills delivered_at/opened_at/bounced_at/complained_at on the queue row, and a hard bounce or a complaint writes the address to email_opt_outs without anybody doing anything. Continuing to mail an address that bounced is how a sending domain gets blocked.

The webhook signature is verified against the raw body, before parsing. Re-serialising a parsed object changes whitespace and key order, and the signature never matches again. An unset RESEND_WEBHOOK_SECRET closes the endpoint rather than opening it: it suppresses addresses, so an unverified one would let anybody stop mail reaching anybody.

What is set up today

All application mail leaves as mail.acrune.com, verified in Resend: DKIM on the resend selector, SPF via send.mail.acrune.com (include:amazonses.com, since Resend sends over SES), and DMARC at p=quarantine; pct=100 with aggregate reports going to contact@acrune.com. Google's reports show DKIM and SPF both passing and nothing quarantined.

The apex acrune.com is Google Workspace and human mail only — its SPF names no application sender and it carries no Resend selector. That separation is already the valuable one: a problem with application mail cannot touch the domain people actually correspond with.

Where the numbers come from

The feed is a table. Read state is server-side, so clearing the badge on a laptop clears it on a phone — which is the whole reason these are rows rather than something derived on the client. A notification is a thing that happened, and a thing that happened has to outlive the tab it arrived in.

Read notifications are deleted after 90 days by the same cron. Unread ones are kept.