email-deliverability

Email Deliverability

Overview

This skill runs the health side of a cold email program once the domains and mailboxes exist. It produces one of two deliverables. When something broke, an incident recovery plan: a verdict, what stops today, causes ranked with the check that confirms or clears each, why the open rate cannot decide it, list re-validation with its cost, and a dated day-by-day restart calendar with sends per inbox and a gate on every step. For routine checks, a deliverability health report: authentication and compliance status per domain, list validation results with an action for every row, seed placement results, domain health with a green, yellow or red status, blocklist checks, open incidents with their runbook step, and the stop rules in force.

It prevents five expensive mistakes: answering an incident with a long audit instead of a dated plan, sending an unvalidated list and burning a domain on bounces, reading "No data" in Postmaster Tools as "healthy", answering spam folder placement by buying more domains (the new domains get the same list and copy and burn the same way), and keeping a domain sending after Google's 0.3% spam line, which removes it from mitigation until it holds below 0.3% for 7 consecutive days.

The shared references/deliverability-primer.md holds the provider rules, bounce and complaint formulas, validation buckets, warmup sources and standing thresholds. This skill applies them; it does not restate them.

When to Use

• "Why are my emails going to spam?" or "my reply rate dropped".
• "Instantly paused my campaign for bounces" or "bounce rate is 4%".
• "Run a deliverability audit" or "weekly health check".
• "Validate this list before I send" or "what do I do with catch-alls?"
• "Do the Gmail and Yahoo bulk sender rules apply to cold email?" or "what changed with Outlook in 2025?"
• "Is my domain blacklisted?" or "how do I get delisted?"
• An SMTP code in a bounce: 5.7.27, 4.7.28, 4.7.32, 5.7.515, 5.7.606.
• "Open rates fell off a cliff" or "opens dropped and bounces jumped this week": write the incident recovery plan; check replies and seeds before trusting the open rate.

Use a different skill for nearby jobs:

Prerequisites

For an incident plan only the symptom numbers are required (inboxes, domains, daily cap, the rates that moved). Everything else becomes a confirming check in the plan or a labeled assumption.

Authoritative Foundations

Detail, dates and links: references/deliverability-primer.md and references/framework-notes.md.

Workflow

1. Classify the request

When the user gives symptom numbers, answer with the plan in the first reply. Restate their setup as counts (12 inboxes x 30 a day x 5 weekdays = 1,800 sends; 4% of that = 72 hard bounces), state at most 3 assumptions in one line, and put the facts that would change the ranking in the Diagnosis "Clears it" column, once. Do not open with a questionnaire.

2. Authentication and unsubscribe check

For every sending domain: one SPF record, DKIM signing on, one DMARC record with rua, From aligned, and a header test from every mailbox showing spf=pass, dkim=pass header.d=<domain>, dmarc=pass. Turn on the sequencer's unsubscribe header where it exists and confirm List-Unsubscribe-Post: List-Unsubscribe=One-Click in a raw test message. Every email body carries a plain opt-out line. Gate table: references/monitoring-and-testing.md section 1. When a check fails, put the exact records to publish in the report: the copy-paste SPF, DKIM and DMARC values and the Google Admin console DKIM path are in references/incident-runbooks.md R6.

3. Validate the list and route every result

Run validate_emails on every address last checked before the user's re-check window (ask for it; no source publishes one, so set it from the bounce rate of re-sent rows by age). Route each email_result per references/deliverability-primer.md section 5, then apply the extra rules in references/monitoring-and-testing.md section 2: send order by email_quality, catch-all rows in their own campaign, gateway-aware reporting from sc_mx_security_gateway.

4. Seed test before launch

Send the live touch 1 from one mailbox per domain to a seed at each provider the list uses (personal Gmail, Workspace, Outlook.com, Microsoft 365, Yahoo; read the mix from sc_mx_provider). Launch when it reaches the inbox at every seed provider; a provider in spam gets the spam-folder runbook first. Protocol: monitoring section 3.

5. Collect the weekly numbers

Per mailbox and per domain, last 7 days and last 200 sends: sends, hard bounces, soft bounces, replies, opt-outs, auto-pauses. Per domain: Postmaster compliance status and spam rate (or "No data"), Yahoo CFL complaints, DMARC pass share from rua reports. Weekly review agenda: monitoring section 6.

6. Check blocklists

Every sending domain on check.spamhaus.org (DBL). Then every other domain a recipient's filter sees in the message: the tracking host's domain (inst.<sending domain> sits on the sending domain; with no custom tracking domain, the sequencer's shared tracking domain), the main site in the signature, a calendar or booking link, and any other link. Check those on the Spamhaus DBL, SURBL (surbl.org lookup) and URIBL (admin.uribl.com), which list domains found in message bodies and links. A listed linked domain hurts every mailbox that carries the link. Dedicated or private IPs also go on Barracuda, SpamCop and Spamhaus IP lists. Workspace and Microsoft 365 senders do not own their IPs, so IP checks do not apply; say so in one line, not a table. Monitoring section 5.

7. Score each domain

A domain showing "No data" in Postmaster still needs bounces, seeds and replies in range to be green.

8. Diagnose the incident

Rank causes by evidence: the cause must explain every symptom given, be shared by every affected domain, and have changed inside the window. Four domains failing the same week share a cause (list, copy, tracking or linked domain, a DNS edit, a settings change). Each ranked cause carries the check that confirms it and the result that clears it, from references/recovery-plans.md section 2. The common combination, opens collapsing on every domain plus hard bounces at 2% or more at flat volume, ranks: bad or stale list batch; spam placement following it; tracking or linked domain flagged or broken; authentication broken by a DNS edit; Spamhaus DBL listing. A Postmaster spam rate under 0.1% does not clear spam placement: Google counts only mail that reached the inbox.

Confirm the incident owner: one named person with authority to pause any domain or campaign without asking anyone. Match the symptom in references/incident-runbooks.md (R1 bounce spike, R2 spam folder, R3 complaint spike, R4 blocklisted domain, R5 blocklisted IP, R6 authentication rejection, R7 Gmail 4.7.28 reputation deferral and other rate limits, R8 mailbox suspended, R9 measurement problem only). Contain first, then diagnose, fix, and resume only on the written resume condition. What stops in the first hour, and what keeps running (warmup at its current setting, the opt-out line, same-day suppression): references/recovery-plans.md section 4.

Keep a backup capacity plan in every health report (in an incident plan, one line inside the retire rule): which warmed reserve domains can take a paused domain's volume, and how many sends a day they cover. Never buy replacement domains during an incident before the cause is found; the new domains inherit the list and copy and burn the same way.

8a. Rule out a measurement problem

Opens are the weakest signal. Apple Mail Privacy Protection downloads remote content when a message arrives, whether or not anyone reads it; Outlook blocks automatic picture downloads by default; security filters open and click within seconds of delivery. A drop says something changed without saying what. Decide with seed placement, human replies per 1,000 sends against the pre-incident baseline, and hard bounces with their SMTP codes; every incident plan says so in three or four sentences.

8b. Write the dated recovery calendar

Build it from today's date with weekday names, following references/recovery-plans.md section 6:

Every row shows total sends a day (inboxes x sends per inbox). Define the numeric gate once, in a "Standard gate" line above the table: hard bounces under 2% over the last 200 sends (Berman's line, Instantly's window), zero 4.7.28, spam rate under 0.1% (Google's sender guidelines). Rows say "standard gate" plus anything that day adds (seed test in the inbox at every provider). Add the back-off rules (one step back on a 2% bounce rate, stop a domain on 5.7.28, 0.3% spam or a DBL listing) and the keep, rest or retire rule for each domain (references/recovery-plans.md section 6b). Reserve domains start warming only after the cause is written down. An incident plan restarts every inbox at 10, because placement is unproven until the seed tests pass.

9. Apply the stop rules

10. Six-month audit

Every six months, the DKIM rotation interval M3AAWG sets, run the five audit checks in references/monitoring-and-testing.md section 7: DNS records against the domain-infrastructure plan, DKIM key age (rotate at least every six months per M3AAWG), a DMARC rua review since the last audit for unknown senders in a report service (dmarcian, Postmark DMARC, Valimail Monitor or EasyDMARC, compared in section 8), a placement test across Google, Microsoft and Yahoo seeds, and caps against actual volume. Each row gets a run date, a result and a next due date in the report.

11. Write the report and hand off

Fill templates/incident-plan-template.md for an incident or templates/output-template.md for a health report, run scripts/check-output.py on it, and hand mailbox actions (pause, rest, retire, re-ramp) to inbox-setup, DNS fixes to domain-infrastructure, copy rewrites to cold-email-copywriting. In the report itself, describe each handoff by the work to be done ("re-ramp the two mailboxes from 10 a day"), never by a skill name or runbook number.

ScraperCity Implementation

Step A. Wallet. check_wallet() before any paid run; show the estimate and wait for a go-ahead on anything over about $5.

Step B. Validate.

validate_emails(emails=["[email protected]", "[email protected]", ...])
check_run_status(runId)          # first check after 30 s, then every 30 s
download_results(runId, outputPath="/abs/path/validated-ledgerline-wk49-20261207.csv")

CLI:

npx scrapercity email-validate [email protected] [email protected]
npx scrapercity status <runId>
npx scrapercity download <runId> -o validated.csv

REST: POST /api/v1/scrape/email-validator with {"emails": [...]}, poll GET /api/v1/scrape/status/{runId}, download GET /api/downloads/{runId}.

Read the CSV header row before mapping. Columns this skill uses: email_result, email_quality, sc_is_catch_all, sc_mx_provider, sc_mx_security_gateway.

Step C. Route results.

Step D. Replace invalid addresses on high-value accounts.

find_emails(contacts=[{"first_name": "Ray", "last_name": "Reyes", "domain": "reyesair.example"}, ...])

$0.05 per email found, free when nothing is found, and every found email is validated at lookup. REST: POST /api/v1/scrape/email-finder with the same contacts array. The CLI email-find command also reads a CSV with first_name,last_name,domain columns.

Step E. Split reporting by recipient provider. Group sends and replies by sc_mx_provider (Google, Microsoft, other) and by sc_mx_security_gateway. A provider or gateway segment with no replies while the others reply gets a seed test at that provider first.

Worked cost estimate (catalog prices, a 6,000-row list for next month):

Expected spend is lower: find_emails charges nothing for inputs it cannot find. Compare with the cost of one burned domain: a $11.08 domain, its 2 to 3 mailbox seats for the rest of the term, and 2 to 4 weeks of warmup (Berman) before a replacement can send.

Output Format

A. Incident recovery plan (something broke)

One Markdown plan following templates/incident-plan-template.md, under about 1,500 words. A setup line first: owner with pause authority, inboxes, domains, cap, sends a week, and at most 3 assumptions.

Owner defaults to "the outbound lead, unless you name someone else today"; the sequencer defaults to Instantly, with one line saying which two settings to find in any other sequencer (custom tracking domain, bounce auto-pause).

1. Verdict: the likeliest cause and why the user's numbers point to it, what stops today, the earliest restart date and its gate, the one decision needed.
2. Stop Now: dated bullets (pause, suppress bounces everywhere, quarantine the batch, no new domains, open tracking off, the bounce auto-pause lowered to 2% with its menu path) and what keeps running (warmup at its current setting, the opt-out line, same-day opt-out suppression).
3. Diagnosis: at least 3 causes ranked 1, 2, 3, each with why it fits, the result that confirms it and the result that clears it. Under it, the checks once, numbered, as commands (bounce log read by its text, dig lines, header test, blocklist lookups, a named seed test), then the fix for each ranked cause written out in full: SPF and DMARC records ready to paste, the Google Admin DKIM path, the tracking CNAME.
4. Measurement: three or four sentences on why opens cannot decide it (Apple Mail Privacy Protection, Outlook image blocking, security filters) and the three deciding signals: seed placement, replies per 1,000 sends, hard bounces with codes.
5. List Re-validation: rows, count, cost at $0.00169, routing per result.
6. Recovery Plan: the standard gate line once with its numbers and sources, then a dated table with weekday names, sends per inbox, total sends a day, and a gate per sending row ("standard gate" plus that day's extra).
7. Resume and Retire Rules: what to do when a gate is missed (without restating the gate numbers) and the keep, rest or retire rule, decided by seeds and bounces.
8. Next Check-in: date, time, the numbers to bring, decisions pending. Not a second list of what would change the ranking.

No six-month audit, records for causes the plan does not rank, monitoring dashboards or framework lists in an incident plan. Each check, gate and fact appears once.

B. Weekly health report

One Markdown report following templates/output-template.md:

1. Summary: period, domains in scope, statuses, incidents, what the user must decide.
2. Scope: domains, mailboxes, sequencer, period, the one owner with authority to pause any domain, and the backup capacity (warmed reserves and the sends a day they cover).
3. Authentication and Unsubscribe: per domain SPF, DKIM, DMARC, alignment, unsubscribe header, Postmaster compliance status. When a check fails, the exact records to publish follow the table.
4. List Validation: counts per result bucket with the action and cost.
5. Placement Tests: seed results per provider per domain.
6. Domain Health: per domain sends, bounce rate, spam rate, replies, status and action.
7. Blocklist Checks: every sending domain and every linked domain (tracking host, main site, booking link) on the Spamhaus DBL, SURBL and URIBL; dedicated IPs when there are any.
8. Incidents and Actions: incident type, trigger, action, owner, resume condition, status.
9. Stop Rules: each rule, its threshold, its source and whether it fired.
10. Six-Month Audit: the five checks, each with run date and next due date.
11. Next Review: date and checks.

Rules for both

• What was not checked goes in one line ("Not checked: SNDS, no dedicated IPs"). Never a table of "Not run" or "Not applicable" rows.
• The reader is the sender, not this repo: no file paths, runbook numbers (R1 to R9), section numbers, skill names or tool ids. Name the incident type and the product ("Email Validator"), and say "re-ramp the two mailboxes from 10 a day" instead of naming a skill.
• Label every number the user did not give as an assumption, and name the source of each threshold once by its document ("Google's sender guidelines", "Instantly help", "Alex Berman"), never a bare "(Google)".
• Every message, record or setting the plan tells the user to change is written out (the record value, the menu path), not "fix DNS".
• No self-grading checklist in the deliverable.

Quality Check

Incident recovery plan:

• The first reply is the plan; the user's numbers are restated as counts (sends a week, bounce count).
• At least 3 causes ranked in order, each with a confirming check and a clearing result; the rank 1 cause explains every symptom given.
• Stop Now is dated, keeps warmup at its current setting and the opt-out line, and buys no domains before the cause is written down.
• Measurement names Apple Mail Privacy Protection and says seeds, replies per 1,000 sends and bounces decide.
• Re-validation count x $0.00169 is computed right; catch-alls wait until the last step.
• Every calendar row has a date; totals equal inboxes x sends per inbox; restart at 10 to 20 a day (Berman); no step more than doubles (Google); the standard gate is defined once with its numbers.
• The checks are numbered commands; each ranked cause has its fix written out (records, Admin path, CNAME); the seed test names its tool or seed accounts.
• python3 scripts/check-output.py plan.md prints PASS (it also enforces the length cap).

Weekly health report:

• Every sending domain has a row in Authentication, Domain Health and Blocklist Checks.
• Every domain status follows the step 7 rules: 2% bounces or 0.3% spam is never green or yellow.
• Validation bucket counts add up to the total validated, and the cost uses $0.00169 per email.
• No row without valid status is in a main send file.
• Every incident names its type, an owner and a resume condition; Scope names one owner with pause authority and the backup capacity.
• Blocklist Checks cover every linked domain on the Spamhaus DBL, SURBL and URIBL, not only sending domains.
• Opens are never read alone: any open-rate drop is checked against replies first.
• "No data" from Postmaster is reported as no data, not as a pass.
• Opt-outs suppressed the same day in every tool, with the count.
• Six-Month Audit has all five checks with dates; the DKIM row shows key age under six months or a booked rotation; the placement row names Google, Microsoft and Yahoo.
• python3 scripts/check-output.py report.md prints PASS.

Common Pitfalls

Execution Artifacts

Related Skills

• domain-infrastructure fixes DNS and adds or replaces domains.
• inbox-setup pauses, rests, retires and re-ramps mailboxes on this skill's findings.
• sending-platforms wires suppression lists, auto-pause settings and webhooks.
• email-list-cleaner and cold-email-list produce the validated files this skill gates.
• cold-email-copywriting rewrites copy when R2 points at content.
• reply-handling processes opt-outs and spam replies the same day.
• cold-email-strategy adjusts volume and segments when a segment draws complaints.