Skip to content

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.

StepSent after signupSkipped whenMain link
setup — Finish setting up your hub≥ 6 hourssetup wizard finished (onboardingComplete)the hub
first_stay — Add your first stay≥ 2 daysat least one stayhub → Settings
share — Share your hub≥ 7 daysa stay with a guest emailthe hub
plus — What Lovely Home+ adds≥ 14 daysthe 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 ​

  1. A daily cron on the hub-jobs Worker (09:00 UTC) calls POST /api/public/activation-run on its platform with header X-Activation-Run-Secret. The same cron then calls POST /api/public/account-plan-run with 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).
  2. 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-stats over the platform health-auth channel — counts only, no personal data), and sends through Resend.
  3. Each step is claimed in activation_email_sends before sending (sent or skipped_done), so re-runs never double-send; a failed send releases the claim and is retried next run.
  4. 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-Post headers. GET /api/public/activation-unsubscribe shows a confirm button (so link scanners can't unsubscribe people); POST (the button, or a mail app's one-click) sets opted_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):

VariableTerraform varPurpose
ACTIVATION_EMAILS_ENABLEDactivation_emails_enabledMaster switch; nothing is sent while off
ACTIVATION_RUN_SECRETactivation_run_secretShared with the hub-jobs Worker; also signs unsubscribe links (rotating it invalidates links in emails already sent)
ACTIVATION_EMAILS_TEST_TOactivation_emails_test_toSandbox: 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 ​

  1. Apply D1 migration 0024_activation_emails.sql to 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.

  2. Deploy hubs (the activation-stats endpoint) and the platform/marketing site (signup checkbox).

  3. Sandbox: set activation_run_secret, activation_emails_enabled = true and activation_emails_test_to = "<your inbox>" in sandbox-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:

    bash
    curl -X POST https://platform-sandbox.lovely-home.co.uk/api/public/activation-run \
      -H "X-Activation-Run-Secret: $ACTIVATION_RUN_SECRET"
  4. 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.

Consent wording is on /signup (signup.setupTipsLabel, 13 languages). Unticked signups store consented_at = NULL and get nothing.