Activation emails
New owners who tick "Email me a few setup tips" at signup (unticked by default) get up to three short emails in their first week (#833), and one at day 14 about Lovely Home+ if they are still on Free (#1536). Each step is skipped once the owner has already done it, so people who are already set up hear nothing.
| Step | Sent after signup | Skipped when | Main link |
|---|---|---|---|
setup — Finish setting up your hub | ≥ 6 hours | setup wizard finished (onboardingComplete) | the hub |
first_stay — Add your first stay | ≥ 2 days | at least one stay | hub → Settings |
share — Share your hub | ≥ 7 days | a stay with a guest email | the hub |
plus — What Lovely Home+ adds | ≥ 14 days | the hub is on Lovely Home+ (site_billing.plan_tier, so Multi Home hubs count) | Account → upgrade this hub |
Owners are emailed for 21 days after signup at most, only while the hub's billing is live (trialing/active/past_due), and never after they unsubscribe. Links carry utm_source=activation&utm_medium=email&utm_campaign={step}. Emails are English, like the other account emails.
How it runs
- A daily cron on the hub-jobs Worker (09:00 UTC) calls
POST /api/public/activation-runon its platform with headerX-Activation-Run-Secret. The same cron then callsPOST /api/public/account-plan-runwith the same header: account plan cancels and downgrades that fall due are finalised and the week-before reminders sent (#1450), and closed accounts are reminded the day before and deleted after 7 days (#1528; see platform-billing.md). - The platform lists opted-in hubs from
activation_email_consent+site_billing, asks each hub only when a step is due (GET /api/platform/activation-statsover the platform health-auth channel — counts only, no personal data), and sends through Resend. - Each step is claimed in
activation_email_sendsbefore sending (sentorskipped_done), so re-runs never double-send; a failed send releases the claim and is retried next run. - Every email has a signed one-click unsubscribe link (in the HTML it's the words "Unsubscribe here"; the plain-text part shows the URL) and
List-Unsubscribe/List-Unsubscribe-Postheaders.GET /api/public/activation-unsubscribeshows a confirm button (so link scanners can't unsubscribe people);POST(the button, or a mail app's one-click) setsopted_out_at.
The run's JSON summary (considered, sent, skipped, waiting, errors) appears in the hub-jobs Worker logs. Counts by step are in the signup funnel API (activationEmails).
The same hub-jobs Worker also calls POST /api/public/clean-run every 15 minutes with the same secret, for cleaner emails (cleans.md).
Settings
Platform Pages env vars (Terraform, platform_admin module):
| Variable | Terraform var | Purpose |
|---|---|---|
ACTIVATION_EMAILS_ENABLED | activation_emails_enabled | Master switch; nothing is sent while off |
ACTIVATION_RUN_SECRET | activation_run_secret | Shared with the hub-jobs Worker; also signs unsubscribe links (rotating it invalidates links in emails already sent) |
ACTIVATION_EMAILS_TEST_TO | activation_emails_test_to | Sandbox: send every email to this inbox instead of the owner, subject prefixed [test → owner@…] |
Also needs RESEND_API_KEY, PLATFORM_SITE_ARCHIVE_SECRET and platform health auth (already used by other platform → hub calls).
Rollout
Apply D1 migration
0024_activation_emails.sqlto the platform billing database — sandbox first:PLATFORM_BILLING_D1_NAME=lovely-home-platform-billing-sandbox node scripts/apply-platform-billing-migration.mjs, later production without the variable. Until it is applied, signup simply doesn't record consent (best effort) and the run finds nobody.Deploy hubs (the
activation-statsendpoint) and the platform/marketing site (signup checkbox).Sandbox: set
activation_run_secret,activation_emails_enabled = trueandactivation_emails_test_to = "<your inbox>"insandbox-hub.tfvars; apply the sandbox state (see platform-terraform.md). Sign up with the box ticked; the setup email arrives ~6 hours later on the next daily run, or trigger a run by hand:bashcurl -X POST https://platform-sandbox.lovely-home.co.uk/api/public/activation-run \ -H "X-Activation-Run-Secret: $ACTIVATION_RUN_SECRET"Production is applied by the Platform admin Terraform workflow, not from a laptop (#966). Its tfvars are generated from GitHub settings:
- secret
ACTIVATION_RUN_SECRET(openssl rand -hex 32, not the sandbox value); - repository variable
ACTIVATION_EMAILS_ENABLED = true.
Then run the workflow (confirm
apply-platform-admin). Without the secret, the switch stays off and no cron is created. There is no test inbox in production.- secret
Consent wording is on /signup (signup.setupTipsLabel, 13 languages). Unticked signups store consented_at = NULL and get nothing.