Skip to main content
Live with caveats. This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.

​
Goal

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

​
Prerequisites

​
Workflow

1
Inspect a sending domain’s health and exact issue records.
2
Repair customer-owned DNS records or escalate platform-scoped issues.
3
Verify again and inspect recovery, pending holds and any expired work.

​
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

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

StackShift Mail overview

Mail APIs and workflows: isolated simulation, explicit brands, consent-aware campaigns, engagement, domain health, migration, spending, inbound delivery and diagnostics.

Events, webhooks, and timelines

List mail events, inspect per-message timelines, subscribe webhooks, rotate secrets, retry deliveries, and verify webhook signatures.

Domain audit and migration

Read DNS evidence, review provider-specific changes and save a controlled migration checklist.

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.