Every reply gets read, one way or another.
Replies are polled from each mailbox’s IMAP inbox, classified, and — for an opt-out — wired straight into suppression. Team access is a Tier 1/2 dashboard concept, layered on top of the same account.
WarmHawk polls IMAP for replies to sends still awaiting one, classifies each reply (INTERESTED, NOT_INTERESTED, OUT_OF_OFFICE, AUTO_REPLY, LEFT_COMPANY, OPT_OUT, UNCLASSIFIED) via your BYOK AI key with a keyword-heuristic fallback, and automatically suppresses an OPT_OUT lead. Team invite/remove with flat permissions lives in the Tier 1/2 operator dashboard, not the open-core API.
How a reply gets classified
A reply row is created (internally, from the IMAP-polling pipeline) with the raw message content, then classified — by your connected AI key when one is configured, or by a keyword-heuristic classifier when there is no AI key or the AI call fails, so a missing key or a provider outage never silently drops a reply to UNCLASSIFIED and misses a compliance-sensitive opt-out. Quoted earlier messages and WarmHawk’s own footer are stripped before classifying, so a reply that quotes your unsubscribe line isn’t read as an opt-out.
A reply from a person ends that lead’s sequence: no more follow-ups go out once someone has written back. A machine’s answer doesn’t (see away notices and auto-replies). Filter the list with classification, campaignId, mailboxId or domainId.
API details (Tier 0 / self-hosters) · GET /v1/replies — filterable, dashboard-facing▸
curl "https://app.yourcompany.com/v1/replies?classification=INTERESTED&campaignId=camp_g7h8i9" \
-H "Authorization: Bearer YOUR_API_KEY"API details (Tier 0 / self-hosters) · PATCH /v1/replies/:id — re-classify by hand▸
curl -X PATCH https://app.yourcompany.com/v1/replies/rep_x1y2z3 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "classification": "INTERESTED" }'Classification labels: INTERESTED, NOT_INTERESTED, OUT_OF_OFFICE, AUTO_REPLY, LEFT_COMPANY, OPT_OUT, UNCLASSIFIED. An OPT_OUT classification — from the AI or the keyword fallback — adds the lead’s email to the same suppression list a manual POST /v1/leads/:id/suppress uses, so it stops future sends immediately, not just on the next dashboard review.
Away notices and auto-replies
Every reply stops the lead’s follow-ups the moment it arrives, so nothing goes out while it waits for its label. The label then decides what happens:
OUT_OF_OFFICE: the follow-ups pause. The next one goes out the day after the return date the reply names (“back October 20”, “returning 10/20”, “back Monday”), or a week after the reply when it names none. It is never sent earlier than the sequence already had it.AUTO_REPLY(a ticket number, “we’ll get back to you”): the sequence carries on as scheduled.LEFT_COMPANY(“no longer with the company”, “this mailbox is no longer monitored”) and every other label: the sequence stays stopped.
A lead that has had a real answer stays stopped, whatever auto-replies come after it. Relabelling a reply with PATCH /v1/replies/:id moves its lead with the new label. The Replies page shows where each lead stands under its label: “Follow-ups paused until Oct 21”, “Follow-ups continue” or “Follow-ups cancelled”.
Before v1.26.0, away notices and auto-replies ended the sequence too. To start those leads’ follow-ups again, run this on the server. Without --yes it only counts them.
API details (Tier 0 / self-hosters) · Resume leads an away notice or auto-reply stopped▸
warmhawk replies resume-auto-replied
warmhawk replies resume-auto-replied --yesAway notices among them wait for their return date like a new one would. Leads with any other reply stay stopped.
Team access (Tier 1/2, dashboard-side)
Tier 0’s open-core API has no team concept — POST /v1/auth/login authenticates against a single-account User table on the engine itself. Team invite/remove with flat, shared permissions is a warmhawk-enterprise-operator dashboard feature on Tier 1/2: every invited teammate sees everything in that one account — it is not per-client data isolation between an agency’s own separate clients (see the pricing comparison for that distinction spelled out in full). 2FA/MFA on dashboard login is also a Tier 1/2 feature, layered on top of the same account.
Reply polling runs as an internal n8n workflow calling GET /replies/pending and the IMAP fetch-reply endpoint — both internal-only, guarded by a shared callback secret and reachable only over the instance’s internal Docker network, never exposed publicly. See Architecture for how the internal-only network boundary works.
Questions
Replies & team: questions worth answering up front
Does an OPT_OUT reply automatically suppress the lead?+
Yes — reply classification is wired directly into the same SuppressionEntry mechanism a manual "suppress" action uses, so an AI-classified opt-out stops future sends without a human having to act on it first.
What happens if the AI reply classifier is unavailable?+
It falls back to a keyword-heuristic classifier (checking for phrases like "unsubscribe," "out of office," "not interested") rather than leaving every reply UNCLASSIFIED. The same keyword check runs when no AI key is connected at all, so an install without AI still catches opt-outs. Quoted earlier messages and WarmHawk’s own footer are stripped first, so a reply that only quotes your “Unsubscribe” link isn’t read as an opt-out.
Does an out-of-office reply stop the follow-ups?+
No, it pauses them. WarmHawk reads the return date from the reply and sends the next follow-up the day after it, or a week later when the reply names no date. An auto-reply such as a support ticket acknowledgement leaves the sequence running as scheduled. A reply saying the person has left the company, or that the address is no longer monitored, is labelled LEFT_COMPANY and ends the sequence.
Is team management part of the core-engine API?+
No — team invite/remove with flat permissions is a warmhawk-enterprise-operator (dashboard) feature, available on Tier 1/2. Tier 0's API has no concept of a team at all; it authenticates against its own single-account User table.
Can I filter replies by classification or mailbox?+
Yes — GET /v1/replies accepts classification, campaignId, mailboxId and domainId query params, any combination, for exactly this kind of Unified Reply Inbox filtering.