email-deliverability

Run a full email-deliverability scan (SPF, DKIM, DMARC, MTA-STS, TLS-RPT, MX TLS, BIMI, DNS blocklists) for a domain and return a 0-100 score with per-check findings. A check can come back `not_applicable` (does not apply to this domain, e.g. MTA-STS on a domain with no MX — excluded from the score, not a failure) or `unverified` (could not be determined this scan, e.g. DKIM behind an ESP with a random per-tenant selector like Amazon SES Easy DKIM — never treat as a failure). `scoreSubtitle` explains the denominator when anything was excluded. Runs at your plan tier (full blocklist set on paid plans) and saves the scan to the domain history in your account.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to scan, e.g. example.com."
    },
    "dkimSelectors": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional DKIM selectors to probe."
    }
  },
  "required": [
    "domain"
  ]
}

Return the overall deliverability score and letter grade for a domain (runs a fresh scan).

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to score, e.g. example.com."
    }
  },
  "required": [
    "domain"
  ]
}

Check a domain (apex + MX-host IPs) against supported DNS blocklists and return listings, targets checked, and issues (authoritative-side queries; no public-resolver false positives).

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to check, e.g. example.com."
    }
  },
  "required": [
    "domain"
  ]
}

Summarize ingested DMARC aggregate (RUA) reports for a domain tracked in your InboxGuard account: report volume, pass rate, top sending sources, and the rua inbox to publish. The domain must already be added to the account, and the plan must include DMARC ingest.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name tracked in the account, e.g. example.com."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 90,
      "description": "Lookback window in days (default 30, max 90)."
    }
  },
  "required": [
    "domain"
  ]
}

List the account's tracked domains with latest scan score, last scan time, and open alert count.

{
  "type": "object",
  "properties": {}
}

Full detail for one tracked domain: the domain record, the latest scan with all per-check findings (spf, dmarc, dkim, ptr, mta_sts, tls_rpt, mx_tls, blocklist), recent score history, open/recent alerts, and Google Postmaster stats when connected.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name as tracked in the account, e.g. example.com."
    }
  },
  "required": [
    "domain"
  ]
}

List the account's deliverability alerts (score drops, check failures, blocklist listings). Defaults to open alerts only.

{
  "type": "object",
  "properties": {
    "resolved": {
      "type": "string",
      "enum": [
        "false",
        "true",
        "all"
      ],
      "description": "'false' = open alerts only (default), 'true' = resolved only, 'all' = both."
    },
    "severity": {
      "type": "string",
      "enum": [
        "critical",
        "warn",
        "info",
        "all"
      ],
      "description": "Filter by severity (default 'all')."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Max alerts to return (default 50)."
    }
  }
}

List recent scans (id, domain, run time, score) across all tracked domains, or for one domain when a name is given.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Optional: restrict to one tracked domain by name, e.g. example.com. Omit for all domains."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max scans to return (default 20)."
    }
  }
}

Mark an alert resolved (or reopen it with resolved=false). Requires an API key with write/full scope. Resolving an already-resolved alert is a no-op.

{
  "type": "object",
  "properties": {
    "alertId": {
      "type": "string",
      "format": "uuid",
      "description": "Alert UUID, from list_alerts or get_domain."
    },
    "resolved": {
      "type": "boolean",
      "description": "true (default) marks the alert resolved; false reopens it."
    }
  },
  "required": [
    "alertId"
  ]
}

Compute the exact DNS-record changes needed to fix a tracked domain's deliverability, based on its latest scan and the org's connected registrar (Cloudflare/Route 53/GoDaddy/Namecheap). Read-only — nothing changes. Returns the `ops` to pass verbatim to apply_dns_fix, plus `manualReview` items that need a human decision (SPF sender list, DKIM keys, BIMI logo). Requires the domain to be tracked, a scan to exist, and a registrar connection covering the zone.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name tracked in the account, e.g. example.com."
    }
  },
  "required": [
    "domain"
  ]
}

Apply a DNS fix plan to a tracked domain by publishing records at the connected registrar. DESTRUCTIVE: it creates/updates/deletes DNS records. Two-step by design — first call get_dns_fix_plan, then pass its `connectionId` and `ops` here verbatim. The server re-derives the diff from the latest scan and rejects any op that no longer matches, so an agent can never apply arbitrary records. Requires an owner/admin API key with write or full scope. Re-scan afterward to confirm the fix.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name tracked in the account, e.g. example.com."
    },
    "connectionId": {
      "type": "string",
      "format": "uuid",
      "description": "The connectionId from get_dns_fix_plan."
    },
    "ops": {
      "type": "array",
      "description": "The `ops` array from get_dns_fix_plan, passed verbatim. The server validates each op against a freshly recomputed diff before executing.",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "domain",
    "connectionId",
    "ops"
  ]
}

Re-verify SPF, DKIM, DMARC, and ARC from a raw RFC 5322 email (full message or just the headers block). Returns InboxGuard's independent verdict (`ours`), the sender's own Authentication-Results (`theirs`), whether they `agree`, and parsed envelope/headers — useful for spotting forged or mismatched auth results. No account needed.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "minLength": 50,
      "description": "The raw email — full RFC 5322 message, or at least the headers block (Received, Authentication-Results, DKIM-Signature, From, …)."
    },
    "senderIp": {
      "type": "string",
      "description": "Optional: connecting IP to evaluate SPF against (overrides the IP parsed from Received headers)."
    },
    "helo": {
      "type": "string",
      "description": "Optional: the SMTP HELO/EHLO domain."
    },
    "mailFrom": {
      "type": "string",
      "description": "Optional: the envelope MAIL FROM (return-path) address."
    }
  },
  "required": [
    "message"
  ]
}

Queue an asynchronous batch scan of up to 50 domains and get a jobId immediately (avoids the 30s per-call limit). Poll get_scan_job with the jobId until status is succeeded/partial/failed to read per-domain scores. Requires an API key with write or full scope. These scans are NOT added to monitoring or saved to history.

{
  "type": "object",
  "properties": {
    "domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "1-50 domains to scan, e.g. [\"example.com\",\"acme.com\"]."
    }
  },
  "required": [
    "domains"
  ]
}

Poll an async batch scan started with scan_domains_batch: returns status (queued/running/succeeded/partial/failed), completed count, and per-domain results (domain, ok, score, grade) as they finish.

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "format": "uuid",
      "description": "The jobId returned by scan_domains_batch."
    }
  },
  "required": [
    "jobId"
  ]
}

Stop monitoring a domain and delete it (and its scan history) from the account. DESTRUCTIVE and not reversible. Requires an owner/admin API key with write or full scope. (To ADD a domain, run scan_domain with this API key — authenticated scans auto-track the domain.)

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name tracked in the account, e.g. example.com."
    }
  },
  "required": [
    "domain"
  ]
}

List the registrar accounts (Cloudflare, Route 53, GoDaddy, Namecheap) connected to the org — provider, verification, last-used time — plus the supported providers. Use this to check whether the detect-and-fix loop (get_dns_fix_plan / apply_dns_fix) is available before attempting it.

{
  "type": "object",
  "properties": {}
}

Create a channel that InboxGuard alerts are delivered to: webhook (HMAC-signed), Slack, Microsoft Teams, PagerDuty, SMS, or email. Returns the channel id, and for kind=webhook the `signing_secret` used to verify deliveries. Requires an owner/admin API key with write or full scope.

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "webhook",
        "slack",
        "teams",
        "pagerduty",
        "sms",
        "email"
      ],
      "description": "Channel type."
    },
    "target": {
      "type": "string",
      "description": "Destination matching `kind`: the webhook/Slack/Teams URL, PagerDuty integration key, phone number (E.164), or email address."
    },
    "displayName": {
      "type": "string",
      "description": "Optional label for the channel."
    },
    "severityFilter": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "info",
          "warn",
          "critical"
        ]
      },
      "description": "Which alert severities to deliver (default [\"critical\",\"warn\"])."
    }
  },
  "required": [
    "kind",
    "target"
  ]
}

Create a read-only public share link for a tracked domain's latest report (anyone with the URL can view it; no account). Returns a `token` and the public `url` (https://inboxguard.io/r/<token>). Requires an owner/admin API key with write or full scope, on a plan that includes public reports.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name tracked in the account, e.g. example.com."
    }
  },
  "required": [
    "domain"
  ]
}

Store this org's Microsoft SNDS (Smart Network Data Services) automated-data-access key so InboxGuard syncs per-IP Outlook/Hotmail reputation daily. Get the key from the SNDS Automated Data Access page (https://sendersupport.olc.protection.outlook.com/snds/). Requires an owner/admin API key with write or full scope. Data appears within ~24h of the first sync.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "The SNDS access key from the SNDS Automated Data Access page."
    },
    "label": {
      "type": "string",
      "description": "Optional label, e.g. \"prod sending IPs\"."
    }
  },
  "required": [
    "key"
  ]
}

Report whether Microsoft SNDS is connected for the org, the last sync time + status, how many sending IPs are tracked, and how many are currently blocked by Outlook/Hotmail. Use before get_snds_ip_stats to confirm the integration is live.

{
  "type": "object",
  "properties": {}
}

Return the latest per-IP reputation from Microsoft SNDS for the org's sending IPs: filter result (GREEN/YELLOW/RED), complaint-rate band, spam-trap hits, message volume, and current block status. Requires SNDS to be connected (see connect_snds / get_snds_status).

{
  "type": "object",
  "properties": {}
}

Store the org's seed-list inbox-placement provider + API key (provider: 'mailreach' or 'glockapps'; GlockApps also needs projectId). Enables start_inbox_placement_test. Requires an owner/admin API key with write or full scope.

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "mailreach",
        "glockapps"
      ],
      "description": "Inbox-placement vendor."
    },
    "apiKey": {
      "type": "string",
      "description": "The vendor API key."
    },
    "projectId": {
      "type": "string",
      "description": "GlockApps project id (required for provider=glockapps)."
    }
  },
  "required": [
    "provider",
    "apiKey"
  ]
}

Report whether a seed-list inbox-placement provider is connected for the org, which provider, and how many tests have run. Lists the supported providers when not connected.

{
  "type": "object",
  "properties": {}
}

Start a seed-list inbox-placement test. Returns a testId, the seed addresses to mail your campaign to, and (if the provider requires it) a header to insert. After sending to the seeds, poll get_inbox_placement_test for the Inbox/Spam/Missing verdict. Requires inbox-placement to be connected and an owner/admin API key with write or full scope.

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "Optional subject line to associate with the test."
    }
  }
}

Poll a seed-list inbox-placement test by testId. Returns status (running/completed/failed) and, once measured, the Inbox/Spam/Missing counts and inbox-placement score (0–100). Call after sending your campaign to the seed addresses from start_inbox_placement_test.

{
  "type": "object",
  "properties": {
    "testId": {
      "type": "string",
      "format": "uuid",
      "description": "The testId returned by start_inbox_placement_test."
    }
  },
  "required": [
    "testId"
  ]
}

List recent seed-list inbox-placement tests for the org (most recent first) with their status and Inbox/Spam/Missing scores.

{
  "type": "object",
  "properties": {}
}

Return a structured deliverability report for a tracked domain: the latest score + letter grade + `scoreSubtitle` (explains the denominator when a check was excluded, e.g. "80/100 · scored on 65 of 83 applicable points · 1 check unverified"), each check's status (pass/warn/fail/unverified/not_applicable — `not_applicable` means the check doesn't apply to this domain and `unverified` means it couldn't be checked this scan; neither is a failure), the top issues to fix, blocklist count, and DMARC policy. Includes `pdfUrl` — the same auth-gated endpoint that returns a branded one-page PDF (send your bearer token). Use this to summarize a domain's posture or hand a client a report.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name tracked in the account, e.g. example.com."
    }
  },
  "required": [
    "domain"
  ]
}

Org-wide deliverability rollup across every monitored domain: average score + overall grade, the grade distribution (how many domains are A/B/C/D/F/unscored), total open alerts, the domains needing attention (lowest score / open alerts first), and a per-client-group breakdown. Use this for an at-a-glance portfolio health summary across an agency or multi-domain account.

{
  "type": "object",
  "properties": {}
}