Autonomous AI sales agent powered by Claude Code or Codex. Finds prospects, writes cold emails, sends campaigns, handles replies, books meetings. No API keys needed — runs on your Claude or Codex subscriptions.
Warmup readiness check, a cold-email ramp, and follow-ups that wait their turn
Ethan301b2f647725
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c1828e8..5429655 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -9,6 +9,18 @@ minor versions can still change behaviour.### Added+- **`harvey warmup [domain]`**: checks whether a sending domain is ready for+ cold email. It covers MX, SPF (`+all`, duplicates, top-level lookups), DKIM,+ DMARC, domain age, domain and SMTP-IP blocklists (a list that refuses the+ query is reported as such, not as a listing), warmup progress and bounce+ rate, then gives a READY / NOT READY verdict. It's read-only, and a DNS+ timeout is reported as unknown, never as a missing record.+- **A cold-email ramp for new domains** (`channels.email.warmup`). From+ `start_date`, no cold email goes out for `min_days`; then the cold cap starts+ at `start_sends` and climbs by `daily_increase` a day up to+ `max_daily_sends`. It applies to native providers and Instantly lead+ uploads. Replies are never held. Off unless `start_date` is set. Both+ based on #18 by Tariz Shahid.- **A postal address and opt-out line under every cold email** (CAN-SPAM).Set `compliance.postal_address` in `harvey.yaml`; `compliance.opt_out_line`defaults to *Not interested? Reply "no thanks" and I won't email again.*@@ -21,6 +33,13 @@ minor versions can still change behaviour.### Fixed+- A follow-up no longer goes out before, or right after, the email it+ follows. Each step now waits until the previous one has actually been sent+ and its gap (at least a day) has passed. Before, approving a batch of drafts+ late, or resuming after a pause or a compliance hold, could send a whole+ sequence within minutes, or step 2 before step 1. A follow-up whose earlier+ email was rejected or failed is cancelled instead of arriving as a first+ email.- Replies are read without the email they quote. The model, the stored threadand the answer get the reply without the quoted email, and any line thatrepeats what Harvey sent that person is set aside, so Harvey's own wordsdiff --git a/CLAUDE.md b/CLAUDE.mdindex e5cbd07..065c8a1 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -272,6 +272,7 @@ harvey outbox # Review queued emails; --approve <id> / --approve-harvey signals # The signal vocabulary; --confirm / --reject CODES (or 'free' / 'all')harvey discover # Find businesses; --providers / --estimate / --provider <key>harvey sending pause|resume # Kill switch for all outbound+harvey warmup [domain] # Sending-domain readiness: SPF/DKIM/DMARC, age, blocklists, ramp```### Common Issuesdiff --git a/README.md b/README.mdindex a54b5f1..fa0f596 100644--- a/README.md+++ b/README.md@@ -442,6 +442,7 @@ harvey usage # active provider's quota + per-agent tokensharvey outbox # review queued emailharvey export # deliverable prospects → CSVharvey sending pause|resume # kill switch+harvey warmup [domain] # is the sending domain ready? (SPF/DKIM/DMARC, age, blocklists)harvey retry-writes # retry prospects the Writer gave up onharvey gmail auth # one-time Gmail OAuthharvey microsoft auth|test # one-time Microsoft 365 sign-in (docs/microsoft365.md)@@ -502,9 +503,9 @@ your explicit choice.**Deliverability — warm up or burn out.** Sending cold email from your main domain, or at volume on day one, lands you in spam permanently.1. Buy a **dedicated sending domain** (`getacme.com`, not `acme.com`).-2. Set up **SPF, DKIM and DMARC** on it. Without all three, Gmail junks you.+2. Set up **SPF, DKIM and DMARC** on it. Without all three, Gmail junks you. `harvey warmup` checks them, plus domain age, blocklists, your warmup progress and bounce rate, and ends with READY / NOT READY. It only reads public DNS and Harvey's own records.3. **Warm up for 2–4 weeks** before real volume.-4. **Ramp slowly** — 10–20/day per inbox, adding ~5/day. The `max_daily_sends: 50` default is a ceiling, not a target.+4. **Ramp slowly** — 10–20/day per inbox, adding ~5/day. The `max_daily_sends: 50` default is a ceiling, not a target. Set `channels.email.warmup.start_date` and Harvey does this for you: no cold email for `min_days`, then a cold-email cap that climbs by `daily_increase` a day. Replies always go out.5. **Watch bounces.** Above ~3%, stop and fix list quality. Harvey trips its own kill switch past your configured threshold.*None of this is legal advice. Sending at scale or into regulated industries? Talk to a lawyer.*diff --git a/harvey.yaml b/harvey.yamlindex 9eeeef2..040812e 100644--- a/harvey.yaml+++ b/harvey.yaml@@ -52,6 +52,16 @@ channels:require_approval: true # native: review in Outbox; Instantly: sending heldsend_to_risky: false # also send to catch-all domains (off = safest)max_bounce_rate: 0.05 # pause all sending if bounces exceed this+ # New sending domain? Set start_date to the day your warmup service went+ # on: no cold email for min_days, then the cold cap climbs from+ # start_sends by daily_increase a day up to max_daily_sends. Replies are+ # never held. Check readiness any time with `harvey warmup`.+ warmup:+ start_date: "" # YYYY-MM-DD; blank = no ramp+ min_days: 14+ start_sends: 5+ daily_increase: 3+ dkim_selector: "" # only if your provider uses an unusual onelinkedin:enabled: false # explicit opt-in; credentials alone do not enable itmax_daily_connections: 20diff --git a/harvey/agents/sender.py b/harvey/agents/sender.pyindex 9eea509..cf8a99f 100644--- a/harvey/agents/sender.py+++ b/harvey/agents/sender.py@@ -18,7 +18,8 @@ from datetime import date, datetime, timedelta, timezonefrom harvey.brain import Brainfrom harvey.config import (- HarveyConfig, EnvConfig, compliance_footer_lines, compliance_notice, compliance_of,+ HarveyConfig, EnvConfig, cold_daily_cap, compliance_footer_lines, compliance_notice,+ compliance_of,)from harvey.gate import pre_send_checkfrom harvey.integrations.instantly import InstantlyClient@@ -28,6 +29,10 @@ from harvey.state import (HAND_SENT_REASON, MANUAL_SEND_KEY, MAYBE_SENT_PREFIX, StateManager,)+# A follow-up waits at least this long after the email it follows went out,+# whatever its schedule says.+MIN_FOLLOW_UP_GAP = timedelta(days=1)+logger = logging.getLogger("harvey.sender")# Max sends drained per heartbeat cycle — spreads volume through the day@@ -96,7 +101,7 @@ class Sender:return# Enforce daily send limit- max_sends = self.config.channels.email.max_daily_sends+ max_sends = cold_daily_cap(self.config.channels.email)sends_today = await self._count_sends_today()remaining = max_sends - sends_todayif remaining <= 0:@@ -253,7 +258,7 @@ class Sender:return# Check remaining daily send budget- max_sends = self.config.channels.email.max_daily_sends+ max_sends = cold_daily_cap(self.config.channels.email)sends_today = await self._count_sends_today()remaining = max_sends - sends_todayif remaining <= 0:@@ -464,6 +469,39 @@ class Sender:return self._with_footer(item["body"])return item["body"]+ async def _follow_up_order(self, item: dict) -> str | tuple[str, str] | None:+ """For a follow-up: "wait" until the email before it went out and its+ gap has passed, (status, error) when that email never will, else None.++ Without this, a step held for any reason (approval, a pause, a+ compliance hold, the warmup ramp) lets its follow-ups' scheduled+ times arrive first: a late "Approve all" sent the whole sequence in+ one go, or step 2 before step 1.+ """+ if item["kind"] != "sequence" or int(item["step"]) <= 1:+ return None+ prev = await self.state.get_previous_step(item)+ if prev is None:+ return None+ if prev["status"] in ("pending_review", "approved", "sending"):+ return "wait"+ if prev["status"] != "sent":+ return "cancelled", f"step {prev['step']} wasn't sent ({prev['status']})"++ def _at(value):+ try:+ return datetime.fromisoformat(str(value))+ except (TypeError, ValueError):+ return None+ planned, prev_planned, sent_at = _at(item["send_at"]), _at(prev["send_at"]), _at(prev["sent_at"])+ gap = MIN_FOLLOW_UP_GAP+ if planned and prev_planned:+ gap = max(gap, planned - prev_planned)+ if sent_at is None:+ return None+ now = datetime.now(timezone.utc).replace(tzinfo=None)+ return "wait" if now < sent_at + gap else None+async def _blocked(self, item: dict, prospect, allow_risky: bool) -> tuple[str, str] | None:"""Why this email must not go out, as (status, error), or None."""if prospect is None:@@ -507,16 +545,19 @@ class Sender:if budget <= 0:logger.info(f"Sender: daily send cap reached ({sent_today}/{max_daily}).")return+ # Cold email has its own cap under the warmup ramp; replies don't.+ cold_cap = cold_daily_cap(self.config.channels.email)+ cold_left = cold_cap - await self.state.count_outbox_sent_today(kind="sequence")now = datetime.now(timezone.utc).replace(tzinfo=None).isoformat()due = await self.state.get_outbox(status="approved", due_before=now, limit=budget * 3)- if self.precleared is not None:- # Cold emails held by an unavailable compliance check stay- # approved at the front of the queue and could fill the page- # above, so fetch replies (and any other unchecked kind) on their- # own too. Bounded: one extra query of the same size.+ if self.precleared is not None or cold_left <= 0:+ # Cold emails held (by an unavailable compliance check, or the+ # cold cap) stay approved at the front of the queue and could+ # fill the page above, so fetch replies (and any other kind) on+ # their own too. Bounded: one extra query of the same size.seen = {item["id"] for item in due}unchecked = await self.state.get_outbox(status="approved", due_before=now, limit=budget * 3,@@ -537,9 +578,13 @@ class Sender:# Set when Precleared can't be asked (allowance used up, network):# cold emails wait for a later cycle, replies still go out.compliance_paused = False+ held_cold = 0for item in due:if sent >= budget:break+ if item["kind"] == "sequence" and sent_cold >= cold_left:+ held_cold += 1+ continueneeds_check = self.precleared is not None and item["kind"] == "sequence"if needs_check and compliance_paused:continue@@ -550,6 +595,12 @@ class Sender:await self.state.update_outbox_item(item["id"], status=blocked[0], error=blocked[1])continue+ order = await self._follow_up_order(item)+ if order == "wait":+ continue+ if order:+ await self.state.update_outbox_item(item["id"], status=order[0], error=order[1])+ continue# Optional compliance check (compliance.precleared): one per# address, before the first cold email. Replies are never checked.@@ -658,6 +709,15 @@ class Sender:if self.send_pacing and sent < budget:await asyncio.sleep(random.uniform(*SEND_JITTER_SECONDS))+ if held_cold:+ warmup = getattr(self.config.channels.email, "warmup", None)+ days = warmup.days_in() if warmup is not None else None+ if days is not None and cold_cap < max_daily:+ logger.info(+ f"Sender: warmup day {days}: {held_cold} cold email(s) wait; today's "+ f"cold cap is {cold_cap}. Replies still go out. See `harvey warmup`.")+ else:+ logger.info(f"Sender: cold email cap reached for today ({cold_cap}).")if sent_cold:await self.state.remember_footer_lines(compliance_footer_lines(self.config))notice = compliance_notice(self.config)diff --git a/harvey/cli.py b/harvey/cli.pyindex c46361f..e584b47 100644--- a/harvey/cli.py+++ b/harvey/cli.py@@ -691,6 +691,76 @@ def cmd_retry_writes(args):asyncio.run(_run())+def cmd_warmup(args):+ """Check whether the sending domain is ready for cold email."""+ import os++ from dotenv import load_dotenv++ from harvey import deliverability as d+ from harvey.agents.handler import BOUNCE_COUNT_KEY+ from harvey.config import ConfigError, load_config+ from harvey.paths import PROJECT_ROOT+ from harvey.state import StateManager++ load_dotenv(PROJECT_ROOT / ".env")+ try:+ config = load_config()+ except ConfigError as e:+ print(f"\n {e}\n")+ raise SystemExit(1)+ email = config.channels.email+ sender = (os.getenv("SMTP_USERNAME", "").strip() if email.provider == "smtp" else "") \+ or config.persona.email+ domain = (args.domain or sender.rpartition("@")[2]).strip().lower().rstrip(".")+ if not d.DOMAIN_RE.match(domain):+ print("\n No valid sending domain found. Pass one: harvey warmup yourdomain.com\n")+ raise SystemExit(1)++ async def _history():+ state = StateManager()+ await state.init_db()+ return (await state.count_outbox_sent(),+ int(await state.get_setting(BOUNCE_COUNT_KEY) or 0))++ smtp_host = os.getenv("SMTP_HOST", "").strip() if email.provider == "smtp" else ""+ print(f"\n Deliverability check - {domain}")+ print(" " + "=" * 56)+ sections = [+ ("Authentication", [d.check_mx(domain), d.check_spf(domain),+ d.check_dkim(domain, email.warmup.dkim_selector),+ d.check_dmarc(domain)]),+ ("Reputation", [d.check_domain_age(domain), *d.check_domain_blocklists(domain)]+ + (d.check_ip_blocklists(smtp_host) if smtp_host else [])),+ ("Warmup & sending", [d.check_warmup(email.warmup, email.max_daily_sends),+ d.check_send_history(*asyncio.run(_history()))]),+ ]+ icons = {d.OK: "OK ", d.WARN: "WARN", d.FAIL: "FAIL", d.INFO: "info"}+ failed = warned = 0+ for title, checks in sections:+ print(f"\n {title}")+ for c in checks:+ failed += c.status == d.FAIL+ warned += c.status == d.WARN+ print(f" [{icons[c.status]}] {c.name:<26} {c.detail}")++ print("\n " + "=" * 56)+ if failed:+ print(f" NOT READY - fix the {failed} FAIL item(s) before any cold email.")+ elif warned:+ print(f" READY WITH CAVEATS - {warned} warning(s); keep volume low.")+ else:+ print(" READY - send within today's cap and watch bounces.")+ print("\n What DNS can't tell you (the real reputation signal):")+ print(" - Google Postmaster Tools: https://postmaster.google.com - add the domain;")+ print(" it shows Gmail's spam rate and domain reputation once you send volume.")+ print(" - Inbox placement: send one email to a seed test (mail-tester.com is free)")+ print(" and aim for 9/10+. Your warmup service's dashboard shows its inbox rate;")+ print(" wait for ~95%+ inbox for a week before relying on cold sends.\n")+ if failed:+ raise SystemExit(1)++def cmd_sending(args):"""Pause/resume the sending kill switch."""from harvey.state import StateManager@@ -853,6 +923,12 @@ def main():choices=["pause", "resume", "status"])sub.set_defaults(func=cmd_sending)+ sub = subparsers.add_parser(+ "warmup", help="Check if your sending domain is set up and warmed up for cold email")+ sub.add_argument("domain", nargs="?", default="",+ help="Domain to check (default: your sending mailbox's domain)")+ sub.set_defaults(func=cmd_warmup)+# harvey usagesub = subparsers.add_parser("usage", help="Show brain usage and quota (Claude or Codex)")sub.add_argument("--days", type=int, default=30, help="Breakdown window (default: 30)")diff --git a/harvey/config.py b/harvey/config.pyindex 5148535..6b736b8 100644--- a/harvey/config.py+++ b/harvey/config.py@@ -3,7 +3,7 @@import loggingimport osimport re-from datetime import time as _time+from datetime import date as _date, time as _timefrom pathlib import Pathimport yaml@@ -68,6 +68,62 @@ class ICPConfig(BaseModel):geo_coordinates: dict[str, str] = {}+class WarmupConfig(BaseModel):+ """Cold-email ramp for a new domain or mailbox.++ Harvey doesn't run a warmup network itself; that needs a pool of real+ inboxes (Instantly, Lemwarm, Mailreach...). This is the other half: no+ cold email goes out for ``min_days`` after ``start_date``, then the cold+ cap climbs from ``start_sends`` by ``daily_increase`` a day until it+ reaches ``max_daily_sends``. Replies are never held. Empty+ ``start_date`` means no ramp.+ """++ start_date: str = "" # YYYY-MM-DD the warmup service was switched on+ min_days: int = 14 # warmup-only days before any cold email+ start_sends: int = 5 # cold-email cap on the first sending day+ daily_increase: int = 3 # added to the cap each day after that+ dkim_selector: str = "" # for `harvey warmup`, if not a common one++ @field_validator("start_date", "dkim_selector", mode="before")+ @classmethod+ def _blank_is_empty(cls, v):+ return "" if v is None else v++ @field_validator("start_date")+ @classmethod+ def _valid_date(cls, v: str) -> str:+ v = (v or "").strip()+ if v:+ try:+ _date.fromisoformat(v)+ except ValueError:+ raise ValueError(f"warmup.start_date '{v}' must be YYYY-MM-DD.")+ return v++ @field_validator("min_days", "start_sends", "daily_increase")+ @classmethod+ def _non_negative(cls, v: int) -> int:+ if v < 0:+ raise ValueError("warmup values must be >= 0")+ return v++ def days_in(self, today: _date | None = None) -> int | None:+ """Days since warmup started, or None when no ramp is configured."""+ if not self.start_date:+ return None+ return ((today or _date.today()) - _date.fromisoformat(self.start_date)).days++ def daily_cap(self, ceiling: int, today: _date | None = None) -> int:+ """Today's cold-email cap under the ramp (never above ``ceiling``)."""+ days = self.days_in(today)+ if days is None:+ return ceiling+ if days < self.min_days:+ return 0+ return min(ceiling, self.start_sends + (days - self.min_days) * self.daily_increase)++class EmailChannelConfig(BaseModel):enabled: bool = True# "instantly" (legacy), "gmail" (Gmail/Workspace via API — recommended),@@ -86,6 +142,8 @@ class EmailChannelConfig(BaseModel):# Kill switch: pause all sending when bounces exceed this fraction of# sent mail (measured over the trailing sends). 0 disables the switch.max_bounce_rate: float = 0.05+ # New domain? Ramp cold email up slowly (see WarmupConfig).+ warmup: WarmupConfig = WarmupConfig()@field_validator("max_daily_sends")@classmethod@@ -94,6 +152,19 @@ class EmailChannelConfig(BaseModel):raise ValueError("max_daily_sends must be >= 0")return v+ def cold_daily_cap(self, today: _date | None = None) -> int:+ """Today's cap on cold (sequence) email: max_daily_sends, throttled+ by the warmup ramp. Replies count only toward max_daily_sends."""+ return self.warmup.daily_cap(self.max_daily_sends, today)+++def cold_daily_cap(email_config, today: _date | None = None) -> int:+ """cold_daily_cap for any email config, including ones without a ramp."""+ warmup = getattr(email_config, "warmup", None)+ if isinstance(warmup, WarmupConfig):+ return warmup.daily_cap(email_config.max_daily_sends, today)+ return email_config.max_daily_sends+def legacy_sending_held(config) -> bool:"""True when Instantly is the provider and approval is required.diff --git a/harvey/deliverability.py b/harvey/deliverability.pynew file mode 100644index 0000000..2f3f9be--- /dev/null+++ b/harvey/deliverability.py@@ -0,0 +1,233 @@+"""Deliverability readiness - is this sending domain safe to cold email from?++Everything here is free and read-only: public DNS, RDAP, DNS blocklists, and+Harvey's own send history. None of it can measure inbox reputation directly+(only mailbox providers know that), so the report also points at the two+things that can: Google Postmaster Tools and an inbox-placement test.+"""++import re+from dataclasses import dataclass+from datetime import date, datetime++import dns.exception+import dns.resolver+import httpx++OK, WARN, FAIL, INFO = "ok", "warn", "fail", "info"++# Selectors used by the common mailbox providers, tried in order when the+# operator hasn't named one (warmup.dkim_selector).+COMMON_DKIM_SELECTORS = (+ "google", "default", "selector1", "selector2", "k1", "k2", "s1", "s2",+ "mail", "dkim", "fm1", "fm2", "fm3", "zoho", "zmail", "mxvault",+ "protonmail", "protonmail2", "mandrill", "smtp", "sig1", "everlytickey1",+)++# (zone, how a "query refused" answer looks) - public resolvers like 8.8.8.8+# are blocked by these lists and get a sentinel answer instead of a verdict.+DOMAIN_BLOCKLISTS = (+ ("dbl.spamhaus.org", lambda ip: ip.startswith("127.255.255.")),+ ("multi.surbl.org", lambda ip: ip == "127.0.0.1"),+ ("multi.uribl.com", lambda ip: ip == "127.0.0.1"),+)+IP_BLOCKLISTS = (+ ("zen.spamhaus.org", lambda ip: ip.startswith("127.255.255.")),+ ("bl.spamcop.net", lambda ip: False),+)++# Where to look a domain or IP up by hand when a list refuses public DNS.+MANUAL_LOOKUP = {+ "dbl.spamhaus.org": "https://check.spamhaus.org",+ "zen.spamhaus.org": "https://check.spamhaus.org",+ "multi.surbl.org": "https://www.surbl.org/surbl-analysis",+ "multi.uribl.com": "https://admin.uribl.com/",+ "bl.spamcop.net": "https://www.spamcop.net/bl.shtml",+}++MIN_DOMAIN_AGE_DAYS = 30+GOOD_DOMAIN_AGE_DAYS = 90+MAX_BOUNCE_RATE = 0.03+MIN_SENDS_FOR_RATES = 20+++@dataclass+class Check:+ name: str+ status: str+ detail: str+++DOMAIN_RE = re.compile(r"^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$")+++class LookupFailed(Exception):+ """DNS couldn't answer (timeout, no reachable server): not the same as+ 'no such record', so a check reports it as unknown, never as missing."""+++def _resolve(name: str, rtype: str):+ try:+ return list(dns.resolver.resolve(name, rtype, lifetime=8))+ except (dns.resolver.NXDOMAIN, dns.resolver.NoAnswer):+ return []+ except dns.exception.DNSException as e:+ raise LookupFailed(type(e).__name__) from e+++def _txt(name: str) -> list[str]:+ return [b"".join(r.strings).decode("utf-8", "replace") for r in _resolve(name, "TXT")]+++def _a(name: str) -> list[str]:+ return [r.address for r in _resolve(name, "A")]+++def _unknown(name: str, e: LookupFailed) -> Check:+ return Check(name, INFO, f"Couldn't look this up ({e}). Check your connection and run again.")+++def check_mx(domain: str) -> Check:+ try:+ mx = sorted(_resolve(domain, "MX"), key=lambda r: r.preference)+ except LookupFailed as e:+ return _unknown("MX", e)+ if not mx:+ return Check("MX", FAIL, "No MX record - replies and bounces have nowhere to go.")+ return Check("MX", OK, ", ".join(str(r.exchange).rstrip(".") for r in mx[:3]))+++def check_spf(domain: str) -> Check:+ try:+ records = [t for t in _txt(domain) if t.lower().startswith("v=spf1")]+ except LookupFailed as e:+ return _unknown("SPF", e)+ if not records:+ return Check("SPF", FAIL, "No SPF record. Add the TXT record your mail provider gives you.")+ if len(records) > 1:+ return Check("SPF", FAIL, f"{len(records)} SPF records - receivers treat that as no SPF. Merge them.")+ spf = records[0]+ terms = spf.lower().split()+ if "+all" in terms or "all" in terms:+ return Check("SPF", FAIL, f"'+all' lets anyone send as you: {spf}")+ lookups = sum(t.lstrip("+-~?").split(":")[0].split("=")[0] in+ ("include", "a", "mx", "ptr", "exists", "redirect") for t in terms)+ if lookups > 10:+ # Top-level terms only; includes add their own lookups on top.+ return Check("SPF", FAIL, f"{lookups} DNS lookups (limit is 10) - SPF will permerror.")+ if "?all" in terms:+ return Check("SPF", WARN, f"'?all' is neutral; use '~all' or '-all': {spf}")+ return Check("SPF", OK, spf)+++def check_dmarc(domain: str) -> Check:+ try:+ records = [t for t in _txt(f"_dmarc.{domain}") if t.lower().startswith("v=dmarc1")]+ except LookupFailed as e:+ return _unknown("DMARC", e)+ if not records:+ return Check("DMARC", FAIL, "No DMARC record. Gmail and Yahoo require one for bulk senders. "+ f"Start with TXT _dmarc.{domain} = \"v=DMARC1; p=none; rua=mailto:you@{domain}\"")+ tags = dict(+ part.strip().split("=", 1) for part in records[0].split(";") if "=" in part+ )+ policy = tags.get("p", "").strip().lower()+ if policy == "none":+ return Check("DMARC", WARN, f"p=none (monitoring only) - fine while warming; "+ f"move to quarantine once reports look clean. {records[0]}")+ return Check("DMARC", OK, records[0])+++def check_dkim(domain: str, selector: str = "") -> Check:+ selectors = (selector,) if selector else COMMON_DKIM_SELECTORS+ for sel in selectors:+ try:+ records = _txt(f"{sel}._domainkey.{domain}")+ except LookupFailed as e:+ return _unknown("DKIM", e)+ for record in records:+ if "p=" in record.replace(" ", "") and "p=;" not in record.replace(" ", "") + ";":+ return Check("DKIM", OK, f"selector '{sel}' found")+ if selector:+ return Check("DKIM", FAIL, f"No DKIM key at {selector}._domainkey.{domain}.")+ return Check("DKIM", WARN, "No key at any common selector. If your provider uses a custom one, "+ "set channels.email.warmup.dkim_selector; otherwise turn DKIM on in your provider.")+++def check_domain_age(domain: str) -> Check:+ try:+ r = httpx.get(f"https://rdap.org/domain/{domain}", timeout=15, follow_redirects=True)+ r.raise_for_status()+ events = r.json().get("events", [])+ except Exception as e:+ return Check("Domain age", INFO, f"Couldn't look up registration date ({type(e).__name__}).")+ registered = next((e.get("eventDate") for e in events if e.get("eventAction") == "registration"), None)+ if not registered:+ return Check("Domain age", INFO, "Registry didn't publish a registration date.")+ try:+ age = (date.today() - datetime.fromisoformat(registered.replace("Z", "+00:00")).date()).days+ except ValueError:+ return Check("Domain age", INFO, f"Registry gave an unreadable date ({registered[:40]}).")+ status = FAIL if age < MIN_DOMAIN_AGE_DAYS else WARN if age < GOOD_DOMAIN_AGE_DAYS else OK+ note = {FAIL: " - brand-new domains are distrusted; warm only, no cold email yet.",+ WARN: " - still young; keep volume low.", OK: ""}[status]+ return Check("Domain age", status, f"{age} days (registered {registered[:10]}){note}")+++def _blocklist_checks(query: str, label: str, lists) -> list[Check]:+ checks = []+ for zone, refused in lists:+ try:+ hits = _a(f"{query}.{zone}")+ except LookupFailed as e:+ checks.append(_unknown(f"{label} {zone}", e))+ continue+ if not hits:+ checks.append(Check(f"{label} {zone}", OK, "not listed"))+ elif any(refused(ip) for ip in hits):+ checks.append(Check(f"{label} {zone}", INFO,+ "list refused the query (common via public DNS like 8.8.8.8) - "+ f"check manually at {MANUAL_LOOKUP.get(zone, zone)}"))+ else:+ checks.append(Check(f"{label} {zone}", FAIL, f"LISTED ({', '.join(hits)})"))+ return checks+++def check_domain_blocklists(domain: str) -> list[Check]:+ return _blocklist_checks(domain, "Blocklist", DOMAIN_BLOCKLISTS)+++def check_ip_blocklists(smtp_host: str) -> list[Check]:+ try:+ ips = _a(smtp_host)+ except LookupFailed as e:+ return [_unknown("Sending IP", e)]+ if not ips:+ return [Check("Sending IP", INFO, f"Couldn't resolve {smtp_host}.")]+ reversed_ip = ".".join(reversed(ips[0].split(".")))+ return _blocklist_checks(reversed_ip, f"IP {ips[0]}", IP_BLOCKLISTS)+++def check_warmup(warmup, ceiling: int, today: date | None = None) -> Check:+ days = warmup.days_in(today)+ if days is None:+ return Check("Warmup", WARN, "No warmup start date set, so sends aren't ramped. Once your warmup "+ "service is on, set channels.email.warmup.start_date: YYYY-MM-DD.")+ if days < 0:+ return Check("Warmup", WARN, f"Starts {warmup.start_date} (in {-days} days).")+ if days < warmup.min_days:+ return Check("Warmup", FAIL, f"Day {days} of {warmup.min_days} - warming only, no cold email "+ f"until {warmup.min_days - days} more day(s) pass.")+ cap = warmup.daily_cap(ceiling, today)+ full_on = warmup.min_days + max(0, -(-(ceiling - warmup.start_sends) // max(warmup.daily_increase, 1)))+ ramp = "full volume" if cap >= ceiling else f"reaches {ceiling}/day on day {full_on}"+ return Check("Warmup", OK, f"Day {days}: today's cap is {cap}/day ({ramp}). "+ "Keep the warmup service running alongside Harvey.")+++def check_send_history(total_sent: int, bounces: int) -> Check:+ if total_sent < MIN_SENDS_FOR_RATES:+ return Check("Bounce rate", INFO, f"{bounces} bounces / {total_sent} sent - too few sends to judge yet.")+ rate = bounces / total_sent+ status = OK if rate <= MAX_BOUNCE_RATE else FAIL+ return Check("Bounce rate", status, f"{rate:.1%} ({bounces}/{total_sent}); keep it under {MAX_BOUNCE_RATE:.0%}.")diff --git a/harvey/state.py b/harvey/state.pyindex 853b20f..ebb9d0d 100644--- a/harvey/state.py+++ b/harvey/state.py@@ -1105,13 +1105,29 @@ class StateManager:) as cursor:return (await cursor.fetchone())[0]- async def count_outbox_sent_today(self) -> int:+ async def count_outbox_sent_today(self, kind: str | None = None) -> int:+ """Emails sent today; only one kind ("sequence", "reply") if given."""+ sql = "SELECT COUNT(*) FROM outbox WHERE status = 'sent' AND date(sent_at) = date('now')"+ params: tuple = ()+ if kind:+ sql += " AND kind = ?"+ params = (kind,)async with self._connect() as db:+ async with db.execute(sql, params) as cursor:+ return (await cursor.fetchone())[0]++ async def get_previous_step(self, item: dict) -> dict | None:+ """The email a sequence follow-up follows (same campaign and person,+ one step earlier), or None."""+ async with self._connect() as db:+ db.row_factory = aiosqlite.Rowasync with db.execute(- "SELECT COUNT(*) FROM outbox WHERE status = 'sent' "- "AND date(sent_at) = date('now')"+ "SELECT * FROM outbox WHERE prospect_id = ? AND campaign_id = ? "+ "AND kind = 'sequence' AND step = ? ORDER BY created_at DESC LIMIT 1",+ (item["prospect_id"], item.get("campaign_id") or "", int(item["step"]) - 1),) as cursor:- return (await cursor.fetchone())[0]+ row = await cursor.fetchone()+ return dict(row) if row else Noneasync def find_outbox_by_message_id(self, message_id: str) -> dict | None:if not message_id:diff --git a/tests/test_followup_spacing.py b/tests/test_followup_spacing.pynew file mode 100644index 0000000..20ef451--- /dev/null+++ b/tests/test_followup_spacing.py@@ -0,0 +1,54 @@+"""A follow-up never goes out before, or too soon after, the email it follows.++Sequence emails are staged with send times days apart. If step 1 is held+(awaiting approval, sending paused, a compliance hold, a warmup ramp), the+follow-ups' scheduled times still arrive; without spacing, approving late+sends the whole sequence at once, or step 2 before step 1.+"""++from datetime import datetime, timedelta, timezone++import pytest++from tests.test_outbox_native import ( # noqa: F401 (state is a fixture)+ FakeProvider, make_sender, seed_campaign, seed_prospect, state,+)+++def _now():+ return datetime.now(timezone.utc).replace(tzinfo=None)+++async def test_approving_a_week_late_sends_step_one_only(state):+ pid = await seed_prospect(state)+ await seed_campaign(state, [pid]) # steps 1 and 2, 3 days apart+ sender = make_sender(state, FakeProvider())+ await sender._run_native() # staged, awaiting approval+ week_ago = _now() - timedelta(days=7)+ for item in await state.get_outbox(status="pending_review"):+ await state.update_outbox_item(+ item["id"], send_at=(week_ago + timedelta(days=3 * (item["step"] - 1))).isoformat())+ await state.approve_outbox() # "Approve all", a week late++ provider = FakeProvider()+ await make_sender(state, provider)._drain_due()+ assert [m["subject"] for m in provider.sent] == ["hi Jane"] # step 1 only+ step2 = next(i for i in await state.get_outbox(status="approved") if i["step"] == 2)+ assert step2 # waits its 3 days after step 1 actually went out+++async def test_a_follow_up_whose_first_email_never_went_out_waits(state):+ pid = await seed_prospect(state, status="queued")+ await state.add_outbox_item(+ prospect_id=pid, to_email="[email protected]", subject="s1", body="One. Question?",+ send_at=(_now() + timedelta(days=1)).isoformat(), status="approved",+ campaign_id="c1", step=1)+ await state.add_outbox_item(+ prospect_id=pid, to_email="[email protected]", subject="s2", body="Two. Question?",+ send_at=(_now() - timedelta(minutes=1)).isoformat(), status="approved",+ campaign_id="c1", step=2)+ provider = FakeProvider()+ await make_sender(state, provider)._drain_due()+ assert provider.sent == []diff --git a/tests/test_precleared.py b/tests/test_precleared.pyindex 50d456b..3cbf372 100644--- a/tests/test_precleared.py+++ b/tests/test_precleared.py@@ -76,14 +76,22 @@ def with_check(sender, transport, api_key=""):return sender-async def queue(state, pid, step=1, kind="sequence", to="[email protected]"):+async def queue(state, pid, step=1, kind="sequence", to="[email protected]", campaign="c1"):return await state.add_outbox_item(prospect_id=pid, to_email=to, subject="hello",body="Fine body. Question?", send_at=_now_iso(), status="approved",- campaign_id="c1" if kind == "sequence" else "", step=step, kind=kind,+ campaign_id=campaign if kind == "sequence" else "", step=step, kind=kind,)+async def days_pass(state, days=4):+ """Move every sent email back in time, so a follow-up's gap has passed."""+ async with aiosqlite.connect(state.db_path) as db:+ await db.execute("UPDATE outbox SET sent_at = datetime(sent_at, ?) "+ "WHERE status = 'sent'", (f"-{days} days",))+ await db.commit()++async def logged_receipts(state):async with aiosqlite.connect(state.db_path) as db:async with db.execute(@@ -292,6 +300,7 @@ async def test_one_check_per_address(state):await queue(state, pid, step=1)await sender._drain_due()+ await days_pass(state)await queue(state, pid, step=2)await sender._drain_due()@@ -309,7 +318,8 @@ async def test_blocked_verdict_is_remembered_for_later_steps(state):await queue(state, pid, step=1)await sender._drain_due()- await queue(state, pid, step=2)+ # Another campaign's first email to the same address: no second check.+ await queue(state, pid, step=1, campaign="c2")await sender._drain_due()assert provider.sent == []diff --git a/tests/test_warmup.py b/tests/test_warmup.pynew file mode 100644index 0000000..bd12def--- /dev/null+++ b/tests/test_warmup.py@@ -0,0 +1,178 @@+"""Warmup: the cold-email ramp for a new domain, and `harvey warmup`'s+read-only deliverability checks.++Based on community PR #18 by Tariz Shahid.+"""++from datetime import date, datetime, timedelta, timezone+from types import SimpleNamespace+from unittest.mock import AsyncMock++import dns.exception+import pytest++from harvey import deliverability as d+from harvey.config import EmailChannelConfig, WarmupConfig+from tests.test_outbox_native import ( # noqa: F401 (state is a fixture)+ FakeProvider, make_sender, seed_prospect, state,+)+++# ── The ramp ──++def test_no_start_date_means_no_ramp():+ assert WarmupConfig().daily_cap(30) == 30+ assert EmailChannelConfig(max_daily_sends=12).cold_daily_cap() == 12+++def test_ramp_holds_then_climbs_to_ceiling():+ w = WarmupConfig(start_date="2026-10-01", min_days=14, start_sends=5, daily_increase=3)+ cap = lambda day: w.daily_cap(30, date(2026, 10, day)) # noqa: E731+ assert [cap(1), cap(14)] == [0, 0] # warming only+ assert [cap(15), cap(16), cap(20)] == [5, 8, 20]+ assert cap(31) == 30 # never above max_daily_sends+++def test_bad_or_blank_settings():+ with pytest.raises(ValueError):+ WarmupConfig(start_date="10/01/2026")+ with pytest.raises(ValueError):+ WarmupConfig(min_days=-1)+ assert WarmupConfig(start_date=None).start_date == "" # left blank in YAML+++def _now_iso(**delta):+ return (datetime.now(timezone.utc).replace(tzinfo=None) + timedelta(**delta)).isoformat()+++async def _approved(state, pid, kind, step=1, campaign="c1"):+ await state.add_outbox_item(+ prospect_id=pid, to_email="[email protected]",+ subject="hello there", body="A short, plain note. Question?", send_at=_now_iso(),+ status="approved", campaign_id=campaign if kind == "sequence" else "", step=step, kind=kind)+++def _ramped_sender(state, provider, days_in, **ramp):+ sender = make_sender(state, provider)+ start = (date.today() - timedelta(days=days_in)).isoformat()+ sender.config.channels.email.warmup = WarmupConfig(start_date=start, **ramp)+ return sender+++async def test_while_warming_cold_email_waits_but_replies_go(state):+ cold = await seed_prospect(state, email="[email protected]", status="queued")+ await _approved(state, cold, "sequence")+ warm = await seed_prospect(state, email="[email protected]", status="replied")+ await state.add_outbox_item(+ prospect_id=warm, to_email="[email protected]", subject="Re: hi",+ body="Sure, Tuesday works.", send_at=_now_iso(), status="approved", kind="reply")+ provider = FakeProvider()+ try:+ await _ramped_sender(state, provider, days_in=3, min_days=14)._drain_due()+ finally:+ make_sender(state, provider).config.channels.email.warmup = WarmupConfig()+ assert [m["to"] for m in provider.sent] == ["[email protected]"]+ assert len(await state.get_outbox(status="approved")) == 1 # the cold one waits+++async def test_after_warming_cold_email_is_capped_at_todays_ramp(state):+ for n in range(4):+ pid = await seed_prospect(state, email=f"p{n}@acme.com", status="queued")+ await state.add_outbox_item(+ prospect_id=pid, to_email=f"p{n}@acme.com", subject="hello there",+ body="A short, plain note. Question?", send_at=_now_iso(), status="approved",+ campaign_id="c1", step=1)+ provider = FakeProvider()+ try:+ # Day 15 of a 14-day warmup: start_sends + one day's increase = 2.+ await _ramped_sender(state, provider, days_in=15, min_days=14, start_sends=1,+ daily_increase=1)._drain_due()+ finally:+ make_sender(state, provider).config.channels.email.warmup = WarmupConfig()+ assert len(provider.sent) == 2+++async def test_instantly_adds_no_more_leads_than_todays_ramp(state, monkeypatch):+ from harvey.agents.sender import Sender+ from harvey.config import EnvConfig+ from harvey.models.campaign import Campaign, EmailStep+ ids = [await seed_prospect(state, email=f"p{n}@acme.com", status="queued") for n in range(6)]+ warm_start = (date.today() - timedelta(days=14)).isoformat()+ config = SimpleNamespace(channels=SimpleNamespace(email=EmailChannelConfig(+ provider="instantly", require_approval=False, max_daily_sends=50,+ warmup=WarmupConfig(start_date=warm_start, min_days=14, start_sends=3))))+ sender = Sender(None, state, config, EnvConfig())+ sender.instantly = AsyncMock()+ sender.instantly.set_campaign_emails.return_value = {}+ sender.instantly.add_leads.return_value = {}+ await sender._deploy_campaign(Campaign(+ id="c", name="Draft", instantly_campaign_id="existing", prospect_ids=ids,+ sequence=[EmailStep(step=1, subject="a note", body="Would this help?")]))+ leads = sender.instantly.add_leads.await_args.args[1]+ assert len(leads) == 3+++# ── The checks (DNS stubbed) ──++def _txt(records):+ return lambda name: records.get(name, [])+++def test_spf_checks(monkeypatch):+ monkeypatch.setattr(d, "_txt", _txt({"a.com": ["v=spf1 include:_spf.google.com ~all"]}))+ assert d.check_spf("a.com").status == d.OK+ monkeypatch.setattr(d, "_txt", _txt({"a.com": ["v=spf1 +all"]}))+ assert d.check_spf("a.com").status == d.FAIL+ monkeypatch.setattr(d, "_txt", _txt({"a.com": ["v=spf1 -all", "v=spf1 ~all"]}))+ assert d.check_spf("a.com").status == d.FAIL+ monkeypatch.setattr(d, "_txt", _txt({}))+ assert d.check_spf("a.com").status == d.FAIL+++def test_dmarc_and_dkim(monkeypatch):+ monkeypatch.setattr(d, "_txt", _txt({+ "_dmarc.a.com": ["v=DMARC1; p=none; rua=mailto:[email protected]"],+ "google._domainkey.a.com": ["v=DKIM1; k=rsa; p=MIIBIjANBg"],+ "s1._domainkey.b.com": ["v=DKIM1; p="], # revoked key+ }))+ assert d.check_dmarc("a.com").status == d.WARN+ assert d.check_dmarc("b.com").status == d.FAIL+ assert d.check_dkim("a.com").status == d.OK+ assert d.check_dkim("b.com", "s1").status == d.FAIL+++def test_blocklist_refusal_is_not_a_listing(monkeypatch):+ answers = {"a.com.dbl.spamhaus.org": ["127.255.255.254"],+ "a.com.multi.surbl.org": ["127.0.0.2"]}+ monkeypatch.setattr(d, "_a", lambda name: answers.get(name, []))+ by_zone = {c.name.split()[-1]: c.status for c in d.check_domain_blocklists("a.com")}+ assert by_zone == {"dbl.spamhaus.org": d.INFO, "multi.surbl.org": d.FAIL,+ "multi.uribl.com": d.OK}+++def test_a_dns_timeout_is_unknown_not_missing(monkeypatch):+ def timeout(*a, **k):+ raise dns.exception.Timeout()+ monkeypatch.setattr(d.dns.resolver, "resolve", timeout)+ checks = [d.check_mx("a.com"), d.check_spf("a.com"), d.check_dkim("a.com"),+ d.check_dmarc("a.com"), *d.check_domain_blocklists("a.com"),+ *d.check_ip_blocklists("smtp.a.com")]+ assert {c.status for c in checks} == {d.INFO}+++def test_warmup_check_reports_progress():+ w = WarmupConfig(start_date="2026-10-01", min_days=14)+ assert d.check_warmup(w, 30, date(2026, 10, 5)).status == d.FAIL+ assert d.check_warmup(w, 30, date(2026, 10, 20)).status == d.OK+ assert d.check_warmup(WarmupConfig(), 30).status == d.WARN++[email protected]("domain, ok", [+ ("acme.com", True), ("mail.acme.co.uk", True),+ ("acme", False), ("acme.com/../x", False), ("-acme.com", False), ("", False),+])+def test_only_real_domain_names_are_checked(domain, ok):+ assert bool(d.DOMAIN_RE.match(domain)) is ok