reply-handling

Reply Handling

Overview

This skill turns a cold email inbox into a set of states with rules. Every reply gets one class from a fixed taxonomy, a response from the library (or a deliberate non-response), a deadline, a CRM state change and, when needed, a suppression entry. Referrals become new contacts: the named person's email is found with find_emails (it returns validated addresses), and their first email names the referrer in the subject and gives a reason to care written for their industry and job.

The mistakes it prevents: answering a positive reply the next day, an automated template sent to someone who wrote "this is spam, I'm reporting you", re-emailing someone who said "remove me", and a "talk to Sarah" referral that gets a thin note pointing at someone else's thread. These cost meetings that the list and the copy already paid for.

When to Use

• "How should I respond to these replies?" (one or more pasted replies: use the triage format).
• "Build a reply playbook", "write objection responses", "set up inbox rules".
• "What do we do with out-of-office and bounces?"
• Configuring lead statuses in Instantly, Smartlead, Lemlist, EmailBison or ManyReach and their CRM sync.
• An SDR or agency needs a response library and SLAs.

Use something else for nearby jobs:

Prerequisites

1. The offer and the meeting link or two proposed time slots.
2. The sending platform and CRM, and whether replies sync between them.
3. Who owns replies, their working hours and time zone.
4. A suppression list location that every sending tool reads (platform blocklist plus CRM field).
5. ScraperCity API key for referral capture (find_emails).
6. For pasted replies: each reply's text, the prospect's signature or location (for time zone), and the brief's offer and proof.
7. For a playbook, the settings no source publishes, which the user sets and the deliverable states: escalation owners and their time limits, the AI-label confidence threshold, how often the review queue is checked, the weekly sample size and the error rate that turns a class off, and how long to pause an out-of-office with no return date.

Authoritative Foundations

Workflow

1. Detect automatic replies before a human reads them

Check headers first, then text. Full rules in references/reply-taxonomy-and-routing.md.

Never send a sales reply to an automatic message.

Automation boundary: AI reply labels in Instantly or Smartlead may act alone only on Out of office (pause), hard bounce and help desk auto-acks (suppress) and polite Unsubscribe (suppress, optional removal line), and only when a header rule matched or your own classifier scores at or above the confidence threshold the user sets (neither vendor publishes a score). Hostile replies, unclear or two-intent replies, and Interested replies from target accounts always go to a person. Everything below the threshold goes to a human-review queue checked at an interval the user sets, and a weekly sample of auto-handled replies, sized by the user, measures misclassification. Rules: references/reply-taxonomy-and-routing.md section 6.

2. Classify every human reply into one class

Use the 15 classes in the taxonomy reference. When a reply fits two classes, take the one higher in this priority order: Hostile > Unsubscribe > Bounce > Interested > Referral > Objection > Not now > Wrong person > Other. An "interested, but talk to Sarah too" reply is Interested, with a referral note.

Hostile is a needs-review class set by trigger words, whatever else the reply says. Automation may suppress the address but never sends anything, not even the polite removal line:

"I'll report back" or "block out an hour" also trips it; a person clears a false alarm in seconds, and a template sent to a real complaint can't be recalled. Full list: references/reply-taxonomy-and-routing.md section 1b.

3. Respond within the SLA

Response times come from Berman: an interested reply within 5 minutes (follow-up guide), every other human reply within 2 to 4 business hours (templates page). Removals happen the same day in every tool. Escalation owners and their time limits are the user's settings; the deliverable states them in the Escalate to column.

In a triage, escalation rides the reply's own window: the AE or manager is alerted when the reply arrives and acts inside the same 5 minutes or 2 to 4 business hours, so the deliverable needs no new number. Hot replies (a meeting request, an accepted time, a price question) get 5 minutes during business hours for every account tier. Replies that arrive after hours are answered first thing the next business day in the prospect's time zone. Target account means a named account list agreed with sales (for example multi-location dental groups).

The Send value is the same word everywhere: "No reply" means nothing goes out; "Removal line (R24)" or "Removal line (R26), sent by a person" means exactly one line goes out. Never write "no sales reply" next to a draft.

4. Write the response from the library

Pick the response in references/response-library.md. Every draft you hand over must be sendable as written:

• No brackets and no blanks. The only variables allowed are the recipient's name and company as merge fields with a fallback, such as {{first_name|there}} and {{company|your team}}.
• Use only facts in the user's brief: their offer, prices, results, integrations. If the brief has no proof point, write the reply without one. Never leave "[client result]" for a rep to fill; a rushed rep sends it broken or makes one up.
• Two to three sentences (Berman's follow-up guide), never over 75 words, one ask at most, contractions, plain words. Interested replies get two specific times with a time zone, or the brief's booking link. No decks, PDFs, proposals or price sheets (Berman's templates page).
• Proposed times fall outside the prospect's busy hours. Restaurants: Toast's peak hours are 11am to 2pm and 5pm to 8pm (quick service) and 5pm to 10pm (casual dining), so offer 2:30pm to 4:30pm their time. Other industries: outside the business's posted rush, or the hours the user gives.

Class rules the drafts follow:

Every objection the user's brief or request names gets its own ready line in the deliverable, in this shape: acknowledge in under 10 words, one fact from the brief, an easy out or one ask.

5. Update the CRM state

Map each class to a lead status and a deal action. Full map in references/reply-taxonomy-and-routing.md.

6. Suppress

Add unsubscribe, hostile and hard-bounce addresses to the global suppression list in every sending tool and the CRM the same day they arrive (Berman: remove them immediately). That stays inside the 2 day unsubscribe limit in Yahoo's and Google's sender rules, which inbox placement depends on. A not-interested reply is suppressed from every sequence permanently, because the reply promised no follow-up. When someone says "take our company off", suppress the domain. In the deliverable, state only the rules the replies trigger (references/suppression-and-compliance.md).

7. Capture referrals

For "talk to Sarah Kim, she runs ops" or "I've left; try David":

1. Parse first name, last name, the job the referrer said they own, and the company domain (from the referrer's email domain if not given).
2. find_emails with contacts: [{"first_name": "Sarah", "last_name": "Kim", "domain": "acme.example"}]. Charged $0.05 only if found, and found addresses come back already validated. Run validate_emails ($0.00169) only on an address the referrer typed out.
3. Thank the referrer in one line (R10) and stop their sequence.
4. Send the referred person R11 as a new thread, not a forward:
   • Subject names the referrer ("Tom suggested I reach out").
   • Line 1: the referrer's name and the job they said this person owns.
   • Line 2: the problem the offer removes, in the terms of their industry and seat (for restaurant payroll, tip reporting across shifts; for a dental practice, front desk time). Name a problem, never a result or number the brief doesn't give.
   • Line 3: one proof or the price, from the brief.
   • Line 4: two times in their time zone or the booking link.
   • Never paste the original email underneath or quote the referrer's reply. Under 75 words, subject under 50 characters (Berman's limits for a cold email). Use "suggested" only if the referrer named this person.

If the person is not named ("talk to our marketing team"), run query_lead_database with companyDomain and a title filter to find the role holder, then find_emails if no email returns.

In a triage, the lookup is one clause in the referral's row: a full address from the referrer is used as given; a missing or cut-off one gets "address from ScraperCity Email Finder (name plus the company domain)". No call blocks, parameters or prices.

8. Review weekly

Count replies by class per campaign cell. Mostly "not interested" points at targeting (Berman's diagnosis table); many "already have a vendor" means the market buys and the offer needs sharpening (Lean B2B interview); unsubscribes above 0.5% of prospects mean the follow-ups are too aggressive or not relevant (follow-up guide). Pause the cell when spam complaints near Google's 0.1% or bounces pass 2%.

ScraperCity Implementation

MCP call for a batch of referrals collected over a week:

{
  "tool": "find_emails",
  "contacts": [
    {"first_name": "Sarah", "last_name": "Kim", "domain": "acmedental.example"},
    {"first_name": "David", "last_name": "Ruiz", "domain": "lonestarortho.example"},
    {"full_name": "Priya Shah", "company_name": "Northpaw Coffee"}
  ]
}

CLI: npx scrapercity email-find. REST: POST /api/v1/scrape/email-finder, then poll GET /api/v1/scrape/status/{runId} and download.

Worked cost estimate (one month, 2,600 contact campaign)

Both finders bill only on a hit, so the estimate is a ceiling: every lookup found.

Under $5, so no separate approval is needed; call check_wallet once a week.

Output Format

Pick the format by what the user asked for.

A. Pasted replies (one to about 25): a reply triage from templates/triage-template.md. Answer first, each fact once. Sections in order, nothing else:

1. One or two lines: the brief facts the drafts use (offer, price, proof) and the assumptions (platform, time zones). No notes about the process or what was or wasn't run.
2. ## Reply Triage: one table, one row per reply: | # | Reply | Class | Send | Within | CRM status | Suppress |. Send is "Draft N", "No reply", "Removal line (draft N), sent by a person" or "No reply; forwarded to" plus the owner's role. Within is the response window (5 minutes for hot replies, 2 to 4 business hours for other human replies). Pause, resume and nurture dates are exact, with the weekday. A referral row says where the referred person's address comes from in one clause.
3. ## Drafts: one ### N. Name, class heading per reply that gets one, the draft in a fenced text block. A new thread (the referred person) starts with a Subject: line naming the referrer.
4. ## Routing and SLAs, only when the user asked for routing, SLAs, inbox rules or setup: one table | Class | Owner | Escalate to | Automation |, one row per class the replies used (the response window already sits in the triage table). Then one line per platform setting the replies trigger, each a rule plus its menu path in Instantly and in Smartlead from references/reply-taxonomy-and-routing.md section 4, or only the platform the user named.
5. ## Open Items: at most 5 bullets: facts missing from the brief that a draft needed (no price, no proof), and one "Confirm:" line naming the settings the user owns (escalation owners, target-account list) without restating values from the tables. Write "None" if empty.

Leave out a Reason column and any rationale after a setting. Taxonomy, bounce or help-desk rules, OOO parsing, meeting reminders, weekly review and referral lookups appear only when a pasted reply or the request needs them.

B. A reply playbook ("build our reply process"): one Markdown file from templates/output-template.md, ## sections in order: Inbox Setup, Reply Taxonomy, Response Library, SLAs, CRM State Map, Suppression Rules, Auto-Reply Detection, Automation Boundaries, Referral Capture, Weekly Review. The SLAs table carries an Escalate to column; Automation Boundaries lists each class as auto, partial or never, the confidence threshold, the review queue, the hostile trigger words and the weekly misclassification sample. Response Library drafts sit in fenced text blocks under ### headings that name the class: one contains "Not interested", at least three name an objection, and the referral first email has a subject naming the referrer.

Rules for both formats:

• Send says the same thing in every table: "No reply" never sits next to a draft, and a removal line is listed as a removal line.
• State only the rules the replies trigger, as plain settings. No justification after a setting ("because...", "keeps the promise", "looks automated"); a playbook's Suppression Rules may give one operating reason per row.
• Every number is either from a named source, named in a few words ("5 minutes, Alex Berman"), or a value the user gave. A setting nobody published and the user did not give goes on the "Confirm:" line by name, with no invented default.
• No legal content: no laws, regulators, penalties or legal deadlines in any deliverable.
• No tool ids, JSON call blocks, per-call prices, file paths, skill names or source page names in the deliverable. Name a lookup in words ("ScraperCity Email Finder") once.
• No claim about what buyers "usually" or "most" do, and no cost, price or result for any vendor, competitor or tool unless the brief or ScraperCity's catalog states it.
• Response ids (R1, R25) may label drafts in a playbook; they never appear inside a draft.

Quality Check

python3 scripts/check-output.py deliverable.md reads either format. For a triage it enforces:

• Only the sections in Output Format A, and at most 5 Open Items bullets.
• Every row's Send matches the drafts: a draft exists for every "Draft N" and removal line, and none exists for a "No reply" row.
• Any reply containing a hostile trigger word (spam, report, lawyer, attorney, sue) is classed Hostile, never sent by automation.
• Hot rows (interested, price, accepted time) are answered within 5 minutes; a price draft says what the price depends on; an accepted-time draft says the invite is on its way.
• A referral draft opens with a Subject: line that names the referrer.
• No Reason column, no "because" outside the drafts, no JSON blocks, tool ids or per-lookup prices, no process notes, and no bounce or help-desk text unless a row needs it; no law names, source page names or file paths.

For a playbook it enforces:

• Every class has an SLA, a CRM state and a suppression decision; hostile, unsubscribe and bounce are suppressed.
• Every SLA row has an Escalate to value; every Interested row escalates to a named role with a time limit; hot replies are answered in 5 minutes or less.
• Unsubscribe and hostile rows say "No reply" or "Removal line", never "no sales reply", and a removal line has a draft.
• Automation Boundaries lets automation handle out of office and unsubscribe, keeps hostile and target-account interested replies with a person, lists hostile trigger words including spam and lawyer, states a confidence threshold, and names a weekly misclassification sample.
• At least 8 drafts, each 75 words or fewer, no "[" outside a {{merge|fallback}} field; the Not interested draft has no question; at least three objection drafts; the referral first email has a subject naming the referrer.
• Referral capture names the Email Finder; every suppression row has a deadline and an operating reason, and no deliverable names a law.

Also check by reading:

• Interested replies get two specific times in the prospect's time zone or a booking link.
• Every fact in a draft (price, result, integration, competitor gap) appears in the user's brief.
• No response sends a deck, PDF or price sheet; a price question gets what the price depends on, then a short walkthrough call with two times outside the prospect's busy hours.
• OOO replies pause rather than stop, and resume after the return date.

Common Pitfalls

Execution Artifacts

Related Skills

• cold-email-strategy defines the branches this skill executes.
• cold-email-copywriting writes the referral sequence and re-engagement copy.
• multi-channel-outreach calls interested contacts who go quiet.
• email-deliverability investigates bounce and complaint spikes this skill reports.
• sending-platforms configures statuses, stop rules and blocklists.
• crm-enricher, email-list-cleaner and decision-maker-finder keep contacts and referrals accurate.