Claude が下書きする修正アクションは、アラートを通知から実行可能な対応へと変える部分です。各アラートには、どのしきい値が発火したかに応じた具体的な是正アクションが添えられます。名前付きドメインのシーケンスを停止する、ウォームアップ中に送信量を 30% 下げる、名前付きブロックリストへ復活申請を提出する、といった具合です。汎用的な「配信到達性を調査せよ」ではありません。
# Email deliverability monitor — n8n flow
This bundle contains a complete n8n workflow that polls Google Postmaster Tools, parses DMARC aggregate reports from a shared IMAP mailbox, runs DNSBL lookups across the major public blocklists, and pulls bounce / complaint metrics from Smartlead and Instantly — then alerts the assigned RevOps owner in Slack the moment any watched domain crosses a documented threshold, with a Claude-drafted remediation step attached.
Three entry points:
- **Hourly Sweep** — `Schedule — Hourly Sweep` fires at the top of every hour and runs the Postmaster, ESP, and DNSBL branches in parallel against every domain in the register.
- **DMARC Poll** — `Schedule — DMARC Poll` runs every 15 minutes and checks the IMAP mailbox for new DMARC aggregate reports.
- **Ad-hoc check** — `Webhook — Ad-hoc Domain Check` accepts `POST /webhook/deliverability-check` for one-off checks against a single domain.
## What this flow does
The hourly sweep loads the static domain register, fans out a Split In Batches (size 3 to stay under the per-second limits on Postmaster Tools and the public DNSBL zones), and runs four parallel polls per domain: Postmaster Tools `trafficStats` for the last 7 days, Smartlead `campaign-statistics` if the domain's `sendingPlatform` is `smartlead`, Instantly `accounts/health` if it's `instantly`, and a DNSBL probe that resolves the MX → IP → queries each configured blocklist zone via two of three resolvers.
The branches converge in `Merge — Per-Domain Snapshot`, which collapses each upstream's shape into one record per `(domain, sourceMetric, dateBucket)` and rejects records older than 26 hours. `Threshold Check (Code)` then applies per-metric alert and critical thresholds against the latest point AND a trailing 7-day rolling mean of the prior points. The thresholds default to the Gmail/Yahoo bulk-sender envelope (spam rate alert at 0.1%, critical at 0.3%) and are overridable via env vars.
`Dedup Gate (Static Data)` reads `$getWorkflowStaticData('global')` for a 12-hour-bucketed `alerted_<domain>_<metric>_<status>` key. If the same alert fired in the last 12 hours, the branch halts silently. Otherwise the gate stamps the key and continues. Static data persists only on production executions — never on manual Execute Workflow runs — which is why the verification below uses live triggers, not the manual-run button.
`Claude — Remediation Draft` posts to the Anthropic API with `claude-haiku-4-5`, an 8-second timeout, and a system prompt that asks for a structured JSON remediation with three fields: `action`, `why`, and `runbookUrl`. The system prompt names what the reader can actually do — pause a sequence, open a delisting request, run a list scrub — so the draft is runnable, not advisory. `Parse Remediation` falls back to a deterministic per-metric template when the LLM call times out or the response fails to parse, and tags `draftSource` so the rep sees whether they got `claude-haiku-4-5` or `template-fallback`.
`Slack — Notify` posts to one of three channels based on alert status and domain severity, using a Block Kit message with a header (severity color), a fields grid (metric, value, alert/critical thresholds, 7-day mean, severity), the remediation as a section block, and a context block @-mentioning the domain owner.
The DMARC branch is independent: `IMAP — DMARC Mailbox` reads new messages matching the `Report Domain` subject pattern, `Parse DMARC XML` unzips `.gz` / `.zip` attachments and walks the XML, and the resulting per-record rows feed into the same `Merge — Per-Domain Snapshot` node. DMARC records with both SPF and DKIM evaluating to `fail` are tagged `spoofingSuspect: true` — the only branch in the flow that can catch a forged-sender attack from outside your sending platforms.
## Import
1. In n8n, open **Workflows → Import from File** and select `email-deliverability-monitor-n8n.json`.
2. Open the workflow's **Settings** and confirm `Execution Order` is `v1` and `Timezone` matches your business hours (defaults to `America/New_York`). The cron expression interprets its schedule in this zone.
3. Edit the `Domain Register (Static)` Code node to your real domains. The default array contains three placeholder entries (`outbound.example.com`, `warm.example.io`, `news.example.com`); replace them.
4. Set the environment variables listed below.
5. Wire all five credentials listed in the Credentials section.
6. Run the five-step verification before activating either Schedule Trigger.
## Domain Register
The watched domains live in the `Domain Register (Static)` Code node — not in env vars, not in a database. The list is short, and putting it in the workflow keeps the version history in n8n's workflow versions alongside the threshold logic.
Each entry:
| Field | Values | Purpose |
|---|---|---|
| `domain` | the FQDN you send from (e.g. `outbound.example.com`) | Used as the API parameter for Postmaster, Smartlead, Instantly; used for MX lookup in DNSBL probe |
| `sendingPlatform` | `smartlead` / `instantly` / `outreach` / `gmail-direct` | Routes which ESP API gets polled (other branches no-op) |
| `owner` | email | Recorded in alert context |
| `slackHandle` | Slack handle without `@` | @-mentioned in the alert |
| `severity` | `primary` / `warmup` / `secondary` | Drives channel routing and on-call paging |
## Environment variables
Set these in your n8n instance's environment (n8n Cloud: **Settings → Environment Variables**; self-hosted: your `.env` file or container environment):
| Variable | Where to find it | Example |
|---|---|---|
| `DNSBL_ZONES` | Comma-separated list of blocklist zones to query. Defaults to Spamhaus, Barracuda, SpamCop. | `zen.spamhaus.org,b.barracudacentral.org,bl.spamcop.net` |
| `DNSBL_RESOLVERS` | Comma-separated resolver IPs. The probe queries 2-of-3 by default. | `8.8.8.8,1.1.1.1,9.9.9.9` |
| `SPAM_RATE_ALERT_THRESHOLD` | Decimal — value at which the alert fires. Default 0.001 (0.1%). | `0.001` |
| `SPAM_RATE_CRITICAL_THRESHOLD` | Decimal — value at which the critical fires. Default 0.003 (0.3%, the Gmail/Yahoo bulk-sender ceiling). | `0.003` |
| `BOUNCE_RATE_ALERT_THRESHOLD` | Decimal — alert. Default 0.05. | `0.05` |
| `BOUNCE_RATE_CRITICAL_THRESHOLD` | Decimal — critical. Default 0.10. | `0.10` |
| `COMPLAINT_RATE_ALERT_THRESHOLD` | Decimal — alert. Default 0.0008 (0.08%). | `0.0008` |
| `COMPLAINT_RATE_CRITICAL_THRESHOLD` | Decimal — critical. Default 0.003. | `0.003` |
| `POSTMASTER_MIN_POINTS_FOR_CRITICAL` | Integer — minimum trailing-72h points required before a Postmaster critical fires. Downgrades to alert when fewer points are available. | `2` |
| `SLACK_CHANNEL_CRITICAL` | Channel name (with `#`) for critical alerts. | `#deliverability-primary` |
| `SLACK_CHANNEL_WARMUP` | Channel for warmup-severity alerts. | `#deliverability-warmup` |
| `SLACK_CHANNEL_SECONDARY` | Channel for secondary-severity alerts. | `#deliverability-secondary` |
The DNSBL public lists allow non-commercial query volume free of charge. If your domain register grows past roughly 30 watched domains, switch to a paid data feed for the Spamhaus zone you query most often — public-resolver rate limits will start to drop queries silently.
## Credentials
### `PLACEHOLDER_POSTMASTER_CRED_ID` — Google Postmaster OAuth
Used by `HTTP — Postmaster Tools`. Postmaster Tools requires a Google Workspace account with the domain already verified in `https://postmaster.google.com`. Create an OAuth 2.0 client in Google Cloud Console with the `https://www.googleapis.com/auth/postmaster.readonly` scope, add it as a **Google OAuth2 API** credential in n8n, and authorize against the same account that owns the Postmaster Tools verification.
### `PLACEHOLDER_IMAP_CRED_ID` — DMARC RUA Mailbox
Used by `IMAP — DMARC Mailbox`. Create a dedicated mailbox (`dmarc-reports@yourcompany.com` is the convention) and point every DMARC RUA record at it. In n8n, add an **IMAP** credential with the mailbox host, port (993 for IMAPS), username, and an app password if your provider requires one. Google Workspace and Microsoft 365 both require app passwords or service-account delegation rather than the primary account password.
### `PLACEHOLDER_SMARTLEAD_CRED_ID` — Smartlead API key
Used by `HTTP — Smartlead Stats`. Generate an API key in Smartlead under **Settings → API Keys**. In n8n, add an **HTTP Header Auth** credential with header name `Authorization` and value `Bearer <your_key>`. Smartlead's API rate-limit is 1 request/second per key as of 2026-05; the Split In Batches batch size of 3 with the default Schedule Trigger interval of 1 hour stays well under this.
### `PLACEHOLDER_INSTANTLY_CRED_ID` — Instantly API key
Used by `HTTP — Instantly Health`. Generate an API key in Instantly under **Settings → Integrations → API Keys**. In n8n, add an **HTTP Header Auth** credential with header name `Authorization` and value `Bearer <your_key>`. Instantly's `/api/v2` endpoints require an account on the Growth plan or above.
### `PLACEHOLDER_SLACK_CRED_ID` — Slack bot token
Used by `Slack — Notify`. Create a Slack app at `https://api.slack.com/apps`, add the `chat:write` bot scope, install it to your workspace, and invite the bot user to each of the three deliverability channels. In n8n, add an **HTTP Header Auth** credential with header name `Authorization` and value `Bearer xoxb-…`. Create the channels (`#deliverability-primary`, `#deliverability-warmup`, `#deliverability-secondary`, `#deliverability-ops`) before activating; the channel names are env-overridable but must exist.
### `PLACEHOLDER_ANTHROPIC_CRED_ID` — Anthropic API key
Used by `Claude — Remediation Draft`. Generate an API key at `https://console.anthropic.com`. In n8n, add an **HTTP Header Auth** credential with header name `x-api-key` and value set to the key. The node uses `claude-haiku-4-5` to keep the call under 2 seconds at typical payload size. Cost is roughly $0.005 per alert on the median payload (~500 input + 120 output tokens).
## DMARC mailbox setup
For each watched domain, the DNS DMARC record should look like:
```
_dmarc.outbound.example.com. IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@yourcompany.com; ruf=mailto:dmarc-reports@yourcompany.com; fo=1; adkim=r; aspf=r; pct=100"
```
Use `p=quarantine` or `p=reject` once you have established baseline reports show all legitimate sources passing. Starting on `p=none` will produce reports but no quarantining — the alert flow works either way; the policy choice is unrelated.
Most major mailbox providers deliver DMARC XML attachments without rewriting. Three known sources of silent attachment loss:
1. **Microsoft 365 with the default Anti-Malware Policy** — the Common Attachment Filter strips `.zip` from inbound mail. Setting: **Microsoft 365 Defender → Email & collaboration → Policies & rules → Anti-malware → Default policy → Protection settings → Common Attachment Filter → File types**. Remove `zip` from the blocked list, or create a transport rule that exempts messages from `dmarc-reports@yourcompany.com`.
2. **Gmail with strict attachment scanning** — `.gz` files are sometimes flagged. Gmail does not strip them but may quarantine the message. If reports stop arriving from a specific reporter, check the Quarantine in Google Workspace admin.
3. **Provider-side rewriting** — a few providers rename `.gz` to `.gz_renamed`. The parser will skip these and log `attachmentMatched: false`. Add a filename rule at the mailbox level to revert the name.
## Verification
Run all five before activating either Schedule Trigger. The flow should NOT be Active during steps 1-4.
### 1. Manual webhook hit against a known domain
POST a single-domain check to the webhook endpoint:
```bash
curl -X POST "https://<your-n8n-host>/webhook/deliverability-check" \
-H "Content-Type: application/json" \
-d '{"domain": "outbound.example.com"}'
```
Expected: 202 response, and within ~30 seconds you see the Slack message in `#deliverability-primary` IF the domain has any threshold trip. If not, the execution log in n8n should show all four branches running with `status: ok` outputs from `Threshold Check (Code)`.
### 2. Forced threshold trip
Temporarily set `SPAM_RATE_ALERT_THRESHOLD=0` and `SPAM_RATE_CRITICAL_THRESHOLD=0`, then re-run the manual webhook. Every Postmaster point will trip. You should see one Slack alert per domain — NOT multiple, because the dedup gate within a 12-hour window collapses them. Reset the env vars afterward.
### 3. Stale-report test
Edit `Merge — Per-Domain Snapshot` temporarily to set the `MAX_AGE_MS` constant to `0`. Re-run. Every Postmaster record should be rejected (collected-at older than 0ms), and you should see the resulting `status: ok` (no data → no alert) rather than spurious alerts on missing data. Revert the constant.
### 4. DNSBL false-positive test
In `DNSBL Probe (Code)`, hardcode a known-clean IP (e.g. `8.8.8.8`) in place of the MX lookup result and re-run. The probe should return `dnsblStatus: ok` with an empty `listings` array. Then hardcode a known-listed test IP from `127.0.0.2` (the standard Spamhaus self-test address — listed on `zen.spamhaus.org` by design) and confirm `dnsblStatus: critical` with the listing recorded. Revert.
### 5. Multi-domain burst test
Add five extra domains to `Domain Register (Static)` temporarily and run the manual webhook. Confirm the Split In Batches handles them without rate-limit errors from Postmaster Tools. The execution log should show the second batch starting ~1 second after the first. Revert.
After verifying all five, set both Schedule Triggers to Active and confirm the next top-of-hour execution runs cleanly in production mode (the dedup gate's static data only persists on production runs).
## Known limits
1. **Single-file zip assumption.** `Parse DMARC XML` uses a minimal zip reader that assumes one file per archive (the DMARC norm). Multi-file zips will fail to parse. If you see `dmarc-parse-error` rows with `error: 'not a zip'` for `.zip` attachments, replace the unwrap function with a real zip library (`adm-zip` is available in most n8n environments).
2. **Postmaster Tools data lag.** Google publishes the previous day's data in batches throughout the next day. The `POSTMASTER_MIN_POINTS_FOR_CRITICAL` env var downgrades single-point days from critical to alert; do not lower it below 2 without accepting noisier paging.
3. **DNSBL public-resolver rate limits.** Spamhaus, Barracuda, and SpamCop all rate-limit queries from common public resolvers. At a register size of 5-10 domains with hourly polling this is well within limits; past ~30 domains, switch the high-volume zone to a paid data feed.
4. **No automatic delisting requests.** The flow surfaces the delisting URL in the Claude remediation draft. Filing the request still requires a human; most blocklists require account creation and a reason-for-listing explanation.
5. **Not runtime-tested in this repo.** The bundle is a complete export and has been hand-walked node by node, but it has not been imported into a live n8n instance against a production Google Workspace and Smartlead account. Treat the verification above as a real first run, not a smoke test.
