feat: prioritize eligible recovery senders before limiting warmup reply candidates and clarify reply targets

This commit is contained in:
Matthew Meszaros
2026-11-02 09:17:29 +01:00
parent 1b98c61ef9
commit 522ea35d14
8 changed files with 131 additions and 36 deletions
+1 -1
View File
@@ -350,7 +350,7 @@ jobs:
WARMBLY_TEST_DB: postgres://warmbly:warmbly@127.0.0.1:5432/warmbly_test?sslmode=disable
run: |
set -o pipefail
go test -race ./internal/repository -run '^TestLive(Monitoring|LastWarmupSendFailure|PersistentMailboxLoadingFailure|DispatchRetry|LineageQueueRevisions|AdminPlatformOverview|WarmupRecoversOldPreparation|WarmupPreparationRecoveryRetains|WarmupFilingRequiresAcknowledgement|WarmupFilingAuthority|WarmupTimeWindow|WarmupInvalidWindow|StoppedRecipientIsNeverAddressed)' -count=1
go test -race ./internal/repository -run '^TestLive(Monitoring|LastWarmupSendFailure|PersistentMailboxLoadingFailure|DispatchRetry|LineageQueueRevisions|ReplyShare|AdminPlatformOverview|WarmupRecoversOldPreparation|WarmupPreparationRecoveryRetains|WarmupFilingRequiresAcknowledgement|WarmupFilingAuthority|WarmupTimeWindow|WarmupInvalidWindow|StoppedRecipientIsNeverAddressed)' -count=1
go test -race -v ./internal/tasks -run '^Test(LiveWarmup(SafetyHoldReschedules|Recovery|UnknownRetirement|TaskDoesNotApplyResults|DispatchDefersInvalidHours)|WarmupSenderDistinguishes)' -count=1 | tee warmup-recovery.log
if grep -q -- '--- SKIP: TestLiveWarmupUnknownRetirement' warmup-recovery.log; then exit 1; fi
for test in TestLiveWarmupUnknownRetirementPreservesEvidenceAndFencesReplayOnce TestLiveWarmupUnknownRetirementAllowsDistinctNewSendAndKeepsCooldown TestLiveWarmupUnknownRetirementAndDefinitiveResultSerialize TestLiveWarmupUnknownRetirementSkipsProtectedRowsWithoutStarvingLaterMailboxes TestLiveWarmupUnknownRetirementReconcilerSeedsOnceAndClearsActiveWarnings; do
@@ -159,7 +159,7 @@ Auth: **Scope** `WRITE_EMAILS` · **Org permission** `manage_emails`
| `warmup_base` | integer | no | Warmup starting volume per day. |
| `warmup_max` | integer | no | Warmup daily ceiling. |
| `warmup_increase` | integer | no | Per-day warmup ramp increment. |
| `warmup_reply_rate` | integer | no | Percentage of the mailbox's own warmup sends that are replies, held over its last seven days. `0` turns warmup replies off. |
| `warmup_reply_rate` | integer | no | Target percentage of the mailbox's own warmup sends that are replies over its last seven UTC days. Eligible received mail and partner availability can limit the measured rate. `0` turns warmup replies off. |
| `warmup_tag` | string | no | Tag applied to warmup threads. |
| `warmup_start_time` | string | no | Daily warmup window start, `HH:MM`. |
| `warmup_end_time` | string | no | Daily warmup window end, `HH:MM`. |
+4 -4
View File
@@ -254,14 +254,14 @@ Replies continue the exact pinned thread and subject, each parent is answered on
Replies thread properly with a real `Re:` subject and `In-Reply-To` header, and candidates must be between 45 minutes and seven days old, so nothing is answered instantly or revived indefinitely.
The **Reply rate** setting is the share of a mailbox's own warmup sends that are replies, and Warmbly holds the mailbox to it. Over its last seven UTC days of warmup, a mailbox set to `30%` sends about three replies for every ten warmup emails, the same figure the Analytics tab reports. Replies never add volume: each one takes the place of a send the mailbox was going to make anyway. `0%` turns replies off.
The **Reply rate** setting targets the share of a mailbox's own warmup sends that are replies over its last seven UTC days. With enough eligible received mail, a mailbox set to `30%` approaches three replies for every ten warmup emails. The Analytics tab reports the measured rate over its selected range, which defaults to the last 30 days, so the figures can differ. Replies never add volume: each one takes the place of a send the mailbox was going to make anyway. `0%` turns replies off.
Replies reach that share two ways:
- **On arrival.** When a verified warmup email arrives and the mailbox is below its share, it sometimes points its next scheduled send back at whoever wrote, 45 minutes to 5 hours later and inside its own warmup hours. The chance is the mailbox's reply rate (raised for a sender in [recovery](#recovery-engagement)), drawn once when the reply is scheduled rather than again when it sends. Each mailbox has one warmup send queued at a time, so a reply-back moves that send earlier and aims it, and never pushes a send the mailbox had already planned sooner. If that send is due within 45 minutes of the arrival, or is already answering someone, the arrival is not answered then.
- **When a send goes out.** If the mailbox is still below its share when its next new-thread send fires, that send answers warmup mail it received instead: something at least 45 minutes and at most seven days old that it has not answered, newest first and mail from a sender in [recovery](#recovery-engagement) before any other. A mailbox ahead of its share does not reply until its sends catch up.
- **On arrival.** When a verified warmup email arrives, Warmbly includes the next send in its target calculation. If that leaves room for a reply, it sometimes points the next scheduled send back at whoever wrote, 45 minutes to 5 hours later and inside its own warmup hours. The chance is the mailbox's reply rate (raised for a sender in [recovery](#recovery-engagement)), drawn once when the reply is scheduled rather than again when it sends. Each mailbox has one warmup send queued at a time, so a reply-back moves that send earlier and aims it, and never pushes a send the mailbox had already planned sooner. If that send is due within 45 minutes of the arrival, or is already answering someone, the arrival is not answered then.
- **When a send goes out.** Warmbly calculates the replies needed to reach the target, including the next send. A deficit of one reply or more makes the send a reply when eligible mail is available; a fractional deficit becomes a reply chance. For example, a `25%` target with ten sends and two replies gives the next send a `75%` reply chance. Because the calculation includes the next send, it can allow a reply when the current share is slightly above target. A selected reply answers mail at least 45 minutes and at most seven days old that the mailbox has not answered. Mail from senders in [recovery](#recovery-engagement) is considered first, then newest first within each group.
Together these help the measured rate converge on the setting, including for busy mailboxes whose next send is almost always less than 45 minutes away. Small send counts and a recent setting change can make it differ temporarily. The rate can fall short when eligible received mail is unavailable, threads have reached their message caps, or the partners that wrote to it can no longer receive. Reply selection considers a bounded set of recent messages on each send, so unavailable recent partners can also delay catch-up.
Together these help the measured rate converge on the setting, including for busy mailboxes whose next send is almost always less than 45 minutes away. Small send counts and a recent setting change can make it differ temporarily. The rate can fall short when eligible received mail is unavailable, threads have reached their message caps, or the partners that wrote to it can no longer receive. Reply selection considers a bounded set of messages on each send, with recovery priority applied before that limit, so unavailable partners among those candidates can also delay catch-up.
A reply is held to the same daily receiving cap as any other warmup email: a reply to an inbox that is full for the day is not sent, and the mailbox goes on with another reply or a new thread, so one busy partner never stops a mailbox's warmup. Replies stop before a thread reaches its message cap so replies cannot answer replies indefinitely. A reply crosses the free and paid tiers like the mail it answers: a paid mailbox answers a free partner that wrote to it, and a free mailbox answers a paid one while it is healthy and its workspace is in good standing.
+42 -9
View File
@@ -9,6 +9,7 @@ import (
"github.com/google/uuid"
"github.com/jackc/pgx/v5"
"github.com/warmbly/warmbly/internal/app/warmupramp"
"github.com/warmbly/warmbly/internal/models"
"github.com/warmbly/warmbly/internal/pkg/mailhdr"
)
@@ -185,19 +186,51 @@ func (r *taskRepository) WarmupReplyShare(ctx context.Context, mailbox uuid.UUID
return sent, replied, err
}
// OwedWarmupReplies lists verified warmup mail the mailbox received at least 45 minutes ago and can still answer, newest first.
func (r *taskRepository) OwedWarmupReplies(ctx context.Context, recipient uuid.UUID, limit int) ([]WarmupOwedReply, error) {
rows, err := r.db.Query(ctx, `SELECT wt.task_id, wr.internal_id, wt.sender_account_id,
wr.message_id, original.subject, wr.provider_thread_id,
COALESCE(wt.conversation_theme,''),COALESCE(wt.content_source,''),wt.conversation_id,wt.conversation_turn,
COALESCE(original.reference_ids,'{}'::text[]),original.scenario_version,original.rendering_version,original.max_turns
FROM warmup_received wr
const owedWarmupRepliesFromSQL = `FROM warmup_received wr
JOIN warmup_tokens wt ON wt.task_id=wr.task_id AND wt.recipient_account_id=wr.email_account_id
JOIN warmup_tasks original ON original.task_id=wt.task_id
JOIN email_accounts ea ON ea.id=wr.email_account_id
WHERE wr.email_account_id=$1 AND wr.created_at<=NOW()-INTERVAL '45 minutes'
AND `+warmupAnswerableSQL+`
ORDER BY wr.created_at DESC LIMIT $2`, recipient, limit)
AND ` + warmupAnswerableSQL
// recoveringWarmupReplySenders classifies every eligible sender before limiting the messages considered for a reply.
func (r *taskRepository) recoveringWarmupReplySenders(ctx context.Context, recipient uuid.UUID) ([]uuid.UUID, error) {
rows, err := r.db.Query(ctx, `WITH senders AS (SELECT DISTINCT wt.sender_account_id AS id `+owedWarmupRepliesFromSQL+`)
SELECT sender.id, sender.mail_host, sender.provider, sender.email, COALESCE(h.health_state,'healthy'),
EXISTS (`+strings.ReplaceAll(activeCampaignsForAccountSQL, "$1", "s.id")+`)
FROM senders s JOIN email_accounts sender ON sender.id=s.id
LEFT JOIN LATERAL (`+warmupGateStandingSQL("s.id")+`) h ON true`, recipient)
if err != nil {
return nil, err
}
defer rows.Close()
priority := []uuid.UUID{}
for rows.Next() {
var sender models.Email
var health models.WarmupHealthState
var campaigning bool
if err := rows.Scan(&sender.ID, &sender.MailHost, &sender.Provider, &sender.Email, &health, &campaigning); err != nil {
return nil, err
}
if health == models.WarmupHealthWatch || health == models.WarmupHealthThrottled || sender.ConsumerMailbox() || campaigning {
priority = append(priority, sender.ID)
}
}
return priority, rows.Err()
}
// OwedWarmupReplies applies recovery priority before the limit, then orders eligible messages newest first.
func (r *taskRepository) OwedWarmupReplies(ctx context.Context, recipient uuid.UUID, limit int) ([]WarmupOwedReply, error) {
priority, err := r.recoveringWarmupReplySenders(ctx, recipient)
if err != nil {
return nil, err
}
rows, err := r.db.Query(ctx, `SELECT wt.task_id, wr.internal_id, wt.sender_account_id,
wr.message_id, original.subject, wr.provider_thread_id,
COALESCE(wt.conversation_theme,''),COALESCE(wt.content_source,''),wt.conversation_id,wt.conversation_turn,
COALESCE(original.reference_ids,'{}'::text[]),original.scenario_version,original.rendering_version,original.max_turns
`+owedWarmupRepliesFromSQL+`
ORDER BY (wt.sender_account_id=ANY($3::uuid[])) DESC, wr.created_at DESC, wt.task_id LIMIT $2`, recipient, limit, priority)
if err != nil {
return nil, err
}
@@ -1,6 +1,7 @@
package repository
import (
"context"
"testing"
"time"
@@ -74,3 +75,83 @@ func TestLiveReplyShareAnswersOwedMailOnAClaimedSend(t *testing.T) {
t.Fatalf("share window = %d sent %d replied (%v), want 14 and 4", sent, replied, err)
}
}
func TestLiveReplySharePrioritizesRecoveryBeforeCandidateLimit(t *testing.T) {
for _, tc := range []struct {
name, health, host, provider, address string
campaign bool
}{
{name: "watch", health: "watch"},
{name: "throttled", health: "throttled"},
{name: "consumer Gmail", host: "google_workspace", provider: "gmail", address: "reply-priority@gmail.com"},
{name: "consumer Outlook", provider: "outlook", address: "reply-priority@hotmail.co.uk"},
{name: "stored consumer host", host: "outlook"},
{name: "active campaign", campaign: true},
} {
t.Run(tc.name, func(t *testing.T) {
f, r := lineageFixture(t)
ctx := t.Context()
exec := func(query string, args ...any) {
t.Helper()
if _, err := f.pool.Exec(ctx, query, args...); err != nil {
t.Fatal(err)
}
}
normal := uuid.New()
exec(`INSERT INTO email_accounts(id,user_id,organization_id,email,name,signature_plain,signature_html,provider,status)
VALUES($1,$2,$3,$4,'Partner','','','smtp_imap','active')`, normal, f.user, f.org, normal.String()+"@example.test")
seed := func(task, sender uuid.UUID, age time.Duration) {
t.Helper()
if task != f.task {
exec(`INSERT INTO tasks(id,task_type,email_account_id,status,message_id) VALUES($1,'warmup',$2,'completed','')`, task, sender)
}
exec(`INSERT INTO warmup_tasks(task_id,lineage_version,subject,scenario_version,rendering_version,max_turns)
VALUES($1,1,'Project notes','diagnostic-v1','canonical-v1',3)`, task)
messageID := task.String() + "@example.test"
exec(`INSERT INTO warmup_tokens(token,task_id,sender_account_id,recipient_account_id,conversation_id,conversation_turn,sent_message_id)
VALUES($1,$2,$3,$4,$5,0,$6)`, uuid.New(), task, sender, f.recipient, uuid.New(), "<"+messageID+">")
receipt := uuid.New()
exec(`INSERT INTO warmup_received(email_account_id,internal_id,sender_account_id,message_id,created_at)
VALUES($1,$2,$3,$4,$5)`, f.recipient, receipt, sender, messageID, time.Now().Add(-age))
address := f.senderTo
if sender == normal {
address = normal.String() + "@example.test"
}
if err := r.RecordVerifiedWarmupParent(ctx, task, f.recipient, receipt, "thread", WarmupReceiptProof{SenderAddress: address}); err != nil {
t.Fatal(err)
}
}
seed(f.task, f.sender, 3*time.Hour)
newerRecovery := uuid.New()
seed(newerRecovery, f.sender, 2*time.Hour)
for i := range 8 {
seed(uuid.New(), normal, time.Hour+time.Duration(i)*time.Minute)
}
owed, err := r.OwedWarmupReplies(ctx, f.recipient, 8)
if err != nil || len(owed) != 8 || owed[0].SenderID != normal || owed[7].SenderID != normal {
t.Fatalf("ordinary messages not ordered newest first: %+v %v", owed, err)
}
if tc.health != "" {
exec(`INSERT INTO warmup_pool_participants(pool_id,email_account_id,health_state)
SELECT id,$1,$2 FROM warmup_pools WHERE pool_type='free'`, f.sender, tc.health)
}
if tc.host != "" || tc.provider != "" {
exec(`UPDATE email_accounts SET mail_host=$2,provider=COALESCE(NULLIF($3,''),'smtp_imap')::email_provider,email=COALESCE(NULLIF($4,''),email) WHERE id=$1`, f.sender, tc.host, tc.provider, tc.address)
}
if tc.campaign {
campaign := uuid.New()
exec(`INSERT INTO campaigns(id,user_id,organization_id,name,description,days,status,created_at,updated_at) VALUES($1,$2,$3,'Priority','',62,'active',NOW(),NOW())`, campaign, f.user, f.org)
exec(`INSERT INTO campaign_senders(campaign_id,email_account_id) VALUES($1,$2)`, campaign, f.sender)
t.Cleanup(func() {
if _, err := f.pool.Exec(context.Background(), `DELETE FROM campaigns WHERE id=$1`, campaign); err != nil {
t.Error(err)
}
})
}
owed, err = r.OwedWarmupReplies(ctx, f.recipient, 8)
if err != nil || len(owed) != 8 || owed[0].ParentTaskID != newerRecovery || owed[1].ParentTaskID != f.task || owed[2].SenderID != normal {
t.Fatalf("older recovery mail not prioritized before the limit: %+v %v", owed, err)
}
})
}
}
-19
View File
@@ -3,7 +3,6 @@ package tasks
import (
"context"
"math/rand"
"sort"
"github.com/google/uuid"
"github.com/rs/zerolog/log"
@@ -34,24 +33,6 @@ func (s *tasksService) owedWarmupReply(ctx context.Context, taskID uuid.UUID, ac
if err != nil || len(owed) == 0 {
return nil
}
signals := warmupramp.RecoverySignals{}
if s.warmupRepo != nil {
signals.Health = s.warmupRepo
}
if s.emailRepo != nil {
signals.Mailboxes = s.emailRepo
}
if s.campaignRepo != nil {
signals.Campaigns = s.campaignRepo
}
recovering := make(map[uuid.UUID]bool, len(owed))
for _, o := range owed {
if _, seen := recovering[o.SenderID]; !seen {
recovering[o.SenderID] = signals.Recovering(ctx, o.SenderID)
}
}
sort.SliceStable(owed, func(i, j int) bool { return recovering[owed[i].SenderID] && !recovering[owed[j].SenderID] })
for _, o := range owed {
if _, _, _, err := s.exactReplyContent(ctx, &o.Parent, *account); err != nil {
continue
@@ -30,7 +30,7 @@ export function WarmupNote({ e, className }: { e: CampaignEstimateResult; classN
<span>
Warmup keeps running on {plural(w.mailboxes, "mailbox", "mailboxes")}
{without > now ? `, down from about ${without} to ${now} a day each` : `, about ${now} a day each`} while this runs.
{w.reply_rate ? " Pool partners answer it before other warmup mail." : ""}
{w.reply_rate ? " Pool partners prioritize replies to it within their own reply settings." : ""}
</span>
</p>
);
@@ -1613,7 +1613,7 @@ function WarmupTab({ form, update, status, mailbox, canWarmup = true }: { form:
{baseOverMax && (
<p className="text-[11px] text-rose-600 -mt-3">Starting volume can't exceed the maximum.</p>
)}
<FieldShell label="Reply rate" hint="Share of this mailbox's warmup sends that are replies, held over the last 7 days.">
<FieldShell label="Reply rate" hint="Target share of this mailbox's warmup sends that are replies over the last 7 UTC days, when eligible mail is available. 0% turns replies off.">
<NumField value={form.warmup_reply_rate} onChange={(v) => update({ warmup_reply_rate: v })} suffix="%" min={cloudMin} />
</FieldShell>
{/* Warmbly Cloud writes its own content, so the segment only applies to warmup sent from here. */}