> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending-domain health

> Monitor outbound authentication, understand holds and repair DNS without treating sender failures as recipient bounces.

<Warning>
  **Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
</Warning>

## Goal

Monitor outbound authentication, understand holds and repair DNS without treating sender failures as recipient bounces.

## Prerequisites

* Keep Mail credentials on your backend. API examples use [https://api.stackshift.cloud/v1](https://api.stackshift.cloud/v1) unless a public /api/v1 route is stated.

## Workflow

<Steps>
  <Step>
    Inspect a sending domain’s health and exact issue records.
  </Step>

  <Step>
    Repair customer-owned DNS records or escalate platform-scoped issues.
  </Step>

  <Step>
    Verify again and inspect recovery, pending holds and any expired work.
  </Step>
</Steps>

## Health lifecycle and polling

* Verified sending domains are rechecked hourly after successful checks. Failed or indeterminate checks are retried after five minutes. Worker scheduling and DNS timeouts can delay a check beyond its nominal nextCheckAt.
* state is healthy, suspect or degraded. A first confirmed failure becomes suspect; a continuing confirmed failure at least five minutes after firstFailureAt becomes degraded. One successful verification restores healthy.
* lastResult is verified, failed, indeterminate or unknown. Transient resolver uncertainty is not by itself a confirmed failure; it does not force a healthy domain into degraded state.
* Domain responses include health with lastCheckedAt, lastSuccessAt, nextCheckAt, degradedAt and issues. There is no separate customer health-check endpoint: use GET /mail/domains/\{domainId} and POST /mail/domains/\{domainId}/verify.

## Repair instructions and failure ownership

* Each issue includes record/name, expected value, observed values, status and scope. Follow the returned exact DNS values instead of copying another domain’s DKIM key or return-path record.
* scope customer identifies records you control. scope platform identifies platform-side problems; contact support rather than changing your DNS to mask a platform configuration failure.
* The checker evaluates sender authentication using the configured SPF include, domain DKIM material, return-path records and configured DMARC requirement. Retain correct DNS and allow propagation, then verify again.
* Health changes produce notifications for degradation and recovery through the existing notification delivery system. Sender authentication failures are separate from recipient bounce and complaint statistics.
* Subscribed webhook endpoints receive mail.domain.degraded and mail.domain.healthy events. Notification retries retain completed channels. The monitor never changes DNS automatically.

## New sends, queued work and recovery

* With enforcement enabled for the workspace, new live API/SMTP sends using a degraded domain fail with sender\_domain\_degraded. Test credentials bypass live domain verification.
* Already accepted work can be held pending domain recovery rather than counted as a recipient bounce. Holds preserve the original deadline, generally no more than 24 hours; an OTP may expire sooner. Repeated failures do not extend that deadline.
* Successful recovery resumes eligible held work. Expired work fails visibly and releases unused billing reservations when failure before handoff is confirmed. Uncertain handoffs are still reconciled before releasing their budget.
* Delivery checks still enforce consent, suppressions, billing and reputation. Fixing DNS does not bypass a separate opt-out, spending block or expired OTP.
* SMTP submission uses a temporary refusal for a degraded sender. Mail already accepted by the MTA cannot be recalled; health recovery only resumes work that is still held.

## Operational enablement

MAIL\_DOMAIN\_HEALTH\_ENABLED enables checks; MAIL\_DOMAIN\_HEALTH\_ENFORCE\_WORKSPACE\_IDS accepts workspace UUIDs or \* for all workspaces. Empty means observation only. These are operator settings, not a customer API toggle.

## Expected result

<Check>
  Domain responses show the current health and repair evidence; confirmed DNS recovery releases eligible held work.
</Check>

## Related guides

<CardGroup cols={2}>
  <Card title="StackShift Mail overview" href="/stackshift-mail/overview">
    Mail APIs and workflows: isolated simulation, explicit brands, consent-aware campaigns, engagement, domain health, migration, spending, inbound delivery and diagnostics.
  </Card>

  <Card title="Events, webhooks, and timelines" href="/stackshift-mail/events-webhooks-and-timelines">
    List mail events, inspect per-message timelines, subscribe webhooks, rotate secrets, retry deliveries, and verify webhook signatures.
  </Card>

  <Card title="Domain audit and migration" href="/stackshift-mail/migration">
    Read DNS evidence, review provider-specific changes and save a controlled migration checklist.
  </Card>

  <Card title="Sender domains and DNS" href="/stackshift-mail/sender-domains-and-dns">
    Create and verify outbound sender domains, inspect SPF, DKIM, DMARC, and return-path record status, and know what the domain status fields mean.
  </Card>
</CardGroup>