From 25e11f8047e7a9658bb0ce4efdc876ec44f8df82 Mon Sep 17 00:00:00 2001 From: Matthew Meszaros Date: Wed, 11 Nov 2026 16:11:38 +0100 Subject: [PATCH] feat: describe a Cloud-enrolled mailbox's warmup in the Advisor as managed by Warmbly Cloud rather than running, keeping the local warmup reading out of the new-mailbox ramp evidence and the docs --- docs/content/docs/guides/advisor.mdx | 2 +- internal/app/advisor/detect_mailbox.go | 29 ++++++++++++------- internal/app/advisor/detect_test.go | 21 ++++++++++---- internal/app/advisor/detect_warmup.go | 4 +-- .../advisor_snapshot_facts_live_test.go | 4 +-- internal/repository/pg_advisor.go | 4 +-- internal/repository/pg_advisor_snapshot.go | 4 +-- 7 files changed, 44 insertions(+), 24 deletions(-) diff --git a/docs/content/docs/guides/advisor.mdx b/docs/content/docs/guides/advisor.mdx index 286a79dce..e9927fd6a 100644 --- a/docs/content/docs/guides/advisor.mdx +++ b/docs/content/docs/guides/advisor.mdx @@ -112,7 +112,7 @@ Only the first two badge a nav tab. **Mailbox configuration**: a daily cap above the `50`/day safe band on a mailbox that is bouncing or drawing complaints, or that sent more than `50` in the last day without `100` clean sends behind it (a high cap with clean numbers is your call and is not flagged); a mailbox under `30` days old that sent more than `20` cold emails in the last day (a high cap alone is not flagged, since the warmup graduation ramp holds a new mailbox below it); a send gap under `5` minutes; unresolved errors on a mailbox campaigns still use. -**Warmup**: warmup off, or paused, on a mailbox that sent cold mail this week (critical on a new mailbox; a stopped warmup counts as off). Neither is raised when the workspace's plan does not include warmup, or for a mailbox connected to [Warmbly Cloud](/guides/warmbly-cloud/), whose warmup runs there rather than on your instance. Also: temporarily throttled sending, reported separately from quarantine or a pool block; none of the pool's warmup mail to the mailbox arriving, or its address hard-bouncing warmup from several workspaces, which stops the pool sending to it (see [unreachable mailboxes](/guides/warmup/#mailboxes-the-pool-cannot-reach)). Missing or stale Cloud status is reported separately from a real reputation ban, with steps to refresh it without disconnecting mailboxes. +**Warmup**: warmup off, or paused, on a mailbox that sent cold mail this week (critical on a new mailbox; a stopped warmup counts as off). Neither is raised when the workspace's plan does not include warmup, or for a mailbox connected to [Warmbly Cloud](/guides/warmbly-cloud/), whose warmup Warmbly Cloud manages rather than your instance (including whether it is running, paused, or waiting for its credential). Also: temporarily throttled sending, reported separately from quarantine or a pool block; none of the pool's warmup mail to the mailbox arriving, or its address hard-bouncing warmup from several workspaces, which stops the pool sending to it (see [unreachable mailboxes](/guides/warmup/#mailboxes-the-pool-cannot-reach)). Missing or stale Cloud status is reported separately from a real reputation ban, with steps to refresh it without disconnecting mailboxes. A **throttled** mailbox remains in the warmup pool. The advisor explains the automatic reduced sending pace rather than asking you to remove it from campaigns, wait a fixed week or manually re-enter the pool. Keep warmup running and do not increase its cap to bypass the slowdown. For placement throttles, half volume steps down to watch below `15%` spam placement, and watch lifts below `7.5%`; separate ramp limits still apply. Re-entry probation and other cooldowns follow the reason shown on the mailbox. A throttle alone does not mean the connection has failed or the provider has blocked the mailbox. diff --git a/internal/app/advisor/detect_mailbox.go b/internal/app/advisor/detect_mailbox.go index b694274ce..e7d1a0fab 100644 --- a/internal/app/advisor/detect_mailbox.go +++ b/internal/app/advisor/detect_mailbox.go @@ -126,16 +126,8 @@ func detectNewMailboxRampingFast(s *repository.AdvisorSnapshot) []Finding { Detail: fmt.Sprintf( "%s was connected %s ago and sent %d cold emails in the last day, on a cap of %d. A new sending identity has no reputation to spend yet; the safe start is 10-20/day, ramping only while bounce and complaint rates stay clean.", m.Email, plural(m.AgeDays, "day", "days"), m.ColdSent1d, m.CampaignLimit), - Remedy: fmt.Sprintf("Drop this mailbox to %d/day and raise it gradually over the next few weeks. Warmup should be running the whole time.", newMailboxSafeCap), - Evidence: map[string]any{ - "mailbox": m.Email, - "age_days": m.AgeDays, - "daily_cap": m.CampaignLimit, - "safe_start_cap": newMailboxSafeCap, - "warmup_running": m.WarmupActive, - "warmup_in_cloud": m.CloudWarmed, - "cold_sends_7d": m.ColdSent7d, - }, + Remedy: fmt.Sprintf("Drop this mailbox to %d/day and raise it gradually over the next few weeks. Warmup should be running the whole time.", newMailboxSafeCap), + Evidence: rampEvidence(m), Action: auto(withUndo(mailboxAction(m.ID, fmt.Sprintf("Start at %d/day instead", newMailboxSafeCap), map[string]any{"campaign_limit": newMailboxSafeCap}, @@ -237,3 +229,20 @@ func humanSeconds(sec int) string { } return fmt.Sprintf("%d seconds", sec) } + +// rampEvidence reports local warmup only where this instance owns it; Cloud's own state is not held here. +func rampEvidence(m repository.AdvisorMailbox) map[string]any { + ev := map[string]any{ + "mailbox": m.Email, + "age_days": m.AgeDays, + "daily_cap": m.CampaignLimit, + "safe_start_cap": newMailboxSafeCap, + "cold_sends_7d": m.ColdSent7d, + } + if m.CloudOwnsWarmup { + ev["warmup_managed_by_cloud"] = true + } else { + ev["warmup_running"] = m.WarmupActive + } + return ev +} diff --git a/internal/app/advisor/detect_test.go b/internal/app/advisor/detect_test.go index 8a2dd1431..8223069fd 100644 --- a/internal/app/advisor/detect_test.go +++ b/internal/app/advisor/detect_test.go @@ -242,21 +242,32 @@ func TestWarmupOffWhileSendingIsCriticalOnANewMailbox(t *testing.T) { } } -// Warmbly Cloud owns an enrolled mailbox's warmup, so its local columns being off is not evidence. -func TestCloudWarmedMailboxIsNotFlaggedForLocalWarmupState(t *testing.T) { +// Warmbly Cloud manages an enrolled mailbox's warmup, so its local columns being off is not evidence. +func TestCloudEnrolledMailboxIsNotJudgedOnLocalWarmup(t *testing.T) { m := healthyMailbox() m.WarmupActive = false m.CampaignLimit = newMailboxSafeCap - m.CloudWarmed = true + m.CloudOwnsWarmup = true got := findingsByKey(Detect(snapshotOf(m), defaults())) if _, fired := got["warmup_off_while_sending"]; fired { - t.Error("warmup-off fired on a mailbox Warmbly Cloud warms") + t.Error("warmup-off fired on a mailbox enrolled in Warmbly Cloud") } m.WarmupPaused = true if _, fired := findingsByKey(Detect(snapshotOf(m), defaults()))["warmup_paused"]; fired { - t.Error("warmup-paused fired on a mailbox Warmbly Cloud warms") + t.Error("warmup-paused fired on a mailbox enrolled in Warmbly Cloud") + } + + // The ramp finding names Cloud as the owner rather than reporting the local columns as warmup not running. + m.AgeDays, m.CampaignLimit = 3, 50 + m.ColdSent30d, m.ColdSent7d, m.ColdSent1d = 120, 120, 45 + f, fired := findingsByKey(Detect(snapshotOf(m), defaults()))["mailbox_new_ramping_fast"] + if !fired { + t.Fatal("a new Cloud mailbox sending at full volume should still be flagged") + } + if _, ok := f.Evidence["warmup_running"]; ok || f.Evidence["warmup_managed_by_cloud"] != true { + t.Errorf("ramp evidence on a Cloud mailbox = %v, want Cloud ownership and no local warmup reading", f.Evidence) } } diff --git a/internal/app/advisor/detect_warmup.go b/internal/app/advisor/detect_warmup.go index b27e9e05d..ba01eecdd 100644 --- a/internal/app/advisor/detect_warmup.go +++ b/internal/app/advisor/detect_warmup.go @@ -93,7 +93,7 @@ func detectWarmupMailNotArriving(s *repository.AdvisorSnapshot) []Finding { func detectWarmupOffWhileSending(s *repository.AdvisorSnapshot) []Finding { out := []Finding{} for _, m := range s.Mailboxes { - if !m.SendingCold() || m.ColdSent7d == 0 || m.WarmupActive || m.WarmupPaused || m.CloudWarmed || s.WarmupUnavailable { + if !m.SendingCold() || m.ColdSent7d == 0 || m.WarmupActive || m.WarmupPaused || m.CloudOwnsWarmup || s.WarmupUnavailable { continue } @@ -140,7 +140,7 @@ func detectWarmupPaused(s *repository.AdvisorSnapshot) []Finding { for _, m := range s.Mailboxes { // Resuming is not an option the plan offers, as after a trial ends. // A pause is deliberate; it only costs anything while the mailbox sends cold mail without it. - if !m.WarmupPaused || m.CloudWarmed || s.WarmupUnavailable || !m.SendingCold() || m.ColdSent7d == 0 { + if !m.WarmupPaused || m.CloudOwnsWarmup || s.WarmupUnavailable || !m.SendingCold() || m.ColdSent7d == 0 { continue } severity := models.AdvisorHigh diff --git a/internal/repository/advisor_snapshot_facts_live_test.go b/internal/repository/advisor_snapshot_facts_live_test.go index 5c1c9e832..79e79492b 100644 --- a/internal/repository/advisor_snapshot_facts_live_test.go +++ b/internal/repository/advisor_snapshot_facts_live_test.go @@ -77,7 +77,7 @@ func TestLiveAdvisorSnapshotReadsTheSendPathsFacts(t *testing.T) { if m.WarmupPaused { t.Error("a stopped warmup read as paused") } - if !m.CloudWarmed { + if !m.CloudOwnsWarmup { t.Error("a Cloud-enrolled mailbox read as warmed locally") } if m.WarmupPoolType != "premium" { @@ -87,7 +87,7 @@ func TestLiveAdvisorSnapshotReadsTheSendPathsFacts(t *testing.T) { if m.InActiveCampaign { t.Error("a disabled sender read as in a running campaign") } - if m.CloudWarmed { + if m.CloudOwnsWarmup { t.Error("a mailbox with no enrollment read as warmed by Cloud") } if m.WarmupPoolType != "free" { diff --git a/internal/repository/pg_advisor.go b/internal/repository/pg_advisor.go index 8ca40a00a..bdc245108 100644 --- a/internal/repository/pg_advisor.go +++ b/internal/repository/pg_advisor.go @@ -49,8 +49,8 @@ type AdvisorMailbox struct { WarmupIncrease int WarmupReplyRate int WarmupPoolType string - // CloudWarmed is true while Warmbly Cloud owns the mailbox's warmup, so the local warmup columns say nothing about it. - CloudWarmed bool + // CloudOwnsWarmup is true while the mailbox is enrolled in Warmbly Cloud, whose warmup may still be paused or held there; the local warmup columns say nothing about it. + CloudOwnsWarmup bool RiskBand string diff --git a/internal/repository/pg_advisor_snapshot.go b/internal/repository/pg_advisor_snapshot.go index 6e670497b..8e86fb0c3 100644 --- a/internal/repository/pg_advisor_snapshot.go +++ b/internal/repository/pg_advisor_snapshot.go @@ -88,7 +88,7 @@ func (r *advisorRepository) loadMailboxes(ctx context.Context, orgID uuid.UUID, -- Cloud reports the pool it warms a mailbox in; the local column is only the local pool's. COALESCE(enr.health_pool_type, ea.warmup_pool_type, 'free'), -- Any enrollment row hands warmup to Cloud, as the local scheduler's stand-down reads it. - enr.email_account_id IS NOT NULL AS cloud_warmed, + enr.email_account_id IS NOT NULL AS cloud_owns_warmup, ea.risk_band::text, COALESCE(sent.d7, 0), COALESCE(sent.d1, 0), COALESCE(sent.d30, 0), COALESCE(dl.bounces, 0), COALESCE(dl.complaints, 0), @@ -208,7 +208,7 @@ func (r *advisorRepository) loadMailboxes(ctx context.Context, orgID uuid.UUID, &m.AuthState, &m.AuthSPF, &m.AuthDKIM, &m.AuthDMARC, &m.AuthDMARCPolicy, &m.AuthFailingSince, &m.WarmupActive, &m.WarmupPaused, &m.WarmupBase, &m.WarmupMax, &m.WarmupIncrease, &m.WarmupReplyRate, &m.WarmupPoolType, - &m.CloudWarmed, + &m.CloudOwnsWarmup, &m.RiskBand, &m.ColdSent7d, &m.ColdSent1d, &m.ColdSent30d, &m.Bounces30d, &m.Complaints30d,