diff --git a/cmd/backend/main.go b/cmd/backend/main.go index a8de19696..7f5157c22 100644 --- a/cmd/backend/main.go +++ b/cmd/backend/main.go @@ -2599,12 +2599,11 @@ func main() { // Normalized: the CNAME value the advisor hands over has to be the // bare host, whatever shape TRACKING_DOMAIN was set in. advisor.WithTrackingHost(config.TrackingHostname()), - // Each step's copy is judged for how it reads to its recipient, - // cached by the hash of the words so unchanged copy costs nothing. - advisor.WithCopyJudge(typeSafeAsker(typeSafeClient), repository.NewCopyJudgmentRepository(primaryDB.Pool)), // So the domain-auth finding reports this install's actual gate // (enforced or not, and the grace window) instead of a default one. - advisor.WithDomainAuthPolicy(instanceSettings)) + advisor.WithDomainAuthPolicy(instanceSettings), + // So the warmup findings never ask a plan without warmup to turn it on. + advisor.WithWarmupAccess(featureGateService)) aitools.RegisterAdvisorTools(aiToolRegistry, advisorService) go (&advisor.Runner{Repo: advisorRepository, Service: advisorService}).Run(ctx) diff --git a/docs/content/docs/development/configuration.mdx b/docs/content/docs/development/configuration.mdx index b9c891111..87fabebe1 100644 --- a/docs/content/docs/development/configuration.mdx +++ b/docs/content/docs/development/configuration.mdx @@ -863,7 +863,7 @@ Salesforce reads `SALESFORCE_OAUTH_CLIENT_ID` and `SALESFORCE_OAUTH_CLIENT_SECRE | `WEB_READER_CUSTOM_URL`, `WEB_READER_CUSTOM_API_KEY` | Any reader that answers a GET with the page's HTML, or JSON carrying it (`html`, `content`, `data.html`). The URL is a template: `{url}` is replaced by the page address as is, `{url_encoded}` by its query-escaped form. The key is sent as a bearer token | unset | | `MAILHOST_ISPDB` | `true` lets mailbox server detection ask Mozilla's Thunderbird ISPDB (`autoconfig.thunderbird.net`) about a domain whose MX records and own autoconfig file name no known provider. Only the domain name is sent. See [data control](/development/data-control/#outbound-calls) | `false` on a self-host, `true` on Warmbly Cloud | | `MAILVENDOR_SANDBOX_URL` | Development only. Points every inbox vendor client at the [sandbox's mock vendor API](/development/sandbox/#mock-inbox-vendors) (`/inboxkit`, `/mailforge`) instead of the real vendors. Ignored unless `APP_ENV` is `dev` | unset | -| `TYPESAFE_API_KEY` | TypeSafe API key. Turns on the typed judgments: reply classification, the copy judgment in the Advisor and the editor, warmup content review (otherwise performed by OpenAI when its generator is configured), bounce classification, import column mapping and per-form triage. Inbox tagging needs the switch below as well. See [data control](/development/data-control/#typesafe-judgments) for what each one sends | unset | +| `TYPESAFE_API_KEY` | TypeSafe API key. Turns on the typed judgments: reply classification, the copy judgment in the editor, warmup content review (otherwise performed by OpenAI when its generator is configured), bounce classification, import column mapping and per-form triage. Inbox tagging needs the switch below as well. See [data control](/development/data-control/#typesafe-judgments) for what each one sends | unset | | `TYPESAFE_ENDPOINT` | URL the TypeSafe judgments are posted to, for a regional or proxied TypeSafe endpoint. Read by the backend, the consumer and `warmblyctl inbox-tag`; has no effect without `TYPESAFE_API_KEY`. Must be `https`, except `http` to a loopback or private-network host; any other value stops the service at startup | `https://api.typesafe.ai/v1/systemone` | | `INBOX_TAGGING_ENABLED` | `true` enables automatic inbox tagging when `TYPESAFE_API_KEY` is also set. Message subject, current body, and the previous outbound body are sent to TypeSafe | `false` | diff --git a/docs/content/docs/development/data-control.mdx b/docs/content/docs/development/data-control.mdx index f38b91515..b42662c4c 100644 --- a/docs/content/docs/development/data-control.mdx +++ b/docs/content/docs/development/data-control.mdx @@ -82,7 +82,7 @@ Mail over a daily budget is deferred, never dropped: the provider cursor is held |---|---|---|---| | Automatic inbox tagging | `INBOX_TAGGING_ENABLED=true` | The inbound subject and bounded plain-text body (for a notification recognised offline by its sender, only while the workspace asks notifications whether they need action, or asks one of its own questions of them), plus the previous outbound message in the thread and the name of the campaign it belongs to when one exists, the workspace's own tagging questions, and the names of its tagging languages when any are chosen | `inbox_tag_results`, with the raw probabilities and the actions taken. Completed results travel with the Inbox group in a workspace export; processing claims do not | | Reply classification | The key alone | The subject and body of a reply to a campaign, only when no tagging verdict exists for it and the offline layers could not decide | `campaign_contact_progress.reply_class` and `reply_intent` | -| Copy judgment | The key alone | The subject and body of a campaign step, at Advisor evaluation and on the editor's re-check | `copy_judgments`, keyed by a hash of the copy and never exported | +| Copy judgment | The key alone | The subject and body of a campaign step, on the editor's re-check | Nothing stored | | Warmup content lint | The key alone | A generated warmup thread before it enters the bank | Review state is stored with the generated thread; rejected threads stay archived and are counted on the generation job | | Bounce classification | The key alone | The bounce reason text (the status code and the receiving server's reply), only when its status code and wording do not already say whether the address is at fault | `deliverability_events.metadata` | | Import column mapping | The key alone | For an import or Google Sheets preview with columns no header matched: every column header, the kind of value each column holds (email addresses, dates, short text and so on, worked out on the instance), and the workspace's custom field names. Never a cell value, and nothing at all unless the first row is clearly headers: none of its cells may be an address, a date or a number, and the Email column must have a header of its own. A contact's row fails that, since its Email cell is the address or blank | Nothing is stored; the answer only fills in the suggested mapping | diff --git a/docs/content/docs/guides/advisor.mdx b/docs/content/docs/guides/advisor.mdx index 5c5c2b83a..7b3039139 100644 --- a/docs/content/docs/guides/advisor.mdx +++ b/docs/content/docs/guides/advisor.mdx @@ -5,6 +5,8 @@ description: "Warmbly watches your sending and tells you what to fix, on the pag The Advisor checks your workspace for problems that quietly hurt cold outreach, such as climbing complaints or a domain missing DMARC. It says what is wrong and what to do, on the page where the problem is. +It only speaks up when something is hurting deliverability or stopping mail from going out, and never about a choice that is yours to make. A one-email campaign, a long follow-up gap, a single copy variant or a high cap on a mailbox with clean numbers is left alone. + ## Fix a finding @@ -37,14 +39,12 @@ Apply the fix. **Done** offers **Undo** where the change can be reverted. ## Good to know -- Core detection uses explicit rules and thresholds, works with no AI configured, and never charges the workspace balance. Optional TypeSafe copy reviews are automated judgments. +- Detection uses explicit rules and thresholds, works with no AI configured, and never charges the workspace balance. - A check stays quiet until it has enough data, for example `100` sends in 30 days for complaint rate. - Nothing is applied until you have seen the **What changes** screen, and the change runs with your permissions. - Autopilot, under **Settings > Workspace**, is off by default and only takes bounded fixes that can be undone. - **Snooze** hides a finding for a week or a month. **Stop suggesting this** dismisses it until the problem clears and recurs. -- Applied fixes leave the suggestions list immediately. Campaign, step and mailbox changes trigger a background recheck; findings that no longer apply disappear when it finishes. Saved copy is reviewed again if it changed, using cached judgments for unchanged content. If the review service is unavailable, its existing findings stay until a successful review. - -Follow-up spacing advice applies only after the campaign's first email. A zero-day wait on the first email is valid: it can send when the campaign's schedule and sending limits allow. The first email still receives content checks. With TypeSafe configured, a separate copy check can flag wording that reads as bulk marketing; that is a judgment about the message, not a recommendation to delay it or proof that it will land in spam. +- Applied fixes leave the suggestions list immediately. Campaign, step and mailbox changes trigger a background recheck; findings that no longer apply disappear when it finishes. @@ -78,7 +78,7 @@ If one check fires on many things, they collapse into a single card ("19 mailbox ## How findings are made -Core checks use explicit rules and thresholds over your workspace data. Optional TypeSafe copy reviews supply model judgments to the copy checks described below. A separate AI narrator rewrites explanations; it cannot create a finding, change its severity, or change what a fix does. Self-hosts with no AI configured still receive the core checks, and Advisor evaluations never charge the workspace balance. +Checks use explicit rules and thresholds over your workspace data. A separate AI narrator rewrites explanations; it cannot create a finding, change its severity, or change what a fix does. Self-hosts with no AI configured receive every check, and Advisor evaluations never charge the workspace balance. ### Sample floors @@ -90,8 +90,6 @@ A check stays quiet until it can be right. Two bounces in thirty sends is not a | Bounce rate | `50` sends in 30 days | | Spam placement | `20` warmup deliveries in 7 days | | Warmup mail not arriving | `5` warmup emails to the mailbox in 7 days, from at least `2` workspaces | -| Reply rate and copy | `200` sends in 30 days | -| Per-step comparison | `100` sends on that step | ### Severity @@ -110,25 +108,21 @@ Only the first two badge a nav tab. ## What it checks -**Deliverability**: complaint rate per mailbox (warns `0.03%`, critical `0.10%`, matching Google's bulk-sender ceiling); bounce rate (warns `3%`, critical `5%`, where SES opens a review); spam placement on warmup mail at Google, Microsoft and Yahoo (warns `10%`, escalates `20%`, critical `50%`; other mail hosts are not counted, see [how spam placement is judged](/guides/warmup/#how-spam-placement-is-judged)); SPF and DMARC per sending domain (critical while sending cold, since Google requires them; an unchecked domain is never called failing, and DKIM is never reported missing because its selector is not discoverable from DNS); and whether a mailbox has its own verified tracking domain. +**Deliverability**: complaint rate per mailbox (warns `0.03%`, critical `0.10%`, matching Google's bulk-sender ceiling); hard-bounce rate (warns `3%`, critical `5%`, where SES opens a review; a full mailbox, a reputation block or a temporary failure is not counted, as in the [pool's health model](/guides/warmup/)); spam placement on warmup mail at Google, Microsoft and Yahoo (warns `10%`, escalates `20%`, critical `50%`; other mail hosts are not counted, see [how spam placement is judged](/guides/warmup/#how-spam-placement-is-judged)); SPF and DMARC per sending domain of an active mailbox (critical while sending cold, since Google requires them; an unchecked domain is never called failing, and DKIM is never reported missing because its selector is not discoverable from DNS); and whether a mailbox has its own verified tracking domain, checked only when a running campaign tracks opens or links through it without a verified tracking domain of its own. -**Mailbox configuration**: daily cap above the `50`/day safe band (gently with clean numbers, firmly without); a mailbox under `30` days old sending above `20`/day; a send gap under `5` minutes; unresolved errors on a mailbox campaigns still use; too few mailboxes carrying total volume; an inactive mailbox attached to a running campaign. +**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 while sending cold (critical on a new mailbox); warmup left paused; a ceiling too low to balance cold volume (roughly half the cold cap); reply rate under `20%`, making warmup one-way; temporarily throttled sending, reported separately from quarantine or a pool block; none of the pool's warmup mail to the mailbox arriving, 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. Also: temporarily throttled sending, reported separately from quarantine or a pool block; none of the pool's warmup mail to the mailbox arriving, 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. The advisor's placement sample covers today and the preceding six UTC dates, matching the Deliverability display and placement-health decisions. After an upgrade, the next advisor evaluation replaces outdated throttle/exclusion guidance automatically. A campaign hold you already applied remains yours to release after checking any other findings. -**Campaigns**: no follow-ups; reply rate under `1%` at volume, escalating under `0.3%`; one step replying below a quarter of the campaign's best (compared only against siblings, which share an audience); one-click unsubscribe off; a daily limit above what its mailboxes can send; no active sender; follow-up spacing outside `2` to `14` days; under `7` days of leads left; no A/B test at high volume; a sending window too narrow for the volume; contacts enrolled in several running campaigns. +**Campaigns**: one-click unsubscribe off; a running campaign with no active sender. -**Copy** (conservative, and drafts are skipped): a merge variable that will not resolve, shipping a literal `{{token}}`; two or more bulk-mail phrases (one is never flagged); over `200` words; a subject over `60` characters; more than two links in a first touch; a shouting subject. +**Copy** (drafts are skipped): a merge variable that will not resolve, shipping a literal `{{token}}`; two or more bulk-mail phrases, matched as whole words (one is never flagged); more than two distinct links in the first email; a shouting subject. Links and capitals are measured on the copy as a recipient reads it: rendered for a contact with every field filled, with markup and `{{if}}` blocks gone. A follow-up sent in the same thread goes out under the first email's subject, so its own subject is not checked. Length, wording and calls to action are yours to judge and are not checked. -Two more copy findings run only when the operator has configured TypeSafe (`TYPESAFE_API_KEY`), a calibrated reader model: an optional **wording review**, and a step with **no clear ask**, either asking for nothing or for several things. The wording review is low severity. Tone advice requires confident agreement that the copy sounds promotional and lacks relevance to the reader or their role. A business offer, a reusable template or a merge variable alone is not enough. Explicit guarantees, free-money or prize promises, and artificial urgency are checked separately. These are model assessments, not measurements of spam placement or reply likelihood. Dismiss a review that does not fit your message. - -Each step's subject and body are sent to TypeSafe for this, once per version of the copy and review policy. Verdicts are cached; saving unchanged content reuses its judgment. A policy update rechecks existing copy. At most `40` steps are judged per evaluation, and the rest wait for the next run. - -**List quality**: shared inboxes (`info@`, `sales@`) above `15%`; consumer domains above `40%` of a B2B list; suppressed contacts above `10%`; missing first names above `10%` when copy personalizes on them; unsubscribed contacts still enrolled. +**List quality**: shared inboxes (`info@`, `sales@`) above `15%`; missing first names above `10%` when the copy prints the name with no fallback (a name inside `{{if .FirstName}}`, `{{with .FirstName}}`, `| default "there"` or `or` is covered); unsubscribed contacts still enrolled. @@ -146,7 +140,7 @@ Findings needing a judgement call have no settings preview. Their second screen ### Fix with agent -Findings whose fix edits something Warmbly owns (copy, sequence shape, list membership) offer **Fix with agent**: it reads the current campaign, step, or list, makes the smallest change that resolves the problem, and reports back. +Findings whose fix edits something Warmbly owns (copy or list membership) offer **Fix with agent**: it reads the current campaign, step, or list, makes the smallest change that resolves the problem, and reports back. It runs as you, with your permissions, and only gets the tools that finding's category needs. A copy problem gets read access to the campaign and edit access to that step, nothing more. **No tool set can send mail, delete a campaign or contact, or touch team, billing, or API keys.** Each loop is charged to the workspace balance for the tokens it uses, typically a few cents. @@ -170,7 +164,6 @@ Under **Settings > Workspace**, off by default. It only takes fixes that are bou - lowering a cap above the safe band, or one a new mailbox jumped to early - cutting the cap on a mailbox drawing complaints - widening a gap that is too short -- matching a campaign's daily limit to its mailboxes' real capacity - turning on one-click unsubscribe **It never pauses sending, edits copy, starts or resumes warmup, or acts without an undo.** Eligible findings are marked **Auto** on the card whether or not it is on, so the set is visible before you enable it. It acts as the member who enabled it, with their permissions, logged as them, and stops if that person leaves. At most ten fixes per evaluation. diff --git a/internal/app/advisor/detect_campaign.go b/internal/app/advisor/detect_campaign.go index d213eafce..228c99e2f 100644 --- a/internal/app/advisor/detect_campaign.go +++ b/internal/app/advisor/detect_campaign.go @@ -2,39 +2,15 @@ package advisor import ( "fmt" - "math" - - "github.com/google/uuid" "github.com/warmbly/warmbly/internal/models" "github.com/warmbly/warmbly/internal/repository" ) -// campaignDetectors cover campaign shape and performance: whether a campaign is -// configured to succeed, and whether it is actually succeeding. +// campaignDetectors cover the campaign settings that decide whether mail goes +// out at all and whether recipients can leave. func campaignDetectors() []Detector { return []Detector{ - { - Key: "campaign_no_followups", - Category: models.AdvisorCategoryCampaign, - About: "A cold campaign with a single email and no follow-up steps. Most replies to cold outreach arrive on a follow-up rather than the first send, so a one-step campaign gives up most of its own results.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns}, - Run: detectNoFollowUps, - }, - { - Key: "campaign_reply_rate_low", - Category: models.AdvisorCategoryCampaign, - About: "A campaign's reply rate at volume. A very low reply rate on a large sample means the offer, the audience, or the copy is wrong, and sending more of it will cost sender reputation without producing results.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns}, - Run: detectReplyRateLow, - }, - { - Key: "campaign_step_dropoff", - Category: models.AdvisorCategoryCampaign, - About: "One sequence step performing far worse than the campaign's best step. Because every step reaches the same audience, a step that underperforms the others by a wide margin is a copy problem isolated to that message.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns, repository.AdvisorSectionSteps}, - Run: detectStepDropoff, - }, { Key: "campaign_unsubscribe_header_off", Category: models.AdvisorCategoryCampaign, @@ -42,13 +18,6 @@ func campaignDetectors() []Detector { Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns}, Run: detectUnsubscribeHeaderOff, }, - { - Key: "campaign_capacity_shortfall", - Category: models.AdvisorCategoryCampaign, - About: "A campaign whose daily limit exceeds what its attached mailboxes can safely send. The campaign will silently deliver less than configured, or push mailboxes past their caps.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns}, - Run: detectCapacityShortfall, - }, { Key: "campaign_no_senders", Category: models.AdvisorCategoryCampaign, @@ -56,41 +25,6 @@ func campaignDetectors() []Detector { Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns}, Run: detectNoSenders, }, - { - Key: "campaign_followup_spacing", - Category: models.AdvisorCategoryCampaign, - About: "The gap between follow-up steps. Too close reads as pestering and drives unsubscribes and complaints; too far apart and the recipient no longer remembers the first email.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns, repository.AdvisorSectionSteps}, - Run: detectFollowUpSpacing, - }, - { - Key: "campaign_list_exhaustion", - Category: models.AdvisorCategoryCampaign, - About: "A running campaign about to run out of leads. Campaigns do not announce that they have finished their list; they just stop producing results.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns}, - Run: detectListExhaustion, - }, - { - Key: "campaign_no_ab_test", - Category: models.AdvisorCategoryCampaign, - About: "A high-volume campaign running a single variant. At this volume an A/B test costs nothing and is the only way to know whether the copy is the constraint.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns}, - Run: detectNoABTest, - }, - { - Key: "campaign_narrow_window", - Category: models.AdvisorCategoryCampaign, - About: "A sending window too short to fit the campaign's daily volume at safe pacing. The campaign either underdelivers or compresses its sends into a burst.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns}, - Run: detectNarrowWindow, - }, - { - Key: "campaign_duplicate_enrollment", - Category: models.AdvisorCategoryCampaign, - About: "Contacts enrolled in more than one running campaign at the same time. To the recipient this is two unrelated strangers pitching in the same week, which is how a sender earns a complaint rather than a reply.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionOrg}, - Run: detectDuplicateEnrollment, - }, } } @@ -105,167 +39,6 @@ func runningCampaigns(s *repository.AdvisorSnapshot) []repository.AdvisorCampaig return out } -func detectNoFollowUps(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, c := range s.Campaigns { - if c.Status == "draft" || c.EmailStepCount == 0 || c.EmailStepCount >= 2 { - continue - } - - out = append(out, Finding{ - Key: "campaign_no_followups", - GroupTitle: "{count} campaigns are a single email with no follow-up", - Category: models.AdvisorCategoryCampaign, - Severity: models.AdvisorMedium, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "campaign", - EntityID: ref(c.ID), - EntityLabel: c.Name, - Impact: clampImpact(35 + c.LeadsTotal/100), - Title: fmt.Sprintf("%s is a single email with no follow-up", c.Name), - Detail: fmt.Sprintf( - "%s sends one email and stops. Most replies to cold outreach arrive on a follow-up rather than the first send, so a one-step campaign gives up the majority of its own results across %s.", - c.Name, plural(c.LeadsTotal, "lead", "leads")), - Remedy: fmt.Sprintf("Add two or three short follow-ups, %d to %d days apart. They should add a new angle rather than repeat the first email.", minFollowUpDays, maxFollowUpDays/2), - Evidence: map[string]any{ - "campaign": c.Name, - "email_steps": c.EmailStepCount, - "leads": c.LeadsTotal, - "recommended_steps": minRecommendedSteps, - }, - }) - } - return out -} - -func detectReplyRateLow(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, c := range runningCampaigns(s) { - if c.Sent < minSendsForEngagement { - continue - } - r := rate(c.Replied, c.Sent) - if r >= replyRateWeak { - continue - } - - severity := models.AdvisorMedium - if r < replyRateVeryLow { - severity = models.AdvisorHigh - } - - out = append(out, Finding{ - Key: "campaign_reply_rate_low", - GroupTitle: "{count} campaigns are getting almost no replies", - Category: models.AdvisorCategoryCampaign, - Severity: severity, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "campaign", - EntityID: ref(c.ID), - EntityLabel: c.Name, - Impact: clampImpact(40 + c.Sent/100), - Title: fmt.Sprintf("%s is getting almost no replies", c.Name), - Detail: fmt.Sprintf( - "%s has sent %d emails in the last 30 days and received %s, a reply rate of %s. At this sample size that is not variance: the offer, the audience, or the opening line is not landing, and sending more of it costs sender reputation without producing results.", - c.Name, c.Sent, plural(c.Replied, "reply", "replies"), pct(r)), - Remedy: "Pause and change one thing at a time. Narrow the audience first (it is usually the audience), then rewrite the first email around a single specific problem those companies actually have.", - Steps: []string{ - "Pause the campaign. Every further send at this rate costs reputation and teaches you nothing new.", - "Look at the audience first. It is the audience far more often than the copy: check that the contacts really are the people who have the problem you are selling to.", - "Narrow it. A list of 200 companies you can describe precisely outperforms 2,000 you cannot.", - "Then rewrite the first email around one specific problem those companies have, in the words they would use for it.", - "Change one thing at a time and restart at low volume. Changing audience and copy together tells you nothing about which one mattered.", - }, - Evidence: map[string]any{ - "campaign": c.Name, - "sends_30d": c.Sent, - "replies_30d": c.Replied, - "reply_rate_percent": band(r), - "bounced_30d": c.Bounced, - "leads": c.LeadsTotal, - "email_steps": c.EmailStepCount, - }, - }) - } - return out -} - -func detectStepDropoff(s *repository.AdvisorSnapshot) []Finding { - // Group steps by campaign so each is compared against its own siblings: - // absolute reply rates vary hugely by market, but within one campaign the - // steps all reach the same audience. - byCampaign := map[string][]repository.AdvisorStep{} - for _, st := range s.Steps { - if st.Kind != "email" || st.Sent < minStepSendsForDropoff { - continue - } - byCampaign[st.CampaignID.String()] = append(byCampaign[st.CampaignID.String()], st) - } - - names := map[string]string{} - for _, c := range s.Campaigns { - names[c.ID.String()] = c.Name - } - - out := []Finding{} - for cid, steps := range byCampaign { - if len(steps) < 2 { - continue - } - best := 0.0 - for _, st := range steps { - if r := rate(st.Replied, st.Sent); r > best { - best = r - } - } - if best <= 0 { - // No step replies at all: that is the campaign-level reply-rate - // finding's job, not a per-step comparison. - continue - } - - for _, st := range steps { - r := rate(st.Replied, st.Sent) - if r*stepDropoffFactor >= best { - continue - } - - label := st.Name - if label == "" { - label = fmt.Sprintf("Step %d", st.Position) - } - out = append(out, Finding{ - Key: "campaign_step_dropoff", - GroupTitle: "{count} sequence steps are far behind the rest of their campaign", - Category: models.AdvisorCategoryCampaign, - Severity: models.AdvisorMedium, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "step", - EntityID: ref(st.ID), - EntityLabel: fmt.Sprintf("%s / %s", names[cid], label), - ParentType: "campaign", - ParentID: ref(st.CampaignID), - Impact: clampImpact(30 + st.Sent/50), - Title: fmt.Sprintf("%s is the weak step in %s", label, names[cid]), - Detail: fmt.Sprintf( - "%s replies at %s across %d sends, against %s for the best step in the same campaign. Every step reaches the same audience, so a gap this wide is a problem with this message rather than the list.", - label, pct(r), st.Sent, pct(best)), - Remedy: "Rewrite this step. Follow-ups that only say \"just bumping this\" reliably land here; one that adds a new, specific reason to reply does not.", - Evidence: map[string]any{ - "campaign": names[cid], - "step": label, - "step_position": st.Position, - "step_sends": st.Sent, - "step_reply_rate_percent": band(r), - "best_step_rate_percent": band(best), - "subject": st.Subject, - }, - }) - } - } - return out -} - func detectUnsubscribeHeaderOff(s *repository.AdvisorSnapshot) []Finding { out := []Finding{} for _, camp := range s.Campaigns { @@ -309,54 +82,6 @@ func detectUnsubscribeHeaderOff(s *repository.AdvisorSnapshot) []Finding { return out } -func detectCapacityShortfall(s *repository.AdvisorSnapshot) []Finding { - // Safe capacity is the sum of the attached mailboxes' own caps, which is - // the platform's mailbox-first sending model: a campaign cannot be safer - // than the mailboxes carrying it. - out := []Finding{} - for _, camp := range runningCampaigns(s) { - if camp.SenderCount == 0 || camp.DailyLimit <= 0 { - continue - } - // SenderCapacity is the sum of THIS campaign's own senders' caps, which - // is what actually bounds it: the per-mailbox cap always wins over the - // campaign's daily limit. - capacity := camp.SenderCapacity - if capacity == 0 || camp.DailyLimit <= capacity { - continue - } - - out = append(out, Finding{ - Key: "campaign_capacity_shortfall", - GroupTitle: "{count} campaigns ask for more volume than their mailboxes can send", - Category: models.AdvisorCategoryCampaign, - Severity: models.AdvisorMedium, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "campaign", - EntityID: ref(camp.ID), - EntityLabel: camp.Name, - Impact: clampImpact(30 + (camp.DailyLimit-capacity)/5), - Title: fmt.Sprintf("%s asks for more volume than its mailboxes can send", camp.Name), - Detail: fmt.Sprintf( - "%s is set to send %d emails a day, but the mailboxes attached to it add up to %d a day at their own caps. The per-mailbox caps win, so the campaign will quietly deliver less than it reports.", - camp.Name, camp.DailyLimit, capacity), - Remedy: "Either lower the campaign's daily limit to match, or connect more mailboxes. Raising the per-mailbox caps to close the gap is the option that costs reputation.", - Evidence: map[string]any{ - "campaign": camp.Name, - "campaign_limit": camp.DailyLimit, - "mailbox_capacity": capacity, - "sender_count": camp.SenderCount, - }, - Action: auto(withUndo(campaignAction(camp.ID, - fmt.Sprintf("Match the campaign to %d/day", capacity), - map[string]any{"daily_limit": capacity}, - change("Campaign daily limit", fmt.Sprintf("%d/day", camp.DailyLimit), fmt.Sprintf("%d/day", capacity)), - ), map[string]any{"campaign_id": camp.ID.String(), "daily_limit": camp.DailyLimit})), - }) - } - return out -} - func detectNoSenders(s *repository.AdvisorSnapshot) []Finding { out := []Finding{} for _, camp := range runningCampaigns(s) { @@ -449,312 +174,3 @@ func noSenderCopyFor(camp repository.AdvisorCampaign) noSenderCopy { } } } - -func detectFollowUpSpacing(s *repository.AdvisorSnapshot) []Finding { - names := map[string]string{} - statuses := map[string]string{} - firstEmail := map[uuid.UUID]int{} - for _, camp := range s.Campaigns { - names[camp.ID.String()] = camp.Name - statuses[camp.ID.String()] = camp.Status - } - for _, st := range s.Steps { - if st.Kind != "email" { - continue - } - if position, ok := firstEmail[st.CampaignID]; !ok || st.Position < position { - firstEmail[st.CampaignID] = st.Position - } - } - - out := []Finding{} - for _, st := range s.Steps { - // The first email's wait is a start delay, not follow-up spacing. - if st.Kind != "email" || st.Position == firstEmail[st.CampaignID] { - continue - } - if statuses[st.CampaignID.String()] == "draft" { - continue - } - if st.WaitAfter >= minFollowUpDays && st.WaitAfter <= maxFollowUpDays { - continue - } - - label := st.Name - if label == "" { - label = fmt.Sprintf("Step %d", st.Position) - } - - var detail, remedy string - var want int - if st.WaitAfter < minFollowUpDays { - want = 3 - detail = fmt.Sprintf( - "%s in %s follows the previous email after %s. Follow-ups this close together read as pestering, and they drive unsubscribes and spam complaints rather than replies.", - label, names[st.CampaignID.String()], plural(st.WaitAfter, "day", "days")) - remedy = "Give it three or four days. Nothing is lost by waiting, and the follow-up lands as a reminder rather than a second demand." - } else { - want = 7 - detail = fmt.Sprintf( - "%s in %s waits %d days after the previous email. By then the recipient has no memory of the first message, so the follow-up has to reintroduce itself and loses the thread's context.", - label, names[st.CampaignID.String()], st.WaitAfter) - remedy = "Bring it back to about a week. Follow-ups work by being recognisably part of the same conversation." - } - - out = append(out, Finding{ - Key: "campaign_followup_spacing", - GroupTitle: "{count} follow-ups are badly spaced", - Category: models.AdvisorCategoryCampaign, - Severity: models.AdvisorLow, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "step", - EntityID: ref(st.ID), - EntityLabel: fmt.Sprintf("%s / %s", names[st.CampaignID.String()], label), - ParentType: "campaign", - ParentID: ref(st.CampaignID), - Impact: 15, - Title: fmt.Sprintf("%s follows too %s", label, map[bool]string{true: "soon", false: "late"}[st.WaitAfter < minFollowUpDays]), - Detail: detail, - Remedy: remedy, - Evidence: map[string]any{ - "campaign": names[st.CampaignID.String()], - "step": label, - "wait_days": st.WaitAfter, - "recommended": want, - "step_position": st.Position, - }, - Action: withUndo(toolAction("update_campaign_step", - fmt.Sprintf("Wait %d days instead", want), - map[string]any{ - "campaign_id": st.CampaignID.String(), - "step_id": st.ID.String(), - "wait_days": want, - }, - change("Wait before this step", plural(st.WaitAfter, "day", "days"), plural(want, "day", "days")), - ), map[string]any{ - "campaign_id": st.CampaignID.String(), - "step_id": st.ID.String(), - "wait_days": st.WaitAfter, - }), - }) - } - return out -} - -func detectListExhaustion(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, camp := range runningCampaigns(s) { - if camp.DailyLimit <= 0 || camp.LeadsRemaining <= 0 { - continue - } - daysLeft := int(math.Floor(float64(camp.LeadsRemaining) / float64(camp.DailyLimit))) - if daysLeft > listExhaustionDays { - continue - } - - out = append(out, Finding{ - Key: "campaign_list_exhaustion", - GroupTitle: "{count} campaigns are about to run out of leads", - Category: models.AdvisorCategoryCampaign, - Severity: models.AdvisorLow, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "campaign", - EntityID: ref(camp.ID), - EntityLabel: camp.Name, - Impact: clampImpact(25 + (listExhaustionDays-daysLeft)*3), - Title: fmt.Sprintf("%s is %s out of leads", camp.Name, whenExhausted(daysLeft)), - Detail: fmt.Sprintf( - "%s has %s left to reach at %d a day, so it is %s out. Campaigns do not announce that they have finished their list; they just stop producing results while still looking active.", - camp.Name, plural(camp.LeadsRemaining, "lead", "leads"), camp.DailyLimit, whenExhausted(daysLeft)), - Remedy: "Add more contacts now if the campaign is working, or let it finish and read the numbers before building the next list.", - Steps: []string{ - "Decide whether this campaign is working before you feed it. Check its reply rate on the campaign page.", - "If it is working, add contacts to the same list and they get picked up on the next scheduling pass. No restart needed.", - "If it is not, let it finish. Topping up a campaign that is not landing just spends more reputation on the same result.", - "Either way, build the next list while this one drains, so there is no gap where the mailboxes sit idle.", - }, - Evidence: map[string]any{ - "campaign": camp.Name, - "leads_remaining": camp.LeadsRemaining, - "leads_total": camp.LeadsTotal, - "daily_limit": camp.DailyLimit, - "days_remaining": daysLeft, - "replies_30d": camp.Replied, - }, - }) - } - return out -} - -// whenExhausted phrases the runway in words rather than rendering "about 0 -// days", which is the kind of arithmetic-shaped sentence nobody writes. -func whenExhausted(daysLeft int) string { - switch { - case daysLeft <= 0: - return "about to run" - case daysLeft == 1: - return "a day from running" - default: - return fmt.Sprintf("about %d days from running", daysLeft) - } -} - -func detectNoABTest(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, camp := range runningCampaigns(s) { - if camp.VariantCount >= 2 || camp.Sent < minSendsForEngagement*2 { - continue - } - - out = append(out, Finding{ - Key: "campaign_no_ab_test", - GroupTitle: "{count} high-volume campaigns are running one version of the copy", - Category: models.AdvisorCategoryCampaign, - Severity: models.AdvisorLow, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "campaign", - EntityID: ref(camp.ID), - EntityLabel: camp.Name, - Impact: clampImpact(20 + camp.Sent/200), - Title: fmt.Sprintf("%s is running one version of the copy", camp.Name), - Detail: fmt.Sprintf( - "%s has sent %d emails on a single variant. At this volume an A/B test costs nothing extra and is the only way to know whether the copy is what is holding the campaign back.", - camp.Name, camp.Sent), - Remedy: "Add a second variant that changes one thing: the subject line, or the opening sentence. Changing both at once tells you nothing about which mattered.", - Steps: []string{ - "Open the first email step and add a variant.", - "Change exactly one thing in it. The subject line is the usual first test, because it decides whether anything else gets read.", - "Leave everything else identical, including the call to action. Two variants that differ in three ways cannot tell you which one moved the number.", - "Let it run until each variant has a few hundred sends before reading the result.", - }, - Evidence: map[string]any{ - "campaign": camp.Name, - "sends_30d": camp.Sent, - "variants": camp.VariantCount, - "reply_rate_percent": band(rate(camp.Replied, camp.Sent)), - }, - }) - } - return out -} - -func detectNarrowWindow(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, camp := range runningCampaigns(s) { - if camp.DailyLimit <= 0 || camp.SenderCount == 0 { - continue - } - windowMinutes := minutesBetween(camp.StartTime, camp.EndTime) - if windowMinutes <= 0 { - continue - } - // Safe pacing: each mailbox holds its own minimum gap, so the campaign's - // achievable volume is (window / gap) per mailbox. - gap := defaultMinGap - for _, m := range s.Mailboxes { - if m.InActiveCampaign && m.MinWaitTime > 0 && m.MinWaitTime < gap { - gap = m.MinWaitTime - } - } - achievable := (windowMinutes * 60 / gap) * camp.SenderCount - if achievable <= 0 || camp.DailyLimit <= achievable { - continue - } - - out = append(out, Finding{ - Key: "campaign_narrow_window", - GroupTitle: "{count} campaigns cannot fit their daily volume into their sending window", - Category: models.AdvisorCategoryCampaign, - Severity: models.AdvisorMedium, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "campaign", - EntityID: ref(camp.ID), - EntityLabel: camp.Name, - Impact: clampImpact(25 + (camp.DailyLimit-achievable)/5), - Title: fmt.Sprintf("%s cannot fit its daily volume into its sending window", camp.Name), - Detail: fmt.Sprintf( - "%s wants %d emails a day but its %s window fits about %d at safe pacing across %s. The campaign will either underdeliver or compress its sends into a burst, and bursts are what filters notice.", - camp.Name, camp.DailyLimit, humanMinutes(windowMinutes), achievable, plural(camp.SenderCount, "mailbox", "mailboxes")), - Remedy: "Widen the sending window, add mailboxes, or lower the daily limit. Widening the window is free and changes nothing about how the mail looks.", - Evidence: map[string]any{ - "campaign": camp.Name, - "daily_limit": camp.DailyLimit, - "window": fmt.Sprintf("%s-%s", camp.StartTime, camp.EndTime), - "window_minutes": windowMinutes, - "achievable_sends": achievable, - "sender_count": camp.SenderCount, - "min_gap_seconds": gap, - }, - Action: auto(withUndo(campaignAction(camp.ID, - fmt.Sprintf("Set the daily limit to %d", achievable), - map[string]any{"daily_limit": achievable}, - change("Campaign daily limit", fmt.Sprintf("%d/day", camp.DailyLimit), fmt.Sprintf("%d/day", achievable)), - ), map[string]any{"campaign_id": camp.ID.String(), "daily_limit": camp.DailyLimit})), - }) - } - return out -} - -func detectDuplicateEnrollment(s *repository.AdvisorSnapshot) []Finding { - if s.Org.DuplicateContacts == 0 || s.Org.RunningCampaigns < 2 { - return nil - } - - severity := models.AdvisorLow - if s.Org.DuplicateContacts >= 100 { - severity = models.AdvisorMedium - } - - return []Finding{{ - Key: "campaign_duplicate_enrollment", - Category: models.AdvisorCategoryCampaign, - Severity: severity, - Surface: models.AdvisorSurfaceContacts, - Impact: clampImpact(20 + s.Org.DuplicateContacts/10), - Title: fmt.Sprintf("%s in more than one running campaign", plural(s.Org.DuplicateContacts, "contact is", "contacts are")), - Detail: fmt.Sprintf( - "%s enrolled in two or more of your %d running campaigns at once. To the recipient that is two unrelated strangers pitching in the same week, which is how a sender earns a complaint instead of a reply.", - plural(s.Org.DuplicateContacts, "contact is", "contacts are"), s.Org.RunningCampaigns), - Remedy: "Pick one campaign per contact. Deduplicate the overlapping lists, or split the audience by a field that keeps them apart.", - Steps: []string{ - "Open Contacts and find the contacts enrolled more than once.", - "Pick which campaign each one should be in. Usually the more specific campaign wins.", - "Remove them from the others. To the recipient, two of your campaigns is two unrelated strangers pitching in the same week.", - "Then stop it recurring: split the audiences on a field that keeps them apart, like industry or company size, rather than rebuilding overlapping lists by hand each time.", - }, - Evidence: map[string]any{ - "duplicate_contacts": s.Org.DuplicateContacts, - "running_campaigns": s.Org.RunningCampaigns, - }, - }} -} - -// minutesBetween parses two "HH:MM" strings into a window length in minutes, -// returning 0 for an unparseable or inverted window (which the campaign -// preflight already reports as an error). -func minutesBetween(start, end string) int { - s, ok1 := parseHHMM(start) - e, ok2 := parseHHMM(end) - if !ok1 || !ok2 || e <= s { - return 0 - } - return e - s -} - -func parseHHMM(v string) (int, bool) { - var h, m int - if _, err := fmt.Sscanf(v, "%d:%d", &h, &m); err != nil { - return 0, false - } - if h < 0 || h > 23 || m < 0 || m > 59 { - return 0, false - } - return h*60 + m, true -} - -func humanMinutes(mins int) string { - if mins%60 == 0 { - return plural(mins/60, "hour", "hour") - } - return fmt.Sprintf("%dh%02dm", mins/60, mins%60) -} diff --git a/internal/app/advisor/detect_copy.go b/internal/app/advisor/detect_copy.go index bdfcfdf3f..00a3be5d0 100644 --- a/internal/app/advisor/detect_copy.go +++ b/internal/app/advisor/detect_copy.go @@ -2,12 +2,13 @@ package advisor import ( "fmt" - "math" "regexp" "sort" "strings" + "unicode" + + "github.com/google/uuid" - "github.com/warmbly/warmbly/internal/app/copyjudge" "github.com/warmbly/warmbly/internal/models" "github.com/warmbly/warmbly/internal/repository" "github.com/warmbly/warmbly/internal/tasks" @@ -33,20 +34,6 @@ func copyDetectors() []Detector { Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns, repository.AdvisorSectionSteps}, Run: detectSpamPhrases, }, - { - Key: "copy_too_long", - Category: models.AdvisorCategoryCopy, - About: "Cold emails long enough that a busy recipient will not read them. Length is the most reliable predictor of a cold email being ignored on a phone, which is where most of them are opened.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns, repository.AdvisorSectionSteps}, - Run: detectCopyTooLong, - }, - { - Key: "copy_subject_too_long", - Category: models.AdvisorCategoryCopy, - About: "Subject lines long enough to be truncated in the inbox list, especially on mobile clients, so the part that would earn the open is never seen.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns, repository.AdvisorSectionSteps}, - Run: detectSubjectTooLong, - }, { Key: "copy_too_many_links", Category: models.AdvisorCategoryCopy, @@ -61,41 +48,94 @@ func copyDetectors() []Detector { Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns, repository.AdvisorSectionSteps}, Run: detectShoutySubject, }, - { - Key: "copy_reads_as_bulk", - Category: models.AdvisorCategoryCopy, - About: "An optional automated copy review, not a measurement of spam placement or reply likelihood. It flags tone only when a confident reader model agrees the message sounds promotional and lacks relevance to a specific reader or role. A business offer, reusable template or merge variable alone does not qualify. Explicit guarantees, free-money or prize promises and urgency are checked separately. Present this as a possible wording issue to review, never a fact about how recipients or spam filters will react. Only runs with TypeSafe configured.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns, repository.AdvisorSectionSteps}, - Run: detectReadsAsBulk, - }, - { - Key: "copy_no_clear_ask", - Category: models.AdvisorCategoryCopy, - About: "Copy that asks the reader for nothing, or for several things at once. A cold email earns a reply by making one small, specific request; with none there is nothing to answer, and with several the reader answers none. Judged by a calibrated reader model, and only when the operator has configured TypeSafe.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns, repository.AdvisorSectionSteps}, - Run: detectNoClearAsk, - }, } } var ( - // linkRe counts hyperlinks in either body form. - linkRe = regexp.MustCompile(`(?i)https?://[^\s"'<>)]+|]*href=`) + // urlRe finds web addresses in either body form. + urlRe = regexp.MustCompile(`(?i)https?://[^\s"'<>)]+`) + // srcAttrRe drops image and script sources, which load rather than link. + srcAttrRe = regexp.MustCompile(`(?i)\bsrc\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)`) // wordRe splits on whitespace for a word count that does not need to be // exact, only stable. wordRe = regexp.MustCompile(`\S+`) - // tagRe strips HTML so the length check measures prose, not markup. + // tagRe strips HTML so phrases are matched in prose, not markup. tagRe = regexp.MustCompile(`(?s)<[^>]*>`) // styleRe removes script/style blocks before stripping tags, so their // contents do not count as words. styleRe = regexp.MustCompile(`(?is)<(script|style)[^>]*>.*?`) ) +// sampleContact fills every built-in field, so copy is measured as a recipient +// reads it rather than as template source. +var sampleContact = models.Contact{ + FirstName: "Alex", + LastName: "Morgan", + Email: "alex@example.com", + Company: "Northwind", + Phone: "+1 555 0100", +} + +// copyView is a step as its recipient reads it. +type copyView struct { + // subject is empty for a step that replies under the conversation's subject. + subject string + // options is the body's text with every spintax option kept, for matching + // phrases any recipient may get. + options string + // links is the body's distinct web addresses. + links int +} + +func viewOf(st repository.AdvisorStep, threaded bool) copyView { + render := func(tmpl string) string { + return tasks.RenderTemplateWith(tmpl, sampleContact, tasks.TemplateContext{}) + } + plain, html := render(st.BodyPlain), render(st.BodyHTML) + body := plain + if strings.TrimSpace(body) == "" { + body = tagRe.ReplaceAllString(styleRe.ReplaceAllString(html, " "), " ") + } + linkSource := plain + if strings.TrimSpace(linkSource) == "" { + linkSource = srcAttrRe.ReplaceAllString(html, " ") + } + // A recipient gets one option of each group, so count the one carrying the most links. + linkSource = tasks.ResolveSpintax(linkSource, func(opts []string) string { + best := opts[0] + for _, o := range opts[1:] { + if distinctLinks(o) > distinctLinks(best) { + best = o + } + } + return best + }) + v := copyView{options: body, links: distinctLinks(linkSource)} + if !threaded { + v.subject = strings.TrimSpace(tasks.ShortestSpintax(render(st.Subject))) + } + return v +} + +// distinctLinks counts each address once: an HTML anchor names its target in +// href and often again as its text. +func distinctLinks(body string) int { + seen := map[string]bool{} + for _, u := range urlRe.FindAllString(body, -1) { + seen[strings.ToLower(strings.TrimRight(u, ".,;:!?"))] = true + } + return len(seen) +} + // stepContext pairs a step with its campaign for labelling. type stepContext struct { step repository.AdvisorStep campaign string status string + // first is the campaign's first email; threaded is whether the step + // replies under the conversation's subject. + first, threaded bool + view copyView } // emailSteps returns every email step in a non-draft campaign, with the @@ -110,15 +150,19 @@ func emailSteps(s *repository.AdvisorSnapshot) []stepContext { } out := []stepContext{} + opened := map[uuid.UUID]bool{} // campaigns whose conversation an earlier email opened for _, st := range s.Steps { if st.Kind != "email" { continue } + first := !opened[st.CampaignID] + threaded := st.ThreadReply && !first + opened[st.CampaignID] = true status := statuses[st.CampaignID.String()] if status == "draft" || status == "" { continue } - out = append(out, stepContext{step: st, campaign: names[st.CampaignID.String()], status: status}) + out = append(out, stepContext{step: st, campaign: names[st.CampaignID.String()], status: status, first: first, threaded: threaded, view: viewOf(st, threaded)}) } return out } @@ -132,16 +176,6 @@ func stepLabel(sc stepContext) string { return name } -// bodyText returns the step's prose: the plaintext body when present, -// otherwise the HTML body with markup stripped. -func bodyText(st repository.AdvisorStep) string { - if strings.TrimSpace(st.BodyPlain) != "" { - return st.BodyPlain - } - stripped := styleRe.ReplaceAllString(st.BodyHTML, " ") - return tagRe.ReplaceAllString(stripped, " ") -} - // detectBrokenTemplate asks the platform's own template validator whether the // copy parses, rather than pattern-matching for "suspicious" braces. Warmbly // bodies are Go templates: `{{if .Company}}`, `{{index . "city"}}`, and @@ -237,11 +271,11 @@ func templateErrorSummary(err error) string { func detectSpamPhrases(s *repository.AdvisorSnapshot) []Finding { out := []Finding{} for _, sc := range emailSteps(s) { - haystack := strings.ToLower(sc.step.Subject + " " + bodyText(sc.step)) + haystack := sc.view.subject + " " + sc.view.options hits := []string{} - for _, phrase := range spamTriggerPhrases { - if strings.Contains(haystack, phrase) { - hits = append(hits, phrase) + for _, p := range spamTriggerPatterns { + if p.re.MatchString(haystack) { + hits = append(hits, p.phrase) } } // One borderline phrase is not a finding. Two or more is a pattern. @@ -270,81 +304,7 @@ func detectSpamPhrases(s *repository.AdvisorSnapshot) []Finding { "campaign": sc.campaign, "step": stepLabel(sc), "phrases": hits, - "subject": sc.step.Subject, - }, - }) - } - return out -} - -func detectCopyTooLong(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, sc := range emailSteps(s) { - words := len(wordRe.FindAllString(bodyText(sc.step), -1)) - if words <= bodyTooLongWords { - continue - } - - out = append(out, Finding{ - Key: "copy_too_long", - GroupTitle: "{count} emails are too long to get read", - Category: models.AdvisorCategoryCopy, - Severity: models.AdvisorLow, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "step", - EntityID: ref(sc.step.ID), - EntityLabel: fmt.Sprintf("%s / %s", sc.campaign, stepLabel(sc)), - ParentType: "campaign", - ParentID: ref(sc.step.CampaignID), - Impact: clampImpact(15 + (words-bodyTooLongWords)/20), - Title: fmt.Sprintf("%s is %d words long", stepLabel(sc), words), - Detail: fmt.Sprintf( - "%s runs to %d words. Most cold email is opened on a phone, where anything past a screen and a half is scrolled past rather than read.", - stepLabel(sc), words), - Remedy: "Cut it to under 120 words: one line on why you are writing to this person specifically, one line on what you do, one question. Everything else belongs in the reply.", - Evidence: map[string]any{ - "campaign": sc.campaign, - "step": stepLabel(sc), - "word_count": words, - "recommended": 120, - "step_sends": sc.step.Sent, - }, - }) - } - return out -} - -func detectSubjectTooLong(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, sc := range emailSteps(s) { - subject := strings.TrimSpace(sc.step.Subject) - if len(subject) <= subjectTooLong { - continue - } - - out = append(out, Finding{ - Key: "copy_subject_too_long", - GroupTitle: "{count} subject lines get cut off in the inbox", - Category: models.AdvisorCategoryCopy, - Severity: models.AdvisorLow, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "step", - EntityID: ref(sc.step.ID), - EntityLabel: fmt.Sprintf("%s / %s", sc.campaign, stepLabel(sc)), - ParentType: "campaign", - ParentID: ref(sc.step.CampaignID), - Impact: clampImpact(15 + (len(subject)-subjectTooLong)/5), - Title: fmt.Sprintf("The subject line in %s gets cut off", stepLabel(sc)), - Detail: fmt.Sprintf( - "The subject is %d characters. Mobile inbox lists show roughly the first %d, so the part that would earn the open is never seen.", - len(subject), subjectTooLong-15), - Remedy: "Get it under 45 characters. Short, specific, and lowercase reads like a colleague; long and title-cased reads like a newsletter.", - Evidence: map[string]any{ - "campaign": sc.campaign, - "step": stepLabel(sc), - "subject": subject, - "length": len(subject), - "recommended": 45, + "subject": sc.view.subject, }, }) } @@ -356,17 +316,10 @@ func detectTooManyLinks(s *repository.AdvisorSnapshot) []Finding { for _, sc := range emailSteps(s) { // Only the first email matters here: a later step linking to a case // study is normal, a first touch with five links is not. - if sc.step.Position != 0 { + if !sc.first { continue } - // One representation only: the plain and HTML bodies carry the same - // links, so concatenating them double-counts every one and turns a - // two-link limit into a one-link limit. - body := sc.step.BodyPlain - if strings.TrimSpace(body) == "" { - body = sc.step.BodyHTML - } - links := len(linkRe.FindAllString(body, -1)) + links := sc.view.links if links <= maxLinksInBody { continue } @@ -402,18 +355,17 @@ func detectTooManyLinks(s *repository.AdvisorSnapshot) []Finding { func detectShoutySubject(s *repository.AdvisorSnapshot) []Finding { out := []Finding{} for _, sc := range emailSteps(s) { - subject := strings.TrimSpace(sc.step.Subject) + subject := sc.view.subject if subject == "" { continue } letters, upper := 0, 0 for _, r := range subject { - if r >= 'a' && r <= 'z' { + if unicode.IsLetter(r) { letters++ - } - if r >= 'A' && r <= 'Z' { - letters++ - upper++ + if unicode.IsUpper(r) { + upper++ + } } } shouting := letters >= 8 && float64(upper)/float64(letters) > 0.7 @@ -464,122 +416,3 @@ func joinQuoted(items []string) string { } return joinWords(quoted) } - -// judgmentFor returns the step's TypeSafe verdict, when the run judged it. -func judgmentFor(s *repository.AdvisorSnapshot, sc stepContext) (copyjudge.Verdict, bool) { - if s.CopyJudgments == nil { - return copyjudge.Verdict{}, false - } - v, ok := s.CopyJudgments[sc.step.ID] - return v, ok -} - -// round2 bands a probability for evidence, so the narrator and the card show -// "0.82" rather than a float's full tail. -func round2(v float64) float64 { - return math.Round(v*100) / 100 -} - -func detectReadsAsBulk(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, sc := range emailSteps(s) { - v, ok := judgmentFor(s, sc) - if !ok || !v.ReadsAsBulk() { - continue - } - - reason := "may sound promotional and lack a clear connection to the recipient or their role" - title := fmt.Sprintf("Review the tone of %s", stepLabel(sc)) - if v.SpamClaim >= copyjudge.SpamClaimAt { - reason = "may contain a guarantee, a free-money or prize promise, or pressure to act immediately" - title = fmt.Sprintf("Review the claims in %s", stepLabel(sc)) - } - - out = append(out, Finding{ - Key: "copy_reads_as_bulk", - GroupTitle: "{count} steps have wording to review", - Category: models.AdvisorCategoryCopy, - Severity: models.AdvisorLow, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "step", - EntityID: ref(sc.step.ID), - EntityLabel: fmt.Sprintf("%s / %s", sc.campaign, stepLabel(sc)), - ParentType: "campaign", - ParentID: ref(sc.step.CampaignID), - Impact: clampImpact(35 + int(v.ReadsAs*20) + sc.step.Sent/100), - Title: title, - Detail: fmt.Sprintf( - "An automated copy review suggests %s in %s %s. This is a wording assessment, not evidence that recipients will ignore it or that a spam filter will reject it.", - stepLabel(sc), sc.campaign, reason), - Remedy: "Check whether the email explains why the offer is relevant to this recipient, describes what you do plainly, and asks one small question. Edit any unsupported promises or artificial urgency. If the wording already fits, dismiss this suggestion.", - Steps: []string{ - fmt.Sprintf("Open the campaign and go to %s.", stepLabel(sc)), - "Read it aloud as if to the one person it is addressed to. Every line that would be strange to say to them is a line to cut.", - "Replace claims (guaranteed, free, act now, limited time) with what is true for this reader: what you noticed, why it is relevant to them.", - "Save any changes to refresh the review, or dismiss it if the assessment does not fit your message.", - }, - Evidence: map[string]any{ - "campaign": sc.campaign, - "step": stepLabel(sc), - "subject": sc.step.Subject, - "reads_as": round2(v.ReadsAs), - "personalization": round2(v.Personalization), - "spam_claim": round2(v.SpamClaim), - "confidence": round2(v.Confidence), - "step_sends": sc.step.Sent, - "content_hash": copyjudge.ContentHash(sc.step.Subject, copyjudge.Body(sc.step.BodyPlain, sc.step.BodyHTML)), - }, - }) - } - return out -} - -func detectNoClearAsk(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, sc := range emailSteps(s) { - v, ok := judgmentFor(s, sc) - if !ok || !v.LacksClearAsk() { - continue - } - - what := "asks the reader for nothing" - fix := "End with one small question the reader can answer in a line: whether this is worth a look, or who the right person is." - if v.Ask == copyjudge.AskSeveral { - what = "asks the reader for several things" - fix = "Keep one ask and move the rest to the reply. A reader with three requests answers none of them." - } - - out = append(out, Finding{ - Key: "copy_no_clear_ask", - GroupTitle: "{count} steps have no clear ask", - Category: models.AdvisorCategoryCopy, - Severity: models.AdvisorLow, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "step", - EntityID: ref(sc.step.ID), - EntityLabel: fmt.Sprintf("%s / %s", sc.campaign, stepLabel(sc)), - ParentType: "campaign", - ParentID: ref(sc.step.CampaignID), - Impact: clampImpact(20 + sc.step.Sent/100), - Title: fmt.Sprintf("%s %s", stepLabel(sc), what), - Detail: fmt.Sprintf( - "%s in %s %s. A cold email earns a reply by making one small, specific request; anything else leaves the reader nothing to answer.", - stepLabel(sc), sc.campaign, what), - Remedy: fix, - Steps: []string{ - fmt.Sprintf("Open the campaign and go to %s.", stepLabel(sc)), - "Decide the one thing you want back from this email: a yes or no, a name, a time.", - fix, - }, - Evidence: map[string]any{ - "campaign": sc.campaign, - "step": stepLabel(sc), - "subject": sc.step.Subject, - "ask": v.Ask, - "confidence": round2(v.Confidence), - "step_sends": sc.step.Sent, - }, - }) - } - return out -} diff --git a/internal/app/advisor/detect_deliverability.go b/internal/app/advisor/detect_deliverability.go index c0112a119..e062ca392 100644 --- a/internal/app/advisor/detect_deliverability.go +++ b/internal/app/advisor/detect_deliverability.go @@ -233,6 +233,10 @@ func detectDomainAuth(s *repository.AdvisorSnapshot) []Finding { if m.AuthState == "unknown" || m.AuthState == "" { continue } + // The DNS sweep only rechecks active mailboxes, so anything else holds a stale reading. + if m.Status != "active" { + continue + } if m.AuthSPF && m.AuthDMARC { continue } @@ -253,7 +257,7 @@ func detectDomainAuth(s *repository.AdvisorSnapshot) []Finding { // Unauthenticated mail that is actively going out is a live problem; // on an idle mailbox it is a setup task. severity := models.AdvisorMedium - if m.InActiveCampaign { + if m.SendingCold() { severity = models.AdvisorCritical if len(missing) == 1 && !m.AuthDMARC { // SPF present, DMARC missing: filtered less aggressively than @@ -296,7 +300,7 @@ func detectDomainAuth(s *repository.AdvisorSnapshot) []Finding { "dkim_verified": m.AuthDKIM, "dmarc": m.AuthDMARC, "dmarc_policy": m.AuthDMARCPolicy, - "currently_sending_cold": m.InActiveCampaign, + "currently_sending_cold": m.SendingCold(), "sending_blocked": blocked, }, }) @@ -325,7 +329,9 @@ func domainAuthGateNote(s *repository.AdvisorSnapshot, m repository.AdvisorMailb func detectSharedTrackingDomain(s *repository.AdvisorSnapshot) []Finding { out := []Finding{} for _, m := range s.Mailboxes { - if !m.InActiveCampaign { + // Nothing goes out on a tracking host unless a campaign tracks opens or + // links, and a campaign's own verified domain takes priority. + if !m.SendingCold() || !m.TrackedOnMailboxHost { continue } if m.TrackingDomain != "" && m.TrackingDomainVerified { diff --git a/internal/app/advisor/detect_list.go b/internal/app/advisor/detect_list.go index e5cdb9291..8cf0fc30f 100644 --- a/internal/app/advisor/detect_list.go +++ b/internal/app/advisor/detect_list.go @@ -3,6 +3,8 @@ package advisor import ( "fmt" + "github.com/google/uuid" + "github.com/warmbly/warmbly/internal/models" "github.com/warmbly/warmbly/internal/pkg/tmplvars" "github.com/warmbly/warmbly/internal/repository" @@ -20,20 +22,6 @@ func listDetectors() []Detector { Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns, repository.AdvisorSectionLists}, Run: detectRoleAddresses, }, - { - Key: "list_free_mail_heavy", - Category: models.AdvisorCategoryList, - About: "The share of a B2B campaign's audience on consumer mailbox domains. A cold list that is mostly consumer addresses is usually scraped rather than sourced, and both reply and complaint rates reflect that.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns, repository.AdvisorSectionLists}, - Run: detectFreeMailHeavy, - }, - { - Key: "list_suppressed_share", - Category: models.AdvisorCategoryList, - About: "Leads already on the organization's suppression list. They are skipped at send time, so a large share means the campaign delivers far less than its numbers suggest.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionCampaigns, repository.AdvisorSectionLists}, - Run: detectSuppressedShare, - }, { Key: "list_missing_personalization_data", Category: models.AdvisorCategoryList, @@ -112,100 +100,24 @@ func detectRoleAddresses(s *repository.AdvisorSnapshot) []Finding { return out } -func detectFreeMailHeavy(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, cl := range campaignsWithLists(s, 100) { - r := rate(cl.List.FreeMail, cl.List.Total) - if r < freeMailShareWarn { - continue - } - - out = append(out, Finding{ - Key: "list_free_mail_heavy", - GroupTitle: "{count} campaigns are mailing mostly consumer mailboxes", - Category: models.AdvisorCategoryList, - Severity: models.AdvisorLow, - Surface: models.AdvisorSurfaceContacts, - EntityType: "campaign", - EntityID: ref(cl.Campaign.ID), - EntityLabel: cl.Campaign.Name, - Impact: clampImpact(20 + int(r)/2), - Title: fmt.Sprintf("%s of %s is on consumer mailboxes", pct(r), cl.Campaign.Name), - Detail: fmt.Sprintf( - "%s of the contacts in %s are on gmail, outlook.com, yahoo and similar. For B2B outreach that usually means the list was scraped rather than sourced, and consumer providers are also the strictest filters you will face.", - pct(r), cl.Campaign.Name), - Remedy: "Check where this list came from. If the target is companies, the addresses should mostly be on company domains.", - Steps: []string{ - "Check where the list came from. A B2B list that is mostly consumer addresses was usually scraped rather than sourced.", - "Filter the consumer-domain contacts out and see what is left. If that is most of the list, the list is the problem, not the copy.", - "Rebuild from a source that gives you company addresses: an export from your CRM, a provider that verifies, or manual research on a smaller set.", - "Keep the consumer addresses out of cold campaigns. They reply less and complain more, and the complaints land on your sending domain.", - }, - Evidence: map[string]any{ - "campaign": cl.Campaign.Name, - "free_mail_contacts": cl.List.FreeMail, - "contacts": cl.List.Total, - "free_mail_share_percent": band(r), - }, - }) - } - return out -} - -func detectSuppressedShare(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, cl := range campaignsWithLists(s, 50) { - r := rate(cl.List.Suppressed, cl.List.Total) - if r < suppressedShareWarn { - continue - } - - out = append(out, Finding{ - Key: "list_suppressed_share", - GroupTitle: "{count} campaigns have a large share they will never send to", - Category: models.AdvisorCategoryList, - Severity: models.AdvisorMedium, - Surface: models.AdvisorSurfaceContacts, - EntityType: "campaign", - EntityID: ref(cl.Campaign.ID), - EntityLabel: cl.Campaign.Name, - Impact: clampImpact(25 + int(r)), - Title: fmt.Sprintf("%s of %s will never be sent to", pct(r), cl.Campaign.Name), - Detail: fmt.Sprintf( - "%s of the %s in %s are on your suppression list from a previous bounce, complaint, or unsubscribe. They are skipped at send time, so this campaign will reach far fewer people than its numbers suggest.", - plural(cl.List.Suppressed, "contact", "contacts"), plural(cl.List.Total, "contact", "contacts"), cl.Campaign.Name), - Remedy: "Clean the suppressed contacts out of the list so the campaign's reported audience matches what it can actually reach, and check where the list overlaps with ones you have already mailed.", - Evidence: map[string]any{ - "campaign": cl.Campaign.Name, - "suppressed": cl.List.Suppressed, - "contacts": cl.List.Total, - "suppressed_share_percent": band(r), - }, - }) - } - return out -} - func detectMissingPersonalizationData(s *repository.AdvisorSnapshot) []Finding { + // Only a step that prints the name with no fallback leaves a gap: a + // {{if .FirstName}} or a default covers the contacts without one. + gapped := map[uuid.UUID]bool{} + for _, sc := range emailSteps(s) { + parts := []string{sc.step.BodyPlain, sc.step.BodyHTML} + if !sc.threaded { + parts = append(parts, sc.step.Subject) + } + if printsBlankFirstName(parts...) { + gapped[sc.step.CampaignID] = true + } + } + out := []Finding{} for _, cl := range campaignsWithLists(s, 50) { r := rate(cl.List.MissingFirstName, cl.List.Total) - if r < missingNameShareWarn { - continue - } - - // Only worth reporting if the copy actually uses the field. - uses := false - for _, st := range s.Steps { - if st.CampaignID != cl.Campaign.ID { - continue - } - if usesFirstName(st.Subject, st.BodyPlain, st.BodyHTML) { - uses = true - break - } - } - if !uses { + if r < missingNameShareWarn || !gapped[cl.Campaign.ID] { continue } @@ -279,11 +191,16 @@ func detectUnsubscribedEnrolled(s *repository.AdvisorSnapshot) []Finding { return out } -// usesFirstName reports whether any part reads the contact's first name, in -// any spelling the renderer accepts (`.FirstName`, `first_name`, `firstName`). -func usesFirstName(parts ...string) bool { +// printsBlankFirstName reports whether any part prints the contact's first +// name where an empty one leaves a gap. A part that does not parse is sent by +// plain replacement, so any reference to the name counts. +func printsBlankFirstName(parts ...string) bool { for _, p := range parts { - if tmplvars.References(p)["FirstName"] { + gaps, ok := tmplvars.BlankGaps(p) + if !ok { + gaps = tmplvars.References(p) + } + if gaps["FirstName"] { return true } } diff --git a/internal/app/advisor/detect_mailbox.go b/internal/app/advisor/detect_mailbox.go index 48fa9e935..4f5511a51 100644 --- a/internal/app/advisor/detect_mailbox.go +++ b/internal/app/advisor/detect_mailbox.go @@ -36,19 +36,6 @@ func mailboxDetectors() []Detector { About: "Unresolved connection or send errors on a mailbox that campaigns still route through. A mailbox erroring silently drops volume from the campaigns depending on it.", Run: detectMailboxErrors, }, - { - Key: "mailbox_concentration", - Category: models.AdvisorCategoryMailbox, - About: "How many mailboxes carry the org's cold volume. Spreading sending across more mailboxes and more sending identities is the core safety property of the platform; concentrating it into one or two mailboxes gives up that protection.", - Reads: []repository.AdvisorSection{repository.AdvisorSectionOrg}, - Run: detectMailboxConcentration, - }, - { - Key: "mailbox_inactive_in_campaign", - Category: models.AdvisorCategoryMailbox, - About: "A mailbox that is inactive or erroring but still attached to a running campaign, so the campaign quietly sends less than it is configured to.", - Run: detectInactiveMailboxInCampaign, - }, } } @@ -65,17 +52,25 @@ func detectCapTooHigh(s *repository.AdvisorSnapshot) []Finding { complaintRate := rate(m.Complaints30d, m.ColdSent30d) proven := m.ColdSent30d >= minSendsForComplaintRate && bounceRate < bounceRateWarn && complaintRate < complaintRateWarn + if proven { + continue + } + // Unproven is not harm: it matters once the mailbox is bouncing or + // complaining, or actually sending above the band without a record. + struggling := m.ColdSent30d >= minSendsForBounceRate && (bounceRate >= bounceRateWarn || complaintRate >= complaintRateWarn) + if !m.SendingCold() || (!struggling && m.ColdSent1d <= safeColdCapBand) { + continue + } severity := models.AdvisorMedium detail := fmt.Sprintf( "%s is capped at %d cold emails a day, above the %d/day safe band. Volume above the default is meant to follow positive reputation signals, not lead them.", m.Email, m.CampaignLimit, safeColdCapBand) - if proven { - // Proven mailbox: this is a note, not an alarm. - severity = models.AdvisorLow + if struggling { + severity = models.AdvisorHigh detail = fmt.Sprintf( - "%s is capped at %d cold emails a day, above the %d/day safe band. Its bounce and complaint rates are clean over %d sends, so the volume is currently holding, but it leaves no headroom if the list quality slips.", - m.Email, m.CampaignLimit, safeColdCapBand, m.ColdSent30d) + "%s is capped at %d cold emails a day, above the %d/day safe band, while its bounce or complaint rate is already past the warning line. More volume from it spends reputation it is already losing.", + m.Email, m.CampaignLimit, safeColdCapBand) } out = append(out, Finding{ @@ -97,7 +92,7 @@ func detectCapTooHigh(s *repository.AdvisorSnapshot) []Finding { "safe_band": safeColdCapBand, "sends_30d": m.ColdSent30d, "bounce_rate_percent": band(bounceRate), - "proven": proven, + "struggling": struggling, }, Action: auto(withUndo(mailboxAction(m.ID, fmt.Sprintf("Set the cap to %d/day", defaultColdCap), @@ -112,10 +107,8 @@ func detectCapTooHigh(s *repository.AdvisorSnapshot) []Finding { func detectNewMailboxRampingFast(s *repository.AdvisorSnapshot) []Finding { out := []Finding{} for _, m := range s.Mailboxes { - if m.AgeDays >= newMailboxDays || !m.InActiveCampaign { - continue - } - if m.CampaignLimit <= newMailboxSafeCap { + // The cap alone is not volume: a warming mailbox is held to the graduation ramp below it. + if m.AgeDays >= newMailboxDays || !m.SendingCold() || m.CampaignLimit <= newMailboxSafeCap || m.ColdSent1d <= newMailboxSafeCap { continue } @@ -129,10 +122,10 @@ func detectNewMailboxRampingFast(s *repository.AdvisorSnapshot) []Finding { EntityID: ref(m.ID), EntityLabel: m.Email, Impact: clampImpact(70 - m.AgeDays), - Title: fmt.Sprintf("%s is sending at full volume after %s", m.Email, plural(m.AgeDays, "day", "days")), + Title: fmt.Sprintf("%s sent %d cold emails in a day after %s", m.Email, m.ColdSent1d, plural(m.AgeDays, "day", "days")), Detail: fmt.Sprintf( - "%s was connected %s ago and is already capped at %d cold emails a day. 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.CampaignLimit), + "%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, @@ -155,7 +148,7 @@ func detectNewMailboxRampingFast(s *repository.AdvisorSnapshot) []Finding { func detectGapTooShort(s *repository.AdvisorSnapshot) []Finding { out := []Finding{} for _, m := range s.Mailboxes { - if !m.InActiveCampaign || m.MinWaitTime >= minSafeGapSeconds { + if !m.SendingCold() || m.MinWaitTime >= minSafeGapSeconds { continue } @@ -197,7 +190,7 @@ func detectMailboxErrors(s *repository.AdvisorSnapshot) []Finding { continue } severity := models.AdvisorMedium - if m.InActiveCampaign { + if m.SendingCold() { severity = models.AdvisorHigh } @@ -215,7 +208,7 @@ func detectMailboxErrors(s *repository.AdvisorSnapshot) []Finding { Detail: fmt.Sprintf( "%s has %s from the last 7 days still unresolved%s. Send and sync errors do not surface as failures in campaign reporting, so a mailbox in this state quietly delivers less than the campaign asked for.", m.Email, plural(m.UnresolvedErrs, "error", "errors"), - map[bool]string{true: " while it is attached to a running campaign", false: ""}[m.InActiveCampaign]), + map[bool]string{true: " while it is attached to a running campaign", false: ""}[m.SendingCold()]), Remedy: "Open the mailbox and work through the errors. Authentication failures usually mean a reconnect; rate-limit errors mean the provider is pushing back and the cap should come down.", Steps: []string{ "Open the mailbox and read the errors. They are grouped by kind, and the kind tells you the fix.", @@ -227,7 +220,7 @@ func detectMailboxErrors(s *repository.AdvisorSnapshot) []Finding { Evidence: map[string]any{ "mailbox": m.Email, "unresolved_errors_7d": m.UnresolvedErrs, - "currently_sending_cold": m.InActiveCampaign, + "currently_sending_cold": m.SendingCold(), "status": m.Status, }, }) @@ -235,99 +228,6 @@ func detectMailboxErrors(s *repository.AdvisorSnapshot) []Finding { return out } -func detectMailboxConcentration(s *repository.AdvisorSnapshot) []Finding { - // Only meaningful once the org is actually sending at volume. - sending := 0 - totalVolume := 0 - for _, m := range s.Mailboxes { - if m.ColdSent7d > 0 { - sending++ - totalVolume += m.ColdSent7d - } - } - if s.Org.RunningCampaigns == 0 || totalVolume < minSendsForEngagement { - return nil - } - - // The planning heuristic in the sending policy: a mailbox at the default - // cap carries ~50/day, so weekly volume divided by the safe per-mailbox - // weekly total is how many mailboxes this volume really wants. - wantMailboxes := totalVolume / (defaultColdCap * 7) - if wantMailboxes < 1 { - wantMailboxes = 1 - } - if sending >= wantMailboxes { - return nil - } - - perMailbox := totalVolume / maxInt(sending, 1) / 7 - return []Finding{{ - Key: "mailbox_concentration", - Category: models.AdvisorCategoryMailbox, - Severity: models.AdvisorHigh, - Surface: models.AdvisorSurfaceMailboxes, - EntityType: "", - Impact: clampImpact(40 + (wantMailboxes-sending)*10), - Title: fmt.Sprintf("%s carrying all your cold volume", plural(sending, "mailbox is", "mailboxes are")), - Detail: fmt.Sprintf( - "You sent %d cold emails in the last week across %s, about %d per mailbox per day. Spreading volume across more mailboxes and more sending identities is the whole safety model here: concentrating it means one reputation problem takes out all of your sending at once.", - totalVolume, plural(sending, "mailbox", "mailboxes"), perMailbox), - Remedy: fmt.Sprintf("Connect more mailboxes and let the campaign rotate across them. At this volume you want around %s, each staying near the default cap.", plural(wantMailboxes, "mailbox", "mailboxes")), - Steps: []string{ - fmt.Sprintf("Connect more mailboxes until you have around %s carrying this volume.", plural(wantMailboxes, "mailbox", "mailboxes")), - "Spread them across more than one domain if you can. Several mailboxes on one domain still concentrate the risk on that domain's reputation.", - "Put each new mailbox through warmup before it takes campaign traffic, and start it at 10 to 20 a day.", - "Add them to the campaign, or give them the tag it selects senders by, and it starts rotating across them automatically.", - fmt.Sprintf("Bring the existing mailboxes back down to about %d/day as the new ones take the load.", defaultColdCap), - }, - Evidence: map[string]any{ - "sending_mailboxes": sending, - "cold_sends_7d": totalVolume, - "per_mailbox_per_day": perMailbox, - "recommended_mailboxes": wantMailboxes, - "safe_per_mailbox_cap": defaultColdCap, - }, - }} -} - -func detectInactiveMailboxInCampaign(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, m := range s.Mailboxes { - if !m.InActiveCampaign || m.Status == "active" { - continue - } - - out = append(out, Finding{ - Key: "mailbox_inactive_in_campaign", - GroupTitle: "{count} inactive mailboxes are attached to running campaigns", - Category: models.AdvisorCategoryMailbox, - Severity: models.AdvisorHigh, - Surface: models.AdvisorSurfaceCampaigns, - EntityType: "email_account", - EntityID: ref(m.ID), - EntityLabel: m.Email, - Impact: 60, - Title: fmt.Sprintf("%s is attached to a running campaign but is %s", m.Email, m.Status), - Detail: fmt.Sprintf( - "A running campaign routes through %s, but the mailbox is %s so nothing sends from it. The campaign is delivering less than it is configured to, and the shortfall does not show up as an error anywhere.", - m.Email, m.Status), - Remedy: "Either reactivate the mailbox or take it off the campaign, so the campaign's real capacity matches what it reports.", - Steps: []string{ - "Decide which you want: the mailbox sending again, or the campaign no longer counting on it.", - "To bring it back, open the mailbox and resolve whatever deactivated it, usually a reconnect, then set it active.", - "To let it go, open the campaign's sender settings and remove it, or take off the tag that selects it.", - "Either way the campaign's reported capacity starts matching what it can actually send, which is what makes its daily limit meaningful.", - }, - Evidence: map[string]any{ - "mailbox": m.Email, - "status": m.Status, - "unresolved_errors_7d": m.UnresolvedErrs, - }, - }) - } - return out -} - // humanSeconds renders a gap as minutes when it divides cleanly, which is how // the setting is presented in the dashboard. func humanSeconds(sec int) string { @@ -336,10 +236,3 @@ func humanSeconds(sec int) string { } return fmt.Sprintf("%d seconds", sec) } - -func maxInt(a, b int) int { - if a > b { - return a - } - return b -} diff --git a/internal/app/advisor/detect_test.go b/internal/app/advisor/detect_test.go index 0efcdb5bd..4b9dc7d91 100644 --- a/internal/app/advisor/detect_test.go +++ b/internal/app/advisor/detect_test.go @@ -1,7 +1,6 @@ package advisor import ( - "context" "encoding/json" "errors" "fmt" @@ -11,9 +10,7 @@ import ( "github.com/google/uuid" - "github.com/warmbly/warmbly/internal/app/copyjudge" "github.com/warmbly/warmbly/internal/models" - "github.com/warmbly/warmbly/internal/pkg/typesafe" "github.com/warmbly/warmbly/internal/repository" ) @@ -73,38 +70,6 @@ func findingsByKey(findings []Finding) map[string]Finding { return out } -func TestFollowUpSpacingExcludesTheFirstEmail(t *testing.T) { - for _, firstPosition := range []int{1, 3} { - t.Run(fmt.Sprintf("opener_at_%d", firstPosition), func(t *testing.T) { - campaignID, otherID := uuid.New(), uuid.New() - openerID, followupID := uuid.New(), uuid.New() - s := &repository.AdvisorSnapshot{ - Campaigns: []repository.AdvisorCampaign{ - {ID: campaignID, Name: "Outbound", Status: "active"}, - {ID: otherID, Name: "Other", Status: "active"}, - }, - Steps: []repository.AdvisorStep{ - {ID: followupID, CampaignID: campaignID, Kind: "email", Position: firstPosition + 1}, - {ID: uuid.New(), CampaignID: campaignID, Kind: "action", Position: firstPosition - 1}, - {ID: openerID, CampaignID: campaignID, Kind: "email", Position: firstPosition}, - {ID: uuid.New(), CampaignID: otherID, Kind: "email", Position: 7}, - }, - } - got := detectFollowUpSpacing(s) - if len(got) != 1 || got[0].EntityID == nil || *got[0].EntityID != followupID { - t.Fatalf("only the follow-up should need spacing: %+v", got) - } - if got[0].Evidence["step_position"] != firstPosition+1 { - t.Fatalf("step position must match the stored position: %+v", got[0].Evidence) - } - s.Steps[0].WaitAfter = 3 - if got := detectFollowUpSpacing(s); len(got) != 0 { - t.Fatalf("a three-day follow-up should need no spacing advice: %+v", got) - } - }) - } -} - func TestHealthyMailboxProducesNoFindings(t *testing.T) { got := Detect(snapshotOf(healthyMailbox()), defaults()) if len(got) != 0 { @@ -236,15 +201,19 @@ func TestUnverifiedDKIMIsNotNamedAsMissing(t *testing.T) { } } -func TestNewMailboxAtFullVolumeIsFlagged(t *testing.T) { +func TestNewMailboxIsFlaggedOnVolumeNotOnItsCap(t *testing.T) { m := healthyMailbox() m.AgeDays = 3 - m.ColdSent30d = 0 - m.ColdSent7d = 0 + m.ColdSent30d, m.ColdSent7d, m.ColdSent1d = 0, 0, 0 + if _, fired := findingsByKey(Detect(snapshotOf(m), defaults()))["mailbox_new_ramping_fast"]; fired { + t.Fatal("a new mailbox the graduation ramp is holding back is not sending at full volume") + } + + 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 three-day-old mailbox at the full default cap should be flagged") + t.Fatal("a three-day-old mailbox that sent 45 cold emails in a day should be flagged") } if f.Action == nil || f.Action.Undo == nil { t.Fatal("the ramp fix should be applyable and undoable") @@ -509,8 +478,8 @@ func TestFingerprintIsStablePerDetectorAndEntity(t *testing.T) { t.Error("two mailboxes with the same problem share a fingerprint") } - orgWide := Finding{Key: "mailbox_concentration"} - if orgWide.Fingerprint() != "mailbox_concentration|org" { + orgWide := Finding{Key: "org_check"} + if orgWide.Fingerprint() != "org_check|org" { t.Errorf("org-scoped fingerprint is %q", orgWide.Fingerprint()) } } @@ -774,14 +743,14 @@ func TestUnparseableHTMLBodyIsFlagged(t *testing.T) { } } -func TestMissingFirstNameOnlyFiresWhenTheCopyUsesIt(t *testing.T) { +func TestMissingFirstNameOnlyFiresWhenTheCopyLeavesAGap(t *testing.T) { campaignID := uuid.New() - build := func(body string) *repository.AdvisorSnapshot { + build := func(body string, followUps ...repository.AdvisorStep) *repository.AdvisorSnapshot { snap := snapshotOf() snap.Campaigns = []repository.AdvisorCampaign{{ID: campaignID, Name: "Outbound", Status: "active"}} - snap.Steps = []repository.AdvisorStep{{ + snap.Steps = append([]repository.AdvisorStep{{ ID: uuid.New(), CampaignID: campaignID, Kind: "email", Subject: "hello", BodyPlain: body, - }} + }}, followUps...) snap.Lists = map[uuid.UUID]repository.AdvisorListStats{ campaignID: {CampaignID: campaignID, Total: 200, MissingFirstName: 60}, } @@ -792,11 +761,27 @@ func TestMissingFirstNameOnlyFiresWhenTheCopyUsesIt(t *testing.T) { t.Error("missing-first-name fired on copy that never greets by name") } - for _, body := range []string{"Hi {{.FirstName}}, worth a chat?", "Hi {{first_name}}, worth a chat?", "Hi {{.firstName | default \"there\"}}"} { + for _, body := range []string{"Hi {{.FirstName}}, worth a chat?", "Hi {{first_name}}, worth a chat?", "Hi {{if .Company}}{{.FirstName}}{{end}}"} { if _, fired := findingsByKey(Detect(build(body), defaults()))["list_missing_personalization_data"]; !fired { - t.Errorf("missing-first-name did not fire on copy that greets by name: %q", body) + t.Errorf("missing-first-name did not fire on copy that prints a missing name: %q", body) } } + for _, body := range []string{ + "{{if .FirstName}}Bonjour {{.FirstName}},{{else}}Bonjour,{{end}}", + "Hi {{.firstName | default \"there\"}}", + "{{with .FirstName}}Hi {{.}},{{else}}Hi,{{end}}", + } { + if _, fired := findingsByKey(Detect(build(body), defaults()))["list_missing_personalization_data"]; fired { + t.Errorf("missing-first-name fired on copy with a fallback for the name: %q", body) + } + } + threaded := repository.AdvisorStep{ + ID: uuid.New(), CampaignID: campaignID, Kind: "email", Position: 1, ThreadReply: true, + Subject: "Quick one, {{.FirstName}}", BodyPlain: "Following up.", + } + if _, fired := findingsByKey(Detect(build("Hi there,", threaded), defaults()))["list_missing_personalization_data"]; fired { + t.Error("missing-first-name fired on the subject of a follow-up that is sent under the conversation's subject") + } if _, fired := findingsByKey(Detect(build("Update the firstname on file, or first_name in your CRM."), defaults()))["list_missing_personalization_data"]; fired { t.Error("missing-first-name fired on prose that only mentions the field") } @@ -823,7 +808,6 @@ func TestAutopilotOnlyGetsReversibleSafeFixes(t *testing.T) { "warmup_off": true, "warmup_paused": true, "warmup_ceiling_low": true, - "warmup_reply_rate_low": true, } autos := 0 @@ -982,279 +966,6 @@ func TestUnavailableCloudStandingDoesNotInventAReputationBan(t *testing.T) { } } -// judgedSnapshot is one active campaign with one email step, plus the verdict -// the copy judge would have attached to it. -func judgedSnapshot(v *copyjudge.Verdict) (*repository.AdvisorSnapshot, uuid.UUID) { - campaignID, stepID := uuid.New(), uuid.New() - snap := snapshotOf() - snap.Campaigns = []repository.AdvisorCampaign{{ID: campaignID, Name: "Outbound", Status: "active"}} - snap.Steps = []repository.AdvisorStep{{ - ID: stepID, CampaignID: campaignID, Kind: "email", Position: 1, - Name: "Opener", - Subject: "quick question", - BodyPlain: "Saw your talk on onboarding. Would a short note on how we cut it to a day be useful?", - }} - if v != nil { - snap.CopyJudgments = map[uuid.UUID]copyjudge.Verdict{stepID: *v} - } - return snap, stepID -} - -func TestJudgmentDetectorsAreSilentWithoutAVerdict(t *testing.T) { - // An install without TypeSafe, or a run where the judge was down, has no - // verdict for the step. That is "not judged", never "judged fine" or - // "judged bad". - snap, _ := judgedSnapshot(nil) - got := findingsByKey(Detect(snap, defaults())) - for _, key := range []string{"copy_reads_as_bulk", "copy_no_clear_ask"} { - if _, fired := got[key]; fired { - t.Errorf("%s fired on a step with no judgment", key) - } - } -} - -func TestPersonalCopyWithOneAskIsNotAFinding(t *testing.T) { - snap, _ := judgedSnapshot(©judge.Verdict{ - ReadsAs: 0, Personalization: 0, Ask: copyjudge.AskOneClear, SpamClaim: 0.05, Confidence: 0.95, - }) - got := findingsByKey(Detect(snap, defaults())) - for _, key := range []string{"copy_reads_as_bulk", "copy_no_clear_ask"} { - if _, fired := got[key]; fired { - t.Errorf("%s fired on a personal note with one clear ask", key) - } - } -} - -func TestReadsAsBulkFiresOnAConfidentBulkVerdict(t *testing.T) { - snap, stepID := judgedSnapshot(©judge.Verdict{ - ReadsAs: 1, Personalization: 1, Ask: copyjudge.AskOneClear, SpamClaim: 0.1, Confidence: 0.9, - }) - f, fired := findingsByKey(Detect(snap, defaults()))["copy_reads_as_bulk"] - if !fired { - t.Fatal("copy_reads_as_bulk did not fire on a confident bulk verdict") - } - if f.Severity != models.AdvisorLow { - t.Errorf("copy review should be low severity, got %s", f.Severity) - } - if f.EntityType != "step" || f.EntityID == nil || *f.EntityID != stepID || f.ParentType != "campaign" { - t.Error("finding is not attached to its step and campaign") - } - if f.Evidence["reads_as"] != 1.0 || f.Evidence["confidence"] != 0.9 { - t.Errorf("evidence does not carry the numbers it fired on: %v", f.Evidence) - } - if !strings.Contains(f.Title, "Opener") { - t.Errorf("title does not name the step: %q", f.Title) - } -} - -func TestReadsAsBulkNeedsConfidenceUnlessAClaimIsMade(t *testing.T) { - // The model put it at the bulk end but was not sure. An unsure verdict is - // not reproducible, and a finding that flickers between runs is worse - // than none. - snap, _ := judgedSnapshot(©judge.Verdict{ - ReadsAs: 1, Ask: copyjudge.AskOneClear, SpamClaim: 0.1, Confidence: 0.5, - }) - if _, fired := findingsByKey(Detect(snap, defaults()))["copy_reads_as_bulk"]; fired { - t.Error("copy_reads_as_bulk fired below the confidence floor") - } - - // A filter-baiting claim is its own probability and needs no floor. - snap, _ = judgedSnapshot(©judge.Verdict{ - ReadsAs: 0.2, Ask: copyjudge.AskOneClear, SpamClaim: 0.85, Confidence: 0.5, - }) - f, fired := findingsByKey(Detect(snap, defaults()))["copy_reads_as_bulk"] - if !fired { - t.Fatal("copy_reads_as_bulk did not fire on a spam claim") - } - if !strings.Contains(f.Detail, "may contain") || !strings.Contains(f.Detail, "not evidence") { - t.Errorf("detail should say the claim is the problem: %q", f.Detail) - } -} - -func TestCopyReviewRequiresAgreementAndTracksRewrites(t *testing.T) { - snap, id := judgedSnapshot(©judge.Verdict{ - ReadsAs: 1, Personalization: 0, Ask: copyjudge.AskOneClear, Confidence: 0.95, - }) - if got := detectReadsAsBulk(snap); len(got) != 0 { - t.Fatal("a message judged relevant should not get a bulk-tone suggestion") - } - v := snap.CopyJudgments[id] - v.Personalization = 1 - snap.CopyJudgments[id] = v - before := detectReadsAsBulk(snap)[0] - snap.Steps[0].BodyPlain = "A different email with the same review scores." - after := detectReadsAsBulk(snap)[0] - if before.Evidence["content_hash"] == after.Evidence["content_hash"] { - t.Fatal("rewritten copy must invalidate the old explanation even when scores match") - } -} - -func TestNoClearAskSaysWhichWay(t *testing.T) { - snap, _ := judgedSnapshot(©judge.Verdict{ReadsAs: 0, Ask: copyjudge.AskNone, Confidence: 0.9}) - f, fired := findingsByKey(Detect(snap, defaults()))["copy_no_clear_ask"] - if !fired { - t.Fatal("copy_no_clear_ask did not fire on no_ask") - } - if f.Severity != models.AdvisorLow { - t.Errorf("severity should be low, got %s", f.Severity) - } - if !strings.Contains(f.Title, "nothing") { - t.Errorf("title should say it asks for nothing: %q", f.Title) - } - - snap, _ = judgedSnapshot(©judge.Verdict{ReadsAs: 0, Ask: copyjudge.AskSeveral, Confidence: 0.9}) - f, fired = findingsByKey(Detect(snap, defaults()))["copy_no_clear_ask"] - if !fired { - t.Fatal("copy_no_clear_ask did not fire on several_asks") - } - if !strings.Contains(f.Title, "several") { - t.Errorf("title should say it asks for several things: %q", f.Title) - } - if f.Evidence["ask"] != copyjudge.AskSeveral { - t.Errorf("evidence should carry the ask: %v", f.Evidence) - } - - snap, _ = judgedSnapshot(©judge.Verdict{ReadsAs: 0, Ask: copyjudge.AskNone, Confidence: 0.3}) - if _, fired := findingsByKey(Detect(snap, defaults()))["copy_no_clear_ask"]; fired { - t.Error("copy_no_clear_ask fired below the confidence floor") - } -} - -// recordingJudge answers every step with one verdict and counts the calls. -type recordingJudge struct { - calls int - err error -} - -func (r *recordingJudge) Ask(_ context.Context, _ any, _ map[string]typesafe.Question) (*typesafe.Response, error) { - r.calls++ - if r.err != nil { - return nil, r.err - } - resp := &typesafe.Response{Model: typesafe.Model, Answers: map[string]typesafe.Answer{ - "reads_as": {Type: typesafe.QuestionScore, Score: 2, Confidence: 0.9}, - "personalization": {Type: typesafe.QuestionScore, Score: 1, Confidence: 0.9}, - "ask": {Type: typesafe.QuestionChoice, Choice: copyjudge.AskOneClear, Confidence: 0.9}, - "spam_claim": {Type: typesafe.QuestionNoul, Noul: 0.1}, - }} - return resp, nil -} - -type memoryJudgeCache struct { - rows map[string]copyjudge.Verdict - puts int -} - -func (m *memoryJudgeCache) Get(_ context.Context, orgID uuid.UUID, hash string) (*copyjudge.Verdict, error) { - v, ok := m.rows[orgID.String()+hash] - if !ok { - return nil, nil - } - return &v, nil -} - -func (m *memoryJudgeCache) Put(_ context.Context, orgID uuid.UUID, hash string, v *copyjudge.Verdict) error { - if m.rows == nil { - m.rows = map[string]copyjudge.Verdict{} - } - m.rows[orgID.String()+hash] = *v - m.puts++ - return nil -} - -func TestJudgeCopyReadsTheCacheBeforeAsking(t *testing.T) { - judge := &recordingJudge{} - cache := &memoryJudgeCache{} - s := NewService(nil, nil, nil, nil, nil, nil, WithCopyJudge(judge, cache)).(*service) - - snap, stepID := judgedSnapshot(nil) - s.judgeCopy(context.Background(), snap) - if judge.calls != 1 || cache.puts != 1 { - t.Fatalf("first run: %d calls, %d cache writes", judge.calls, cache.puts) - } - v, ok := snap.CopyJudgments[stepID] - if !ok || v.ReadsAs != 1 { - t.Fatalf("verdict not attached to the step: %v %v", ok, v) - } - - // Same copy again: the cache answers, the model is not asked. - snap2, _ := judgedSnapshot(nil) - snap2.OrganizationID = snap.OrganizationID - snap2.Steps[0].ID = stepID - s.judgeCopy(context.Background(), snap2) - if judge.calls != 1 { - t.Errorf("unchanged copy was judged again (%d calls)", judge.calls) - } - if _, ok := snap2.CopyJudgments[stepID]; !ok { - t.Error("cached verdict was not attached") - } - - // Drafts are never judged, so they never cost anything. - snap3, _ := judgedSnapshot(nil) - snap3.Campaigns[0].Status = "draft" - s.judgeCopy(context.Background(), snap3) - if judge.calls != 1 { - t.Error("a draft campaign's step was sent to the judge") - } -} - -type unavailableJudgeCache struct{ memoryJudgeCache } - -func (m *unavailableJudgeCache) Put(context.Context, uuid.UUID, string, *copyjudge.Verdict) error { - return errors.New("cache unavailable") -} - -func TestJudgeCopyReusesIdenticalCopyWhenCacheWriteFails(t *testing.T) { - judge := &recordingJudge{} - s := NewService(nil, nil, nil, nil, nil, nil, WithCopyJudge(judge, &unavailableJudgeCache{})).(*service) - snap, _ := judgedSnapshot(nil) - for i := 0; i < 50; i++ { - step := snap.Steps[0] - step.ID = uuid.New() - snap.Steps = append(snap.Steps, step) - } - s.judgeCopy(context.Background(), snap) - if judge.calls != 1 || len(snap.CopyJudgments) != 51 { - t.Fatalf("identical copy cost %d calls and produced %d verdicts", judge.calls, len(snap.CopyJudgments)) - } -} - -func TestJudgeCopyCapsFreshJudgmentsAndSurvivesErrors(t *testing.T) { - judge := &recordingJudge{} - cache := &memoryJudgeCache{} - s := NewService(nil, nil, nil, nil, nil, nil, WithCopyJudge(judge, cache)).(*service) - - snap, _ := judgedSnapshot(nil) - campaignID := snap.Campaigns[0].ID - for i := 0; i < maxCopyJudgmentsPerRun+10; i++ { - snap.Steps = append(snap.Steps, repository.AdvisorStep{ - ID: uuid.New(), CampaignID: campaignID, Kind: "email", Position: i + 1, - Subject: fmt.Sprintf("step %d", i), BodyPlain: fmt.Sprintf("body %d", i), - }) - } - s.judgeCopy(context.Background(), snap) - if judge.calls != maxCopyJudgmentsPerRun { - t.Errorf("expected the cap of %d fresh judgments, got %d", maxCopyJudgmentsPerRun, judge.calls) - } - if len(snap.CopyJudgments) != maxCopyJudgmentsPerRun { - t.Errorf("expected %d verdicts attached, got %d", maxCopyJudgmentsPerRun, len(snap.CopyJudgments)) - } - - // The judge being down leaves steps unjudged and the run intact. - down := NewService(nil, nil, nil, nil, nil, nil, WithCopyJudge(&recordingJudge{err: errors.New("529")}, &memoryJudgeCache{})).(*service) - snap, _ = judgedSnapshot(nil) - down.judgeCopy(context.Background(), snap) - if len(snap.CopyJudgments) != 0 { - t.Error("a failed judgment produced a verdict") - } - got := findingsByKey(Detect(snap, defaults())) - for _, key := range []string{"copy_reads_as_bulk", "copy_no_clear_ask"} { - if _, fired := got[key]; fired { - t.Errorf("%s fired on a step the judge never answered for", key) - } - } -} - // The no-senders finding names the way the campaign actually picks mailboxes, // so a campaign on "every active mailbox" is never sent to check its tags (#661). func TestNoSendersNamesHowTheCampaignPicksMailboxes(t *testing.T) { @@ -1362,7 +1073,7 @@ func busySnapshot() *repository.AdvisorSnapshot { { ID: uuid.New(), CampaignID: campaignID, Kind: "email", Position: 1, Name: "Opener", WaitAfter: 1, Subject: "ACT NOW!! LIMITED TIME OFFER, THIS IS NOT SPAM AND IT IS 100% FREE FOR YOU AND YOUR WHOLE TEAM TODAY", - BodyPlain: "Hi {{.FirstName}},\n\n{{if .Company}}Act now, click here, buy now, limited time, no obligation, 100% free, risk free. " + strings.Repeat("More words here. ", 200), + BodyPlain: "Hi {{.FirstName}},\n\n{{if .Company}}Act now, click here, buy now, limited time, no obligation, 100% free, risk free. https://a.example https://b.example https://c.example " + strings.Repeat("More words here. ", 200), Sent: 2000, Replied: 40, }, { @@ -1395,11 +1106,10 @@ func TestDetectorsDeclareEverySectionTheyRead(t *testing.T) { return strings.Join(out, ",") } base := busySnapshot() - fired := 0 for _, d := range AllDetectors() { full := d.Run(base) - if len(d.Reads) > 0 && len(full) > 0 { - fired++ + if len(d.Reads) > 0 && len(full) == 0 { + t.Errorf("detector %q reads a section but does not fire on the fixture, so this check cannot see it", d.Key) } for sec, clear := range blank { declared := false @@ -1416,9 +1126,6 @@ func TestDetectorsDeclareEverySectionTheyRead(t *testing.T) { } } } - if fired < 20 { - t.Errorf("the fixture fires only %d section-reading detectors; the check has no teeth", fired) - } } func TestFailedSectionHoldsItsDetectors(t *testing.T) { @@ -1454,3 +1161,97 @@ func TestFailedSectionHoldsItsDetectors(t *testing.T) { t.Errorf("a complete snapshot held %v", got) } } + +func TestCopyIsMeasuredAsTheRecipientReadsIt(t *testing.T) { + campaignID := uuid.New() + run := func(st repository.AdvisorStep) map[string]Finding { + snap := snapshotOf() + snap.Campaigns = []repository.AdvisorCampaign{{ID: campaignID, Name: "Outbound", Status: "active"}} + st.ID, st.CampaignID, st.Kind = uuid.New(), campaignID, "email" + snap.Steps = []repository.AdvisorStep{st} + return findingsByKey(Detect(snap, defaults())) + } + + got := run(repository.AdvisorStep{ + Subject: "{{if .Company}}Une question pour {{.Company}}{{else}}Une question rapide{{end}}, équipe", + BodyHTML: `

Voir https://example.com/a et ici.

`, + }) + for _, key := range []string{"copy_shouty_subject", "copy_too_many_links"} { + if _, fired := got[key]; fired { + t.Errorf("%s fired on template syntax or markup rather than on what is sent", key) + } + } + + spun := "{Book https://cal.example/x|Grab https://cal.example/x|Meet https://cal.example/x} or {see https://a.example/{one|two}|read https://a.example/one}." + if _, fired := run(repository.AdvisorStep{Subject: "hello", BodyPlain: spun})["copy_too_many_links"]; fired { + t.Error("spintax options naming the same address counted as several links") + } + if _, fired := run(repository.AdvisorStep{Subject: "hello", BodyPlain: "{https://a.example https://b.example https://c.example|thanks}"})["copy_too_many_links"]; !fired { + t.Error("an option some recipients get with three links was not flagged") + } + + if _, fired := run(repository.AdvisorStep{Subject: "hello", BodyPlain: "I will contact now and then. We are not insurgent."})["copy_spam_phrases"]; fired { + t.Error("spam phrases matched inside other words") + } + if _, fired := run(repository.AdvisorStep{Subject: "hello", BodyPlain: "It is guaranteed. Act now."})["copy_spam_phrases"]; !fired { + t.Error("spam phrases missed whole phrases") + } +} + +func TestMailboxFindingsOnlyClaimWhatIsHappening(t *testing.T) { + cases := []struct { + name, key string + state func(*repository.AdvisorMailbox, *repository.AdvisorSnapshot) + fires bool + }{ + {"untracked campaign", "mailbox_shared_tracking_domain", func(m *repository.AdvisorMailbox, _ *repository.AdvisorSnapshot) { + m.TrackingDomain = "" + }, false}, + {"tracked campaign", "mailbox_shared_tracking_domain", func(m *repository.AdvisorMailbox, _ *repository.AdvisorSnapshot) { + m.TrackingDomain, m.TrackedOnMailboxHost = "", true + }, true}, + {"disconnected mailbox's stale DNS", "mailbox_domain_auth", func(m *repository.AdvisorMailbox, _ *repository.AdvisorSnapshot) { + m.Status, m.AuthState, m.AuthDMARC = "inactive", models.AuthStateFailing, false + }, false}, + {"warmup off, plan cannot warm", "warmup_off_while_sending", func(m *repository.AdvisorMailbox, s *repository.AdvisorSnapshot) { + m.WarmupActive, s.WarmupUnavailable = false, true + }, false}, + {"warmup off, nothing sent", "warmup_off_while_sending", func(m *repository.AdvisorMailbox, _ *repository.AdvisorSnapshot) { + m.WarmupActive, m.ColdSent7d = false, 0 + }, false}, + {"warmup off while sending", "warmup_off_while_sending", func(m *repository.AdvisorMailbox, _ *repository.AdvisorSnapshot) { + m.WarmupActive = false + }, true}, + {"paused after the trial", "warmup_paused", func(m *repository.AdvisorMailbox, s *repository.AdvisorSnapshot) { + m.WarmupActive, m.WarmupPaused, s.WarmupUnavailable = false, true, true + }, false}, + {"paused on a mailbox sending nothing", "warmup_paused", func(m *repository.AdvisorMailbox, _ *repository.AdvisorSnapshot) { + m.WarmupActive, m.WarmupPaused, m.ColdSent7d = false, true, 0 + }, false}, + {"paused while sending cold", "warmup_paused", func(m *repository.AdvisorMailbox, _ *repository.AdvisorSnapshot) { + m.WarmupActive, m.WarmupPaused = false, true + }, true}, + {"high cap on a clean mailbox", "mailbox_cap_too_high", func(m *repository.AdvisorMailbox, _ *repository.AdvisorSnapshot) { + m.CampaignLimit, m.ColdSent1d = 120, 110 + }, false}, + {"high cap, new and sending under the band", "mailbox_cap_too_high", func(m *repository.AdvisorMailbox, _ *repository.AdvisorSnapshot) { + m.CampaignLimit, m.ColdSent30d, m.ColdSent1d = 120, 40, 30 + }, false}, + {"high cap, new and sending above the band", "mailbox_cap_too_high", func(m *repository.AdvisorMailbox, _ *repository.AdvisorSnapshot) { + m.CampaignLimit, m.ColdSent30d, m.ColdSent1d = 120, 80, 80 + }, true}, + {"high cap while complaining", "mailbox_cap_too_high", func(m *repository.AdvisorMailbox, _ *repository.AdvisorSnapshot) { + m.CampaignLimit, m.Complaints30d = 120, 5 + }, true}, + } + for _, tc := range cases { + m := healthyMailbox() + m.CampaignLimit = newMailboxSafeCap + s := snapshotOf() + tc.state(&m, s) + s.Mailboxes = []repository.AdvisorMailbox{m} + if _, fired := findingsByKey(Detect(s, defaults()))[tc.key]; fired != tc.fires { + t.Errorf("%s: %s fired=%v, want %v", tc.name, tc.key, fired, tc.fires) + } + } +} diff --git a/internal/app/advisor/detect_warmup.go b/internal/app/advisor/detect_warmup.go index 5ff37c9c8..b9102afdb 100644 --- a/internal/app/advisor/detect_warmup.go +++ b/internal/app/advisor/detect_warmup.go @@ -24,18 +24,6 @@ func warmupDetectors() []Detector { About: "Warmup left paused on a mailbox. Pausing is a deliberate, usually temporary action, and a pause nobody resumed removes the mailbox's positive signal without anyone noticing.", Run: detectWarmupPaused, }, - { - Key: "warmup_ceiling_too_low", - Category: models.AdvisorCategoryWarmup, - About: "A warmup ceiling far below the mailbox's cold cap. Warmup volume should be proportionate to cold volume, otherwise the positive signal is drowned out by the cold traffic it is supposed to balance.", - Run: detectWarmupCeilingTooLow, - }, - { - Key: "warmup_reply_rate_low", - Category: models.AdvisorCategoryWarmup, - About: "The share of warmup mail that gets replied to. Warmup works by looking like real correspondence; a low reply rate makes it one-way traffic, which is exactly the pattern it is supposed to counteract.", - Run: detectWarmupReplyRateLow, - }, { Key: "cloud_standing_unavailable", Category: models.AdvisorCategoryWarmup, @@ -106,7 +94,7 @@ func detectWarmupMailNotArriving(s *repository.AdvisorSnapshot) []Finding { func detectWarmupOffWhileSending(s *repository.AdvisorSnapshot) []Finding { out := []Finding{} for _, m := range s.Mailboxes { - if !m.InActiveCampaign || m.WarmupActive || m.WarmupPaused { + if !m.SendingCold() || m.ColdSent7d == 0 || m.WarmupActive || m.WarmupPaused || s.WarmupUnavailable { continue } @@ -151,13 +139,12 @@ func detectWarmupOffWhileSending(s *repository.AdvisorSnapshot) []Finding { func detectWarmupPaused(s *repository.AdvisorSnapshot) []Finding { out := []Finding{} for _, m := range s.Mailboxes { - if !m.WarmupPaused { + // 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 || s.WarmupUnavailable || !m.SendingCold() || m.ColdSent7d == 0 { continue } - severity := models.AdvisorMedium - if m.InActiveCampaign { - severity = models.AdvisorHigh - } + severity := models.AdvisorHigh out = append(out, Finding{ Key: "warmup_paused", @@ -173,11 +160,11 @@ func detectWarmupPaused(s *repository.AdvisorSnapshot) []Finding { Detail: fmt.Sprintf( "Warmup on %s is paused%s. Pausing keeps the ramp progress, so resuming picks up where it left off rather than starting over.", m.Email, - map[bool]string{true: " while the mailbox is running cold campaigns", false: ""}[m.InActiveCampaign]), + map[bool]string{true: " while the mailbox is running cold campaigns", false: ""}[m.SendingCold()]), Remedy: "Resume warmup unless you paused it deliberately for a reason that still applies.", Evidence: map[string]any{ "mailbox": m.Email, - "currently_sending_cold": m.InActiveCampaign, + "currently_sending_cold": m.SendingCold(), "cold_sends_7d": m.ColdSent7d, }, Action: withUndo(toolAction("set_mailbox_warmup", @@ -190,88 +177,6 @@ func detectWarmupPaused(s *repository.AdvisorSnapshot) []Finding { return out } -func detectWarmupCeilingTooLow(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, m := range s.Mailboxes { - if !m.WarmupActive || !m.InActiveCampaign { - continue - } - want := int(float64(m.CampaignLimit) * warmupCeilingFloorRatio) - if want < defaultWarmupBase { - want = defaultWarmupBase - } - if m.WarmupMax >= want { - continue - } - - out = append(out, Finding{ - Key: "warmup_ceiling_too_low", - GroupTitle: "Warmup is too small to balance cold volume on {count} mailboxes", - Category: models.AdvisorCategoryWarmup, - Severity: models.AdvisorMedium, - Surface: models.AdvisorSurfaceMailboxes, - EntityType: "email_account", - EntityID: ref(m.ID), - EntityLabel: m.Email, - Impact: clampImpact(25 + (want - m.WarmupMax)), - Title: fmt.Sprintf("Warmup on %s is too small to balance its cold volume", m.Email), - Detail: fmt.Sprintf( - "%s can send %d cold emails a day but tops out at %d warmup emails a day. Warmup is meant to be a meaningful share of what the mailbox sends, otherwise the positive signal is swamped by the cold traffic it is supposed to balance.", - m.Email, m.CampaignLimit, m.WarmupMax), - Remedy: fmt.Sprintf("Raise the warmup ceiling to about %d/day, roughly half the cold cap. The ramp still gets there gradually.", want), - Evidence: map[string]any{ - "mailbox": m.Email, - "warmup_ceiling": m.WarmupMax, - "cold_daily_cap": m.CampaignLimit, - "recommended_ceiling": want, - }, - Action: withUndo(mailboxAction(m.ID, - fmt.Sprintf("Raise the warmup ceiling to %d/day", want), - map[string]any{"warmup_max": want}, - change("Warmup ceiling", fmt.Sprintf("%d/day", m.WarmupMax), fmt.Sprintf("%d/day", want)), - ), map[string]any{"email_account_id": m.ID.String(), "warmup_max": m.WarmupMax}), - }) - } - return out -} - -func detectWarmupReplyRateLow(s *repository.AdvisorSnapshot) []Finding { - out := []Finding{} - for _, m := range s.Mailboxes { - if !m.WarmupActive || m.WarmupReplyRate >= minWarmupReplyRate { - continue - } - - out = append(out, Finding{ - Key: "warmup_reply_rate_low", - GroupTitle: "Warmup is nearly one-way on {count} mailboxes", - Category: models.AdvisorCategoryWarmup, - Severity: models.AdvisorLow, - Surface: models.AdvisorSurfaceMailboxes, - EntityType: "email_account", - EntityID: ref(m.ID), - EntityLabel: m.Email, - Impact: 20, - Title: fmt.Sprintf("Warmup on %s is nearly one-way", m.Email), - Detail: fmt.Sprintf( - "Only %d%% of warmup messages from %s get a reply. Warmup works because it looks like real correspondence; at this rate it is mostly one-way traffic, which is the pattern it is meant to counteract.", - m.WarmupReplyRate, m.Email), - Remedy: fmt.Sprintf("Raise the warmup reply rate to around %d%%, the platform default.", 30), - Evidence: map[string]any{ - "mailbox": m.Email, - "reply_rate_percent": m.WarmupReplyRate, - "recommended": 30, - }, - Action: withUndo(mailboxAction(m.ID, - "Raise the warmup reply rate to 30%", - map[string]any{"warmup_reply_rate": 30}, - change("Warmup reply rate", fmt.Sprintf("%d%%", m.WarmupReplyRate), "30%"), - ), map[string]any{"email_account_id": m.ID.String(), "warmup_reply_rate": m.WarmupReplyRate}), - }) - } - return out -} - func detectCloudStandingUnavailable(s *repository.AdvisorSnapshot) []Finding { out := []Finding{} for _, m := range s.Mailboxes { diff --git a/internal/app/advisor/fixer.go b/internal/app/advisor/fixer.go index cc18f62d5..ba835a476 100644 --- a/internal/app/advisor/fixer.go +++ b/internal/app/advisor/fixer.go @@ -66,32 +66,20 @@ const ( // as the honest answer that this one needs a person. // // The rule for being on this list: the fix is an edit to content the platform -// owns. Copy, sequence shape, and list membership qualify. DNS, provider +// owns. Copy and list membership qualify. DNS, provider // consoles, and anything needing a judgement call about volume do not, and // those show their manual steps instead. var agentFixable = map[string]bool{ // Copy: the text is ours to edit. - "copy_broken_template": true, - "copy_spam_phrases": true, - "copy_too_long": true, - "copy_subject_too_long": true, - "copy_shouty_subject": true, - "copy_too_many_links": true, - "copy_reads_as_bulk": true, - "copy_no_clear_ask": true, - - // Sequence shape: steps are ours to add and re-time. - "campaign_no_followups": true, - "campaign_followup_spacing": true, - "campaign_step_dropoff": true, - "campaign_capacity_shortfall": true, - "campaign_narrow_window": true, + "copy_broken_template": true, + "copy_spam_phrases": true, + "copy_shouty_subject": true, + "copy_too_many_links": true, // List membership: contacts are ours to filter and correct. "list_role_addresses": true, "list_missing_personalization_data": true, "list_unsubscribed_enrolled": true, - "list_suppressed_share": true, } // CanAgentFix reports whether the agent should be offered for a finding. The diff --git a/internal/app/advisor/judge_copy.go b/internal/app/advisor/judge_copy.go deleted file mode 100644 index b45068019..000000000 --- a/internal/app/advisor/judge_copy.go +++ /dev/null @@ -1,114 +0,0 @@ -package advisor - -import ( - "context" - "errors" - "log" - "time" - - "github.com/google/uuid" - - "github.com/warmbly/warmbly/internal/app/copyjudge" - "github.com/warmbly/warmbly/internal/pkg/typesafe" - "github.com/warmbly/warmbly/internal/repository" -) - -// maxCopyJudgmentsPerRun bounds how many fresh TypeSafe calls one evaluation -// may spend. Verdicts are cached by content hash, so this only bites on a -// workspace's first run or after a wave of rewrites, and the next run judges -// the rest. -const maxCopyJudgmentsPerRun = 40 - -// copyJudgeTimeout bounds one judgment. -const copyJudgeTimeout = 10 * time.Second - -// judgeCopy fills snapshot.CopyJudgments for every email step in a non-draft -// campaign, from the cache where it can and from TypeSafe where it must. It -// never fails the evaluation: a judge that is down leaves steps unjudged, and -// the detectors that read a verdict stay silent on those. -// -// It returns the steps that ended the run without a verdict (the cap, or a -// judge that is down), so Evaluate can keep their existing findings open -// rather than resolving them for lack of an answer. -func (s *service) judgeCopy(ctx context.Context, snapshot *repository.AdvisorSnapshot) []uuid.UUID { - if s.judge == nil || s.judgeCache == nil { - return nil - } - steps := emailSteps(snapshot) - if len(steps) == 0 { - return nil - } - verdicts := make(map[uuid.UUID]copyjudge.Verdict, len(steps)) - byContent := make(map[string]copyjudge.Verdict, len(steps)) - fresh := 0 - capped := false - for _, sc := range steps { - body := copyjudge.Body(sc.step.BodyPlain, sc.step.BodyHTML) - hash := copyjudge.ContentHash(sc.step.Subject, body) - if verdict, ok := byContent[hash]; ok { - verdicts[sc.step.ID] = verdict - continue - } - - cached, err := s.judgeCache.Get(ctx, snapshot.OrganizationID, hash) - if err != nil { - log.Printf("advisor: copy judgment cache read for org %s: %v", snapshot.OrganizationID, err) - } - if cached != nil { - byContent[hash] = *cached - verdicts[sc.step.ID] = *cached - continue - } - - if fresh >= maxCopyJudgmentsPerRun { - capped = true - continue - } - fresh++ - // Bounded per call, and the first failure ends the run's judging: - // Evaluate runs inside the refresh request, and a judge that is down - // must not be asked forty times. - jctx, cancel := context.WithTimeout(typesafe.WithUsage(ctx, "copy_judgment", snapshot.OrganizationID.String()), copyJudgeTimeout) - v, err := copyjudge.Judge(jctx, s.judge, sc.step.Subject, body) - cancel() - if err != nil { - log.Printf("advisor: copy judgment for step %s in org %s: %v", sc.step.ID, snapshot.OrganizationID, err) - if !errors.Is(err, copyjudge.ErrNoContent) { - break - } - continue - } - if err := s.judgeCache.Put(ctx, snapshot.OrganizationID, hash, v); err != nil { - log.Printf("advisor: copy judgment cache write for org %s: %v", snapshot.OrganizationID, err) - } - verdicts[sc.step.ID] = *v - byContent[hash] = *v - } - if capped { - log.Printf("advisor: copy judgment cap of %d reached for org %s; the rest are judged next run", maxCopyJudgmentsPerRun, snapshot.OrganizationID) - } - snapshot.CopyJudgments = verdicts - - var unjudged []uuid.UUID - for _, sc := range steps { - if _, ok := verdicts[sc.step.ID]; !ok { - unjudged = append(unjudged, sc.step.ID) - } - } - return unjudged -} - -// judgmentFindingKeys are the detectors that read a copy verdict. A step with -// no verdict this run keeps whichever of these it already had. -var judgmentFindingKeys = []string{"copy_reads_as_bulk", "copy_no_clear_ask"} - -// keepUnjudged is the fingerprints ResolveMissing must leave alone. -func keepUnjudged(steps []uuid.UUID) []string { - out := make([]string, 0, len(steps)*len(judgmentFindingKeys)) - for _, id := range steps { - for _, key := range judgmentFindingKeys { - out = append(out, key+"|step:"+id.String()) - } - } - return out -} diff --git a/internal/app/advisor/judge_copy_test.go b/internal/app/advisor/judge_copy_test.go deleted file mode 100644 index 034fa1a88..000000000 --- a/internal/app/advisor/judge_copy_test.go +++ /dev/null @@ -1,26 +0,0 @@ -package advisor - -import ( - "testing" - - "github.com/google/uuid" -) - -// The keep list has to spell fingerprints exactly as Finding.Fingerprint does, -// or ResolveMissing closes the findings it was meant to preserve. -func TestKeepUnjudgedMatchesFingerprints(t *testing.T) { - id := uuid.New() - want := map[string]bool{} - for _, key := range judgmentFindingKeys { - want[Finding{Key: key, EntityType: "step", EntityID: &id}.Fingerprint()] = true - } - for _, fp := range keepUnjudged([]uuid.UUID{id}) { - if !want[fp] { - t.Fatalf("keepUnjudged produced %q, which no judgment finding would carry", fp) - } - delete(want, fp) - } - if len(want) != 0 { - t.Fatalf("keepUnjudged missed %v", want) - } -} diff --git a/internal/app/advisor/service.go b/internal/app/advisor/service.go index c1cdffba9..8e4a38f59 100644 --- a/internal/app/advisor/service.go +++ b/internal/app/advisor/service.go @@ -13,7 +13,6 @@ import ( "github.com/warmbly/warmbly/internal/app/aitools" "github.com/warmbly/warmbly/internal/errx" "github.com/warmbly/warmbly/internal/models" - "github.com/warmbly/warmbly/internal/pkg/typesafe" "github.com/warmbly/warmbly/internal/repository" ) @@ -91,12 +90,8 @@ type service struct { // domainAuth resolves the sending-domain authentication gate, so the // domain-auth finding describes what actually happens on this install // rather than what happens on a default one. Optional/nil-safe. - domainAuth DomainAuthPolicy - - // The copy judge. Both optional together: without them the copy - // detectors that read a verdict never fire, and the regex ones still do. - judge typesafe.Asker - judgeCache repository.CopyJudgmentRepository + domainAuth DomainAuthPolicy + warmupAccess WarmupAccess } // DomainAuthPolicy resolves whether the sending-domain authentication gate is @@ -145,16 +140,14 @@ func WithDomainAuthPolicy(p DomainAuthPolicy) Option { return func(s *service) { s.domainAuth = p } } -// WithCopyJudge supplies the TypeSafe client and the verdict cache that let -// the copy detectors read how a step's copy lands with its reader. A nil asker -// leaves the option inert, so the caller can pass whatever it has. -func WithCopyJudge(asker typesafe.Asker, cache repository.CopyJudgmentRepository) Option { - return func(s *service) { - if asker == nil || cache == nil { - return - } - s.judge, s.judgeCache = asker, cache - } +// WarmupAccess answers whether an organization's plan includes warmup. +type WarmupAccess interface { + CanUseWarmup(ctx context.Context, orgID uuid.UUID) (bool, *errx.Error) +} + +// WithWarmupAccess lets the warmup findings stay quiet when the plan cannot warm. +func WithWarmupAccess(a WarmupAccess) Option { + return func(s *service) { s.warmupAccess = a } } // maxNarrationsPerRun bounds how many completions one evaluation can spend. @@ -196,12 +189,14 @@ func (s *service) Evaluate(ctx context.Context, orgID uuid.UUID, trigger string) if s.domainAuth != nil { snapshot.DomainAuthEnforced, snapshot.DomainAuthGrace = s.domainAuth.DomainAuth(ctx) } - unjudged := s.judgeCopy(ctx, snapshot) + if s.warmupAccess != nil { + if ok, xerr := s.warmupAccess.CanUseWarmup(ctx, orgID); xerr == nil { + snapshot.WarmupUnavailable = !ok + } + } findings := Detect(snapshot, settings) - // A step the judge did not reach this run is not a step whose copy got - // better; its judgment findings stay open until it is read again. - keep := keepUnjudged(unjudged) + keep := []string{} stored := make([]*models.AdvisorFinding, 0, len(findings)) newCount := 0 for _, f := range findings { diff --git a/internal/app/advisor/thresholds.go b/internal/app/advisor/thresholds.go index b08e61cd1..d991177a1 100644 --- a/internal/app/advisor/thresholds.go +++ b/internal/app/advisor/thresholds.go @@ -1,5 +1,7 @@ package advisor +import "regexp" + // Thresholds. Every value here traces to the sending-safety and paid-pool // policy in CLAUDE.md, or to the provider guidance that policy cites. They are // deliberately stricter than the point where mailbox providers start @@ -19,11 +21,6 @@ const ( // minWarmupDeliveriesForPlacement mirrors the documented spam-placement // floor: at least 20 warmup deliveries in the last 7 days. minWarmupDeliveriesForPlacement = 20 - // minSendsForEngagement is the floor for reply/open-rate advice. Copy - // feedback on 30 sends is superstition. - minSendsForEngagement = 200 - // minStepSendsForDropoff is the per-step floor for follow-up advice. - minStepSendsForDropoff = 100 // --- deliverability bands --------------------------------------------- // Google: keep user-reported spam below 0.10%, never reach 0.30%. @@ -58,46 +55,15 @@ const ( // --- warmup ------------------------------------------------------------ // Repo defaults: base 10/day, ceiling 40/day, +1/day ramp, 30% reply rate. - defaultWarmupBase = 10 - defaultWarmupMax = 40 - minWarmupBase = 5 - minWarmupReplyRate = 20 - // warmupCeilingFloorRatio is the share of a mailbox's cold cap that its - // warmup ceiling should at least match. A mailbox sending 50 cold/day on a - // 10/day warmup ceiling has almost no positive signal to offset the cold - // traffic. - warmupCeilingFloorRatio = 0.5 - - // --- campaign performance --------------------------------------------- - // Cold outreach reply rates below this, at volume, mean the offer or the - // list is wrong; more sending will not fix it and will cost reputation. - replyRateWeak = 1.0 - replyRateVeryLow = 0.3 - // stepDropoffFactor: a follow-up step whose reply rate is this many times - // worse than the campaign's best step is worth rewriting. - stepDropoffFactor = 4.0 - - // --- sequence shape ---------------------------------------------------- - // A single-email cold campaign leaves most of its replies unclaimed. - minRecommendedSteps = 3 - // Follow-ups closer together than this read as pestering. - minFollowUpDays = 2 - // And further apart than this lose the thread entirely. - maxFollowUpDays = 14 + defaultWarmupBase = 10 + defaultWarmupMax = 40 // --- list hygiene ------------------------------------------------------ roleAddressShareWarn = 15.0 - freeMailShareWarn = 40.0 - suppressedShareWarn = 10.0 missingNameShareWarn = 10.0 - // listExhaustionDays: a running campaign with fewer than this many days of - // leads left needs more list before it silently goes quiet. - listExhaustionDays = 7 // --- copy -------------------------------------------------------------- - subjectTooLong = 60 - bodyTooLongWords = 200 - maxLinksInBody = 2 + maxLinksInBody = 2 ) // spamTriggerPhrases are the phrases that most reliably move cold B2B mail into @@ -128,3 +94,18 @@ var spamTriggerPhrases = []string{ "100% free", "$$$", } + +type spamPattern struct { + phrase string + re *regexp.Regexp +} + +// spamTriggerPatterns match each phrase at the start of a word, so "act now" +// is not found inside "contact now" while "guarantee" still finds "guaranteed". +var spamTriggerPatterns = func() []spamPattern { + out := make([]spamPattern, 0, len(spamTriggerPhrases)) + for _, p := range spamTriggerPhrases { + out = append(out, spamPattern{p, regexp.MustCompile(`(?i)(?:^|[^\pL\pN])` + regexp.QuoteMeta(p))}) + } + return out +}() diff --git a/internal/app/orgtransfer/spec.go b/internal/app/orgtransfer/spec.go index 7548de1ec..7180a4955 100644 --- a/internal/app/orgtransfer/spec.go +++ b/internal/app/orgtransfer/spec.go @@ -1186,7 +1186,7 @@ var ExcludedTables = map[string]string{ "cloud_link_reports": "Retired command results and observations once owed to Warmbly Cloud over this instance's link, which does not travel.", "cloud_link_warmup_messages": "Retired handles this instance gave Warmbly Cloud for warmup mail, bound to its link and to provider coordinates on this instance.", "warmup_conversations": "The instance's shared warmup content library, not workspace data.", - "copy_judgments": "A cache of copy judgments keyed by the hash of the words judged. The destination re-reads a step the first time its Advisor runs.", + "copy_judgments": "A cache of copy judgments keyed by the hash of the words judged, no longer written; nothing reads it.", "warmup_thread_messages": "Message identifiers this instance recognised as turns of a warmup conversation, so the reply to each is recognised too. The destination syncs provider mail afresh and rebuilds it from the warmup tokens, which do travel.", "sessions": "Live login sessions. They are bound to the source instance's signing key and must not survive a move.", "mailbox_erasures": "Erasure still owed for a mailbox this instance deleted: a grant to revoke at the provider, and message bodies to remove from this instance's blob store. Both name work on the instance that wrote the row, and the mailboxes are already gone.", diff --git a/internal/pkg/tmplvars/gaps.go b/internal/pkg/tmplvars/gaps.go new file mode 100644 index 000000000..fb6063e2d --- /dev/null +++ b/internal/pkg/tmplvars/gaps.go @@ -0,0 +1,287 @@ +package tmplvars + +import ( + "maps" + "sort" + "strings" + "text/template/parse" +) + +// BlankGaps reports the built-in contact fields src prints with nothing to +// fall back on, so an empty value leaves a hole: outside an {{if}} or {{with}} +// that tests the field, and not through default or or. ok is false when src +// does not parse. +func BlankGaps(src string) (gaps map[string]bool, ok bool) { + if !strings.Contains(src, "{{") { + return map[string]bool{}, true + } + norm, err := Normalize(maskMarkers(src)) + if err != nil { + return nil, false + } + tree := parse.New("gaps") + tree.Mode = parse.SkipFuncCheck + trees := map[string]*parse.Tree{} + if _, err := tree.Parse(norm, "", "", trees); err != nil { + return nil, false + } + g := gapWalker{gaps: map[string]bool{}} + names := make([]string, 0, len(trees)) + for name := range trees { + names = append(names, name) + } + sort.Strings(names) + for _, name := range names { + if t := trees[name]; t != nil && t.Root != nil { + root := operand{root: true} + g.node(t.Root, &frame{dot: root, vars: map[string]operand{"$": root}, safe: map[string]bool{}}) + } + } + return g.gaps, true +} + +// operand is what a value holds as far as the gap walk can tell: the template +// data itself, the bare text of one built-in field, or something else. +type operand struct { + root bool + field string +} + +// frame is the walk's state at one point: what dot and each variable hold, +// and which fields are known not to be empty there. +type frame struct { + dot operand + vars map[string]operand + safe map[string]bool +} + +func (f *frame) with(dot operand, safe map[string]bool) *frame { + merged := maps.Clone(f.safe) + for k := range safe { + merged[k] = true + } + return &frame{dot: dot, vars: maps.Clone(f.vars), safe: merged} +} + +type gapWalker struct{ gaps map[string]bool } + +// passThrough are the functions whose output is empty when their input is, so +// printing one of them over a blank field still leaves a hole. +var passThrough = map[string]bool{ + "lower": true, "upper": true, "trim": true, "title": true, "and": true, + "print": true, "printf": true, "println": true, "html": true, "js": true, "urlquery": true, +} + +func (g *gapWalker) node(n parse.Node, f *frame) { + switch x := n.(type) { + case *parse.ListNode: + if x == nil { + return + } + for _, c := range x.Nodes { + g.node(c, f) + } + case *parse.ActionNode: + if len(x.Pipe.Decl) > 0 { + g.declare(x.Pipe, f) + return + } + for field := range g.printed(x.Pipe, f) { + if !f.safe[field] { + g.gaps[field] = true + } + } + case *parse.IfNode: + whenTrue, whenFalse := g.cond(x.Pipe, f) + body := f.with(f.dot, whenTrue) + g.declare(x.Pipe, body) + g.node(x.List, body) + g.node(x.ElseList, f.with(f.dot, whenFalse)) + case *parse.WithNode: + whenTrue, whenFalse := g.cond(x.Pipe, f) + body := f.with(g.value(x.Pipe, f), whenTrue) + g.declare(x.Pipe, body) + g.node(x.List, body) + g.node(x.ElseList, f.with(f.dot, whenFalse)) + case *parse.RangeNode: + body := f.with(operand{}, nil) + for _, v := range x.Pipe.Decl { + body.vars[v.Ident[0]] = operand{} + } + g.node(x.List, body) + g.node(x.ElseList, f.with(f.dot, nil)) + } +} + +// declare binds the variables a pipeline declares or assigns to its value. +func (g *gapWalker) declare(p *parse.PipeNode, f *frame) { + if p == nil { + return + } + v := g.value(p, f) + for _, d := range p.Decl { + f.vars[d.Ident[0]] = v + } +} + +// value is what a pipeline of one operand holds. +func (g *gapWalker) value(p *parse.PipeNode, f *frame) operand { + if p == nil || len(p.Cmds) != 1 || len(p.Cmds[0].Args) != 1 { + return operand{} + } + return g.operandOf(p.Cmds[0].Args[0], f) +} + +func (g *gapWalker) operandOf(n parse.Node, f *frame) operand { + switch x := n.(type) { + case *parse.DotNode: + return f.dot + case *parse.PipeNode: + return g.value(x, f) + case *parse.FieldNode: + if f.dot.root && len(x.Ident) == 1 { + return builtinField(x.Ident[0]) + } + case *parse.VariableNode: + held := f.vars[x.Ident[0]] + if len(x.Ident) == 1 { + return held + } + if held.root && len(x.Ident) == 2 { + return builtinField(x.Ident[1]) + } + } + return operand{} +} + +// builtinField is the operand for a top-level name: a built-in text field, or nothing. +func builtinField(name string) operand { + canonical, ok := topNames[name] + if !ok || canonical == SenderField || canonical == UnsubscribeLink { + return operand{} + } + return operand{field: canonical} +} + +// printed is the set of fields whose emptiness reaches the pipeline's output. +func (g *gapWalker) printed(p *parse.PipeNode, f *frame) map[string]bool { + var cur map[string]bool + for _, cmd := range p.Cmds { + cur = g.command(cmd, cur, f) + } + return cur +} + +func (g *gapWalker) command(cmd *parse.CommandNode, piped map[string]bool, f *frame) map[string]bool { + if len(cmd.Args) == 0 { + return nil + } + head, isFunc := cmd.Args[0].(*parse.IdentifierNode) + if !isFunc { + if p, ok := cmd.Args[0].(*parse.PipeNode); ok && len(cmd.Args) == 1 { + return g.printed(p, f) + } + if v := g.operandOf(cmd.Args[0], f); v.field != "" { + return map[string]bool{v.field: true} + } + return nil + } + if !passThrough[head.Ident] { + return nil // default, or, comparisons and the rest never print a blank field as-is + } + out := maps.Clone(piped) + if out == nil { + out = map[string]bool{} + } + for _, arg := range cmd.Args[1:] { + if p, ok := arg.(*parse.PipeNode); ok { + maps.Copy(out, g.printed(p, f)) + } else if v := g.operandOf(arg, f); v.field != "" { + out[v.field] = true + } + } + return out +} + +// cond is the set of fields known not to be empty when the condition holds, +// and when it does not. +func (g *gapWalker) cond(p *parse.PipeNode, f *frame) (whenTrue, whenFalse map[string]bool) { + if p == nil || len(p.Cmds) == 0 { + return nil, nil + } + cmd := p.Cmds[0] + if len(p.Cmds) > 1 { + // {{if .FirstName | trim}}: the head decides whether there is anything to test. + if v := g.value(&parse.PipeNode{Cmds: []*parse.CommandNode{cmd}}, f); v.field != "" { + return map[string]bool{v.field: true}, nil + } + return nil, nil + } + return g.condCmd(cmd, f) +} + +func (g *gapWalker) condCmd(cmd *parse.CommandNode, f *frame) (whenTrue, whenFalse map[string]bool) { + head, isFunc := cmd.Args[0].(*parse.IdentifierNode) + if !isFunc { + if len(cmd.Args) == 1 { + return g.condArg(cmd.Args[0], f) + } + return nil, nil + } + args := cmd.Args[1:] + switch head.Ident { + case "not": + if len(args) == 1 { + t, fl := g.condArg(args[0], f) + return fl, t + } + case "and": + whenTrue = map[string]bool{} + for _, a := range args { + t, _ := g.condArg(a, f) + maps.Copy(whenTrue, t) + } + return whenTrue, nil + case "or": + whenFalse = map[string]bool{} + for _, a := range args { + _, fl := g.condArg(a, f) + maps.Copy(whenFalse, fl) + } + return nil, whenFalse + case "ne", "eq": + if len(args) == 2 { + field := g.comparedToEmpty(args[0], args[1], f) + if field == "" { + field = g.comparedToEmpty(args[1], args[0], f) + } + if field != "" { + set := map[string]bool{field: true} + if head.Ident == "ne" { + return set, nil + } + return nil, set + } + } + } + return nil, nil +} + +func (g *gapWalker) condArg(n parse.Node, f *frame) (whenTrue, whenFalse map[string]bool) { + if p, ok := n.(*parse.PipeNode); ok { + return g.cond(p, f) + } + if v := g.operandOf(n, f); v.field != "" { + return map[string]bool{v.field: true}, nil + } + return nil, nil +} + +// comparedToEmpty is the field a compares against an empty string literal b. +func (g *gapWalker) comparedToEmpty(a, b parse.Node, f *frame) string { + s, ok := b.(*parse.StringNode) + if !ok || s.Text != "" { + return "" + } + return g.operandOf(a, f).field +} diff --git a/internal/pkg/tmplvars/gaps_test.go b/internal/pkg/tmplvars/gaps_test.go new file mode 100644 index 000000000..10103a7bc --- /dev/null +++ b/internal/pkg/tmplvars/gaps_test.go @@ -0,0 +1,50 @@ +package tmplvars + +import "testing" + +func TestBlankGaps(t *testing.T) { + cases := []struct { + in string + gap bool + }{ + {"Hi {{.FirstName}},", true}, + {"Hi {{first_name}},", true}, + {"Hi {{.first_name | title}},", true}, + {`{{printf "Hi %s," .FirstName}}`, true}, + {"Hi {{$.FirstName}},", true}, + {"{{if .FirstName}}Bonjour {{.FirstName}},{{else}}Bonjour,{{end}}", false}, + {"{{if .first_name}}Hi {{first_name}}{{end}}", false}, + {"{{if .FirstName}}Hi {{.FirstName}}{{end}} and later {{.FirstName}}", true}, + {"{{if .FirstName}}Hi{{else}}Hi {{.FirstName}}{{end}}", true}, + {"{{with .FirstName}}Hi {{.}},{{else}}Hi,{{end}}", false}, + {`{{.FirstName | default "there"}}`, false}, + {`{{default "there" .FirstName}}`, false}, + {`{{or .FirstName "there"}}`, false}, + {"{{if and .FirstName .Company}}{{.FirstName}} at {{.Company}}{{end}}", false}, + {"{{if not .FirstName}}Hi,{{else}}Hi {{.FirstName}},{{end}}", false}, + {`{{if ne .FirstName ""}}Hi {{.FirstName}}{{end}}`, false}, + {`{{if eq .FirstName ""}}Hi{{else}}Hi {{.FirstName}}{{end}}`, false}, + {"{{if $n := .FirstName}}Hi {{$n}}{{end}}", false}, + {"{{$n := .FirstName}}Hi {{$n}}", true}, + {"{{if .Company}}Hi {{.FirstName}}{{end}}", true}, + {"{{if .FirstName | trim}}Hi {{.FirstName}}{{end}}", false}, + {"{{if .FirstName}}{{else if .Company}}Team {{.Company}}{{end}}", false}, + {"{{range .tags}}{{$.FirstName}}{{end}}", true}, + {"{{.Sender.FirstName}}", false}, + {"{{if .FirstName}}{{end}}", false}, + {"no template here", false}, + } + for _, tc := range cases { + gaps, ok := BlankGaps(tc.in) + if !ok { + t.Errorf("%q: did not parse", tc.in) + continue + } + if gaps["FirstName"] != tc.gap { + t.Errorf("%q: gap=%v, want %v", tc.in, gaps["FirstName"], tc.gap) + } + } + if _, ok := BlankGaps("{{if .FirstName}}unclosed"); ok { + t.Error("an unparseable template reported ok") + } +} diff --git a/internal/repository/advisor_snapshot_facts_live_test.go b/internal/repository/advisor_snapshot_facts_live_test.go new file mode 100644 index 000000000..17e1223e1 --- /dev/null +++ b/internal/repository/advisor_snapshot_facts_live_test.go @@ -0,0 +1,126 @@ +package repository + +import ( + "context" + "testing" + "time" + + "github.com/google/uuid" +) + +// The snapshot reads the facts detectors claim on the send path's terms: an +// enabled sender, the all-active fallback, a stopped warmup and the tracking +// host actually used. +func TestLiveAdvisorSnapshotReadsTheSendPathsFacts(t *testing.T) { + handle, pool := liveContactDB(t) + ctx := context.Background() + requireSchemaVersion(t, pool, 357) + + user, org, campaign := uuid.New(), uuid.New(), uuid.New() + sending, disabled := uuid.New(), uuid.New() + fallbackOrg, fallbackUser, fallbackCampaign, fallbackMailbox := uuid.New(), uuid.New(), uuid.New(), uuid.New() + exec := func(sql string, args ...any) { + t.Helper() + if _, err := pool.Exec(ctx, sql, args...); err != nil { + t.Fatalf("fixture %q: %v", sql[:min(50, len(sql))], err) + } + } + t.Cleanup(func() { + for _, ids := range [][2]uuid.UUID{{org, user}, {fallbackOrg, fallbackUser}} { + for _, sql := range []string{ + `DELETE FROM campaigns WHERE organization_id = $1`, + `DELETE FROM email_accounts WHERE organization_id = $1`, + `DELETE FROM organizations WHERE id = $1`, + } { + if _, err := pool.Exec(ctx, sql, ids[0]); err != nil { + t.Errorf("cleanup: %v", err) + } + } + if _, err := pool.Exec(ctx, `DELETE FROM users WHERE id = $1`, ids[1]); err != nil { + t.Errorf("cleanup user: %v", err) + } + } + }) + + exec(`INSERT INTO users (id, email, first_name, last_name) VALUES ($1, $2, 'Advisor', 'Live')`, + user, "adv-"+user.String()[:8]+"@test.local") + exec(`INSERT INTO organizations (id, name, slug, owner_user_id) VALUES ($1, 'Advisor Live', $2, $3)`, + org, "adv-"+org.String()[:8], user) + for _, a := range []uuid.UUID{sending, disabled} { + exec(`INSERT INTO email_accounts (id, user_id, organization_id, email, name, signature_plain, signature_html, + provider, status, campaign_limit, min_wait_time, timezone, warmup, warmup_paused_at, warmup_stopped_at) + VALUES ($1, $2, $3, $4, 'Advisor', '', '', 'smtp_imap', 'active', 30, 600, 'UTC', NOW(), NOW(), NOW())`, + a, user, org, "adv-"+a.String()[:8]+"@test.local") + } + exec(`INSERT INTO campaigns (id, user_id, organization_id, name, description, days, status, sender_strategy, open_tracking, updated_at, created_at) + VALUES ($1, $2, $3, 'Advisor', '', 62, 'active', 'explicit', true, NOW(), NOW())`, campaign, user, org) + exec(`INSERT INTO campaign_senders (campaign_id, email_account_id, enabled) VALUES ($1, $2, true), ($1, $3, false)`, + campaign, sending, disabled) + repo := NewAdvisorRepository(handle) + snap, err := repo.LoadSnapshot(ctx, org, time.Now()) + if err != nil { + t.Fatalf("load snapshot: %v", err) + } + seen := map[uuid.UUID]bool{} + for _, m := range snap.Mailboxes { + seen[m.ID] = true + switch m.ID { + case sending: + if !m.InActiveCampaign || !m.TrackedOnMailboxHost { + t.Errorf("enabled sender: in campaign=%v tracked=%v, want both", m.InActiveCampaign, m.TrackedOnMailboxHost) + } + if m.WarmupPaused { + t.Error("a stopped warmup read as paused") + } + case disabled: + if m.InActiveCampaign { + t.Error("a disabled sender read as in a running campaign") + } + } + } + if !seen[sending] || !seen[disabled] { + t.Fatalf("the snapshot is missing a fixture mailbox: %v", seen) + } + + // A campaign with no picks and no tags sends from every active mailbox. + exec(`INSERT INTO users (id, email, first_name, last_name) VALUES ($1, $2, 'Advisor', 'Live')`, + fallbackUser, "adv-"+fallbackUser.String()[:8]+"@test.local") + exec(`INSERT INTO organizations (id, name, slug, owner_user_id) VALUES ($1, 'Advisor Live', $2, $3)`, + fallbackOrg, "adv-"+fallbackOrg.String()[:8], fallbackUser) + exec(`INSERT INTO email_accounts (id, user_id, organization_id, email, name, signature_plain, signature_html, + provider, status, campaign_limit, min_wait_time, timezone) + VALUES ($1, $2, $3, $4, 'Advisor', '', '', 'smtp_imap', 'active', 30, 600, 'UTC')`, + fallbackMailbox, fallbackUser, fallbackOrg, "adv-"+fallbackMailbox.String()[:8]+"@test.local") + exec(`INSERT INTO campaigns (id, user_id, organization_id, name, description, days, status, sender_strategy, link_tracking, utm_tracking, updated_at, created_at) + VALUES ($1, $2, $3, 'Advisor', '', 62, 'active', 'tags', false, true, NOW(), NOW())`, fallbackCampaign, fallbackUser, fallbackOrg) + // A seed mailbox never sends campaign mail, so naming one as the only + // sender still leaves the campaign on the fallback. + seed := uuid.New() + exec(`INSERT INTO email_accounts (id, user_id, organization_id, email, name, signature_plain, signature_html, + provider, status, campaign_limit, min_wait_time, timezone, seed_scope) + VALUES ($1, $2, $3, $4, 'Seed', '', '', 'smtp_imap', 'active', 30, 600, 'UTC', 'workspace')`, + seed, fallbackUser, fallbackOrg, "adv-"+seed.String()[:8]+"@test.local") + exec(`INSERT INTO campaign_senders (campaign_id, email_account_id, enabled) VALUES ($1, $2, true)`, fallbackCampaign, seed) + snap, err = repo.LoadSnapshot(ctx, fallbackOrg, time.Now()) + if err != nil { + t.Fatalf("load fallback snapshot: %v", err) + } + byID := map[uuid.UUID]AdvisorMailbox{} + for _, m := range snap.Mailboxes { + byID[m.ID] = m + } + if m, ok := byID[fallbackMailbox]; !ok || !m.InActiveCampaign { + t.Fatalf("a mailbox the all-active fallback sends from read as idle: %+v", snap.Mailboxes) + } + if byID[fallbackMailbox].TrackedOnMailboxHost { + t.Error("UTM tags alone read as tracking through the mailbox's host") + } + if byID[seed].InActiveCampaign { + t.Error("a seed mailbox read as sending for a campaign") + } + for _, c := range snap.Campaigns { + if c.ID == fallbackCampaign && c.SenderCount != 1 { + t.Errorf("fallback campaign sender count = %d, want 1 (the seed mailbox never sends)", c.SenderCount) + } + } +} diff --git a/internal/repository/pg_advisor.go b/internal/repository/pg_advisor.go index cf60beabc..be43a543b 100644 --- a/internal/repository/pg_advisor.go +++ b/internal/repository/pg_advisor.go @@ -9,7 +9,6 @@ import ( "github.com/google/uuid" "github.com/jackc/pgx/v5" - "github.com/warmbly/warmbly/internal/app/copyjudge" "github.com/warmbly/warmbly/internal/infrastructure/db" "github.com/warmbly/warmbly/internal/models" ) @@ -74,6 +73,9 @@ type AdvisorMailbox struct { // InActiveCampaign is true when at least one running campaign can send // through this mailbox (tag match or explicit sender). InActiveCampaign bool + // TrackedOnMailboxHost is true when one of those campaigns tracks opens or + // links and has no verified tracking domain of its own, so the mailbox's host is used. + TrackedOnMailboxHost bool // SendLifecycle is active, resting or reserve (held by its owner). SendLifecycle string // The pool's warmup mail handed off to this mailbox over seven days, how @@ -163,6 +165,8 @@ type AdvisorStep struct { Subject string BodyPlain string BodyHTML string + // ThreadReply sends the step under the conversation's subject, never its own. + ThreadReply bool Sent int Opened int @@ -219,11 +223,9 @@ type AdvisorSnapshot struct { // their mail has already stopped going out or is only about to. DomainAuthEnforced bool DomainAuthGrace time.Duration - // CopyJudgments holds the TypeSafe verdict for each email step's copy, - // keyed by step id. Filled by the service when a judge is configured; - // a step with no entry is simply not judged, and no copy detector that - // reads a verdict fires on it. - CopyJudgments map[uuid.UUID]copyjudge.Verdict + // WarmupUnavailable is set by the service when the plan does not include + // warmup, so no finding asks to turn it on or resume it. + WarmupUnavailable bool // Failed holds each section that did not load this run, with its error. Failed map[AdvisorSection]error } diff --git a/internal/repository/pg_advisor_snapshot.go b/internal/repository/pg_advisor_snapshot.go index 6c9c34ba6..24e8ce578 100644 --- a/internal/repository/pg_advisor_snapshot.go +++ b/internal/repository/pg_advisor_snapshot.go @@ -82,7 +82,8 @@ func (r *advisorRepository) loadMailboxes(ctx context.Context, orgID uuid.UUID, ea.tracking_domain, ea.tracking_domain_verified, ea.auth_state, ea.auth_spf, ea.auth_dkim, ea.auth_dmarc, ea.auth_dmarc_policy, ea.auth_failing_since, (ea.warmup IS NOT NULL AND ea.warmup_paused_at IS NULL) AS warmup_active, - (ea.warmup IS NOT NULL AND ea.warmup_paused_at IS NOT NULL) AS warmup_paused, + -- Stop also stamps warmup_paused_at; a stopped mailbox is off, not paused. + (ea.warmup IS NOT NULL AND ea.warmup_paused_at IS NOT NULL AND ea.warmup_stopped_at IS NULL) AS warmup_paused, ea.warmup_base, ea.warmup_max, ea.warmup_increase, ea.warmup_reply_rate, COALESCE(ea.warmup_pool_type, 'free'), ea.risk_band::text, @@ -94,7 +95,7 @@ func (r *advisorRepository) loadMailboxes(ctx context.Context, orgID uuid.UUID, CASE WHEN cstatus.cloud_only THEN '` + models.WarmupReasonCloudEvidenceUnavailable + `' ELSE COALESCE(p.last_health_reason, '') END, (NOT cstatus.cloud_only AND COALESCE(p.blocked_until > NOW(), false)) AS pool_blocked, COALESCE(err.n, 0), - COALESCE(camp.active, false), + COALESCE(camp.active, false), COALESCE(camp.tracked, false), ea.send_lifecycle, inb.delivered, inb.arrived, inb.lost_by FROM email_accounts ea @@ -113,7 +114,9 @@ func (r *advisorRepository) loadMailboxes(ctx context.Context, orgID uuid.UUID, LEFT JOIN ( SELECT t2.email_account_id, - COUNT(*) FILTER (WHERE de.event_type = 'bounce') AS bounces, + -- Hard bounces only, on the pool health model's terms: a full mailbox, a block or a transient failure is not about the address. + COUNT(*) FILTER (WHERE de.event_type = 'bounce' + AND COALESCE(de.metadata->>'bounce_cause', '') NOT IN ('mailbox_full', 'reputation_block', 'transient')) AS bounces, COUNT(*) FILTER (WHERE de.event_type = 'complaint') AS complaints FROM deliverability_events de JOIN tasks t2 ON t2.id = de.task_id @@ -148,21 +151,36 @@ func (r *advisorRepository) loadMailboxes(ctx context.Context, orgID uuid.UUID, AND wt.recipient_account_id = ea.id ) inb ON true LEFT JOIN LATERAL ( - -- A mailbox counts as "in an active campaign" when a running - -- campaign either lists it explicitly or matches one of its tags. - SELECT true AS active + -- A mailbox counts as "in an active campaign" on ResolveCampaignSenderPool's terms: + -- an enabled sender, a tag match, or the all-active fallback, and never a seed mailbox. + -- tracked: one of them puts a pixel or wrapped links on the mailbox's host (UTM tags alone do not). + SELECT true AS active, + bool_or((c.open_tracking OR c.link_tracking) + AND NOT (c.tracking_domain <> '' AND c.tracking_domain_verified)) AS tracked FROM campaigns c WHERE c.organization_id = ea.organization_id AND c.status = 'active' + AND ea.seed_scope IS NULL AND ( - EXISTS (SELECT 1 FROM campaign_senders cs WHERE cs.campaign_id = c.id AND cs.email_account_id = ea.id) + EXISTS (SELECT 1 FROM campaign_senders cs WHERE cs.campaign_id = c.id AND cs.email_account_id = ea.id AND cs.enabled) OR EXISTS ( SELECT 1 FROM campaign_email_tags cet JOIN email_tags et ON et.tag_id = cet.tag_id WHERE cet.campaign_id = c.id AND et.email_id = ea.id ) + OR ( + ea.status = 'active' + AND c.sender_strategy <> 'explicit' + AND NOT EXISTS (SELECT 1 FROM campaign_email_tags cet WHERE cet.campaign_id = c.id) + AND NOT EXISTS ( + SELECT 1 FROM campaign_senders cs + JOIN email_accounts sea ON sea.id = cs.email_account_id + WHERE cs.campaign_id = c.id AND cs.enabled + AND sea.organization_id = c.organization_id AND sea.status = 'active' AND sea.seed_scope IS NULL + ) + ) ) - LIMIT 1 + HAVING COUNT(*) > 0 ) camp ON true WHERE ea.organization_id = $1 ORDER BY ea.created_at ASC` @@ -190,7 +208,7 @@ func (r *advisorRepository) loadMailboxes(ctx context.Context, orgID uuid.UUID, &m.WarmupPlacement.MajorDelivered, &m.WarmupPlacement.MajorSpam, &m.WarmupPlacement.OtherDelivered, &m.WarmupPlacement.OtherSpam, &m.PoolHealth, &m.PoolHealthScore, &m.PoolHealthReason, &m.PoolBlocked, - &m.UnresolvedErrs, &m.InActiveCampaign, + &m.UnresolvedErrs, &m.InActiveCampaign, &m.TrackedOnMailboxHost, &m.SendLifecycle, &m.WarmupDelivered7d, &m.WarmupArrived7d, &m.WarmupLostBy7d, ); err != nil { @@ -230,6 +248,7 @@ func (r *advisorRepository) loadCampaigns(ctx context.Context, orgID uuid.UUID) FROM email_accounts ea WHERE ea.organization_id = c.organization_id AND ea.status = 'active' + AND ea.seed_scope IS NULL AND ( EXISTS (SELECT 1 FROM campaign_senders cs WHERE cs.campaign_id = c.id AND cs.email_account_id = ea.id AND cs.enabled) OR EXISTS ( @@ -245,7 +264,7 @@ func (r *advisorRepository) loadCampaigns(ctx context.Context, orgID uuid.UUID) SELECT 1 FROM campaign_senders cs JOIN email_accounts sea ON sea.id = cs.email_account_id WHERE cs.campaign_id = c.id AND cs.enabled - AND sea.organization_id = c.organization_id AND sea.status = 'active' + AND sea.organization_id = c.organization_id AND sea.status = 'active' AND sea.seed_scope IS NULL ) ) ) @@ -324,7 +343,7 @@ func (r *advisorRepository) loadSteps(ctx context.Context, orgID uuid.UUID) ([]A query := ` SELECT s.id, s.campaign_id, s.name, s."position", COALESCE(s.kind, 'email'), s.wait_after, - s.subject, s.body_plain, s.body_html, + s.subject, s.body_plain, s.body_html, s.thread_reply, COALESCE(f.sent, 0), COALESCE(f.opened, 0), COALESCE(f.replied, 0), COALESCE(f.bounced, 0) FROM sequences s JOIN campaigns c ON c.id = s.campaign_id @@ -340,7 +359,7 @@ func (r *advisorRepository) loadSteps(ctx context.Context, orgID uuid.UUID) ([]A ) f ON true WHERE c.organization_id = $1 AND c.status IN ('active', 'paused', 'draft') - ORDER BY s.campaign_id, s."position" + ORDER BY s.campaign_id, s."position", s.created_at LIMIT 2000` rows, err := r.db.Query(ctx, query, orgID) @@ -354,7 +373,7 @@ func (r *advisorRepository) loadSteps(ctx context.Context, orgID uuid.UUID) ([]A var s AdvisorStep if err := rows.Scan( &s.ID, &s.CampaignID, &s.Name, &s.Position, &s.Kind, &s.WaitAfter, - &s.Subject, &s.BodyPlain, &s.BodyHTML, + &s.Subject, &s.BodyPlain, &s.BodyHTML, &s.ThreadReply, &s.Sent, &s.Opened, &s.Replied, &s.Bounced, ); err != nil { return nil, err diff --git a/internal/repository/pg_copy_judgment.go b/internal/repository/pg_copy_judgment.go deleted file mode 100644 index 985b6a92a..000000000 --- a/internal/repository/pg_copy_judgment.go +++ /dev/null @@ -1,78 +0,0 @@ -package repository - -import ( - "context" - "encoding/json" - "errors" - "fmt" - - "github.com/google/uuid" - "github.com/jackc/pgx/v5" - "github.com/jackc/pgx/v5/pgxpool" - - "github.com/warmbly/warmbly/internal/app/copyjudge" -) - -// CopyJudgmentRepository caches one TypeSafe verdict per piece of copy per -// organization, keyed by content hash, so an unchanged step is judged once -// however many times the Advisor runs or the editor re-checks it. -type CopyJudgmentRepository interface { - // Get returns the stored verdict, or nil when this copy has not been - // judged. - Get(ctx context.Context, orgID uuid.UUID, hash string) (*copyjudge.Verdict, error) - // Put stores or replaces the verdict for this copy. - Put(ctx context.Context, orgID uuid.UUID, hash string, v *copyjudge.Verdict) error -} - -type copyJudgmentRepository struct { - db *pgxpool.Pool -} - -func NewCopyJudgmentRepository(db *pgxpool.Pool) CopyJudgmentRepository { - return ©JudgmentRepository{db: db} -} - -func (r *copyJudgmentRepository) Get(ctx context.Context, orgID uuid.UUID, hash string) (*copyjudge.Verdict, error) { - var ( - raw []byte - model string - tokens int - ) - err := r.db.QueryRow(ctx, ` - SELECT verdict, model, input_tokens FROM copy_judgments - WHERE organization_id = $1 AND content_hash = $2`, orgID, hash).Scan(&raw, &model, &tokens) - if errors.Is(err, pgx.ErrNoRows) { - return nil, nil - } - if err != nil { - return nil, fmt.Errorf("copy judgment get: %w", err) - } - var v copyjudge.Verdict - if err := json.Unmarshal(raw, &v); err != nil { - return nil, fmt.Errorf("copy judgment decode: %w", err) - } - // The columns are the record of what was paid; the jsonb is the answer. - v.Model, v.InputTokens = model, tokens - return &v, nil -} - -func (r *copyJudgmentRepository) Put(ctx context.Context, orgID uuid.UUID, hash string, v *copyjudge.Verdict) error { - if v == nil { - return errors.New("copy judgment put: nil verdict") - } - raw, err := json.Marshal(v) - if err != nil { - return fmt.Errorf("copy judgment encode: %w", err) - } - _, err = r.db.Exec(ctx, ` - INSERT INTO copy_judgments (organization_id, content_hash, verdict, model, input_tokens) - VALUES ($1, $2, $3, $4, $5) - ON CONFLICT (organization_id, content_hash) DO UPDATE SET - verdict = EXCLUDED.verdict, model = EXCLUDED.model, - input_tokens = EXCLUDED.input_tokens, created_at = NOW()`, - orgID, hash, raw, v.Model, v.InputTokens) - if err != nil { - return fmt.Errorf("copy judgment put: %w", err) - } - return nil -} diff --git a/internal/tasks/spintax.go b/internal/tasks/spintax.go index abccd8450..0acb3ce13 100644 --- a/internal/tasks/spintax.go +++ b/internal/tasks/spintax.go @@ -40,6 +40,34 @@ func spinClean(s string) string { // spintaxAlt matches an innermost {a|b|…} group that actually contains a '|'. var spintaxAlt = regexp.MustCompile(`\{([^{}]*\|[^{}]*)\}`) +// ShortestSpintax resolves each alternation group expandSpintax would expand to +// its shortest option: the reading every recipient's copy is at least as long as. +func ShortestSpintax(s string) string { + return ResolveSpintax(s, func(opts []string) string { + best := opts[0] + for _, o := range opts[1:] { + if len(o) < len(best) { + best = o + } + } + return best + }) +} + +// ResolveSpintax resolves each alternation group expandSpintax would expand, +// innermost first, to the option pick chooses. +func ResolveSpintax(s string, pick func(opts []string) string) string { + if !strings.Contains(s, "|") { + return s + } + for i := 0; i < 20 && spintaxAlt.MatchString(s); i++ { + s = spintaxAlt.ReplaceAllStringFunc(s, func(m string) string { + return pick(strings.Split(m[1:len(m)-1], "|")) + }) + } + return s +} + // expandSpintax expands ONLY real alternation groups — those containing a '|' — // choosing one option at random per group. Brace runs without a '|' (CSS in an // HTML body, JSON, an unrelated "{...}") are left verbatim, so this is safe to