# Deliverability Watch

Monitor email service provider (ESP) deliverability metrics and raise alerts when bounce, spam-complaint, or open-rate signals drift outside normal range.

## When to use
- On a recurring schedule to check recent campaign or sending-domain deliverability health.
- After a campaign send, to confirm bounce and spam-complaint rates stayed within acceptable limits.
- When a human reports inbox placement or open-rate problems and asks for a root-cause check.
- Before a large send, to verify the sending reputation is currently healthy.

## Tools
- `http-get` — call the ESP's REST API to pull bounce, spam-complaint, and open/click metrics for a domain, IP, or campaign.
- `shell-execute` — compute rates, rolling averages, and anomaly thresholds from the pulled metrics, and diff against prior baselines.
- `send-message` — notify a human or another agent when an anomaly is detected, when authentication fails, or when a metric needs review.
- `schedule-task`: register this watch on a recurring cron cadence so it reruns automatically without a human re-enqueuing it.

## Cadence

Monitoring must repeat, not run once. On first setup, use `schedule-task` to register a recurring run of this check on an appropriate cron cadence (for example `0 * * * *` hourly or `0 9 * * *` daily), passing the same monitoring instruction as the schedule prompt. The platform then reruns it automatically at each due time — you never depend on a human to re-enqueue it. Create the schedule only once; if this check is already scheduled, skip re-creating it.

## Playbook
1. Identify the target scope for this check: sending domain, IP pool, or specific campaign ID, and the time window to evaluate.
2. Call the ESP REST API with `http-get` to fetch recent bounce, spam-complaint, and open/click metrics (e.g. GET https://api.<esp>.com/v3/stats). Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials. If the call returns 401/403 or no Integration row exists, stop and message a human via `send-message` asking them to create the Integration, naming the service and required scopes.
3. If the response is empty or missing expected fields, re-check the endpoint path and query parameters before concluding there is no data.
4. Use `shell-execute` to compute bounce rate, spam-complaint rate, and open-rate delta versus the prior period from the fetched data.
5. Compare each computed rate against standard deliverability thresholds (e.g. bounce rate above roughly 2%, spam-complaint rate above roughly 0.1%, or an open-rate drop of more than 30% versus baseline).
6. If a metric breaches its threshold, use `shell-execute` to assemble a concise summary: which metric, current value, threshold, and affected domain/campaign.
7. Send the anomaly summary to a human via `send-message` so they can decide on remediation (e.g. pausing sends, warming a new IP, reviewing content).
8. If the underlying ESP API supports only reading these metrics and any suppression-list or sender-setting change is needed, do not attempt to modify it — compile the required change into a summary and hand off to a human via `send-message`, since PATCH/PUT/DELETE operations on ESP records are not possible with the declared tools.
9. If all metrics are within range, note the clean check result for the record; no alert is required.

## Failure modes
- 401/403 response from the ESP API -> missing or invalid Integration; stop and escalate via `send-message` naming the service and required scopes.
- Empty or malformed metrics payload -> verify the endpoint path, time-window parameters, and campaign/domain identifiers before retrying.
- Rate limit (429) response -> back off and retry later; note the rate limit in memory so future checks space out requests.
- Metrics schema or endpoint appears to have changed (unexpected fields, deprecated route) -> stop and hand off to a human via `send-message` rather than guessing field mappings.

## Done when
- The relevant bounce, spam-complaint, and open-rate metrics have been fetched and compared against thresholds for the target scope and window.
- Any breach has been summarized and delivered to a human via `send-message`, or the check is confirmed clean.
- No attempt was made to modify ESP suppression lists or settings directly; any needed change was routed to a human handoff.