Deliverability Watch

skill

Read ESP deliverability metrics via API and alert on bounce/spam/open anomalies.

Download .md

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..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.