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

# Domain audit and migration

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

<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

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

## 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>
    Audit DNS and resolve manual-review findings.
  </Step>

  <Step>
    Add the sending domain and publish exact coexistence records without replacing mailbox MX.
  </Step>

  <Step>
    Verify DNS, test with simulation and explicitly qualify controlled live delivery.
  </Step>

  <Step>
    Switch traffic gradually, monitor, then retire unused old records.
  </Step>
</Steps>

## Public endpoints and request fields

* GET [https://api.stackshift.cloud/api/v1/mail/audit](https://api.stackshift.cloud/api/v1/mail/audit) requires domain and optionally selectors (comma-separated, at most five) and download=1. The download is mail-domain-audit.json.
* GET /api/v1/mail/migration-plan accepts the same fields plus required provider. download=1 returns mail-migration-plan.json. GET /api/v1/mail/migration-guides returns \{data: \[...]} with every provider guide. No authentication is required for these three routes.
* Supported provider values are resend, sendgrid, mailgun, postmark, ses, sendbyte and smtp. Selectors are queried only when supplied; choosing a provider does not imply domain-wide DKIM discovery.
* Accept domain names only, not URLs, IP addresses, credentials or paths. Unicode domain names normalize to ASCII. No supplied URL is fetched and no DNS record is changed.

## Download an audit

```bash theme={null}
curl --get 'https://api.stackshift.cloud/api/v1/mail/audit' \
  --data-urlencode 'domain=example.com' \
  --data-urlencode 'selectors=ss1' \
  --data-urlencode 'download=1' \
  --output mail-domain-audit.json
```

## Response fields and limits

* Audit responses contain domain, checkedAt, records, spf and disclaimer. Each record has kind, name, status, observed and explanation. spf includes status (safe\_merge, manual\_review or unknown), lookupCount, reasons and proposed only when a proposal is available.
* SPF, DMARC and MX observations are DNS evidence, not a guarantee of delivery or inbox placement. Every result includes an unknown entry for untested DKIM selectors. An absent DMARC record at a subdomain does not exclude an organizational-domain policy.
* The migration-plan response adds guide, steps, rollback, example, sdkExample and contactMigration. Guide fields include provider, name, authentication, sender, apiChange, webhookChange, dnsChange, source and verifiedAt. Follow the returned provider source; credentials and provider-specific IDs do not transfer.
* Audit limits: 32 DNS lookups, eight seconds total, two seconds per lookup, eight concurrent audits, a two-minute cache bounded to 128 entries and 12 requests/minute per client IP. audit\_busy means capacity is occupied; invalid\_domain, invalid\_selectors, invalid\_audit and invalid\_provider identify invalid requests. A resolver failure is reported as unknown rather than a safe DNS result.

## SPF coexistence and DNS repair

* The merge preserves current senders and policy, avoids duplicate Stackshift includes and inserts include:\_spf.stackshift.cloud before the terminal all mechanism or redirect modifier. It does not create a second SPF record.
* Multiple/malformed policies, unsupported macros, include/redirect cycles, failed lookups or potential SPF lookup-limit violations require manual review. Do not publish a proposal when status/reasons report uncertainty.
* Preserve existing mailbox MX records during an outbound migration. The public tool does not generate DKIM keys; add the authenticated sending domain to obtain its exact Stackshift DKIM and return-path records.
* A provider guide supplies specific authentication/API mapping plus webhook and DNS migration notes. It does not copy a provider account, hosted mailboxes, historical messages or templates automatically. Move contacts through consent-aware import preview.

## Provider mappings returned by the planner

These are the mappings implemented by the planner. The returned source and verifiedAt fields identify the guide maintained in this release; selecting a provider does not contact its API or import its configuration.

* Resend (resend): replace its bearer key and POST /emails with Stackshift credentials and POST /v1/mail/send. Map from/to/subject/html/text, recreate templates and variables, and verify your own domain; provider test senders do not transfer.
* SendGrid (sendgrid): replace POST /v3/mail/send and its bearer key. Map personalizations recipients to to/cc/bcc and content MIME entries to html/text. Rebuild dynamic templates and verify the sender domain.
* Mailgun (mailgun): replace HTTP Basic api:key and domain-specific /messages multipart submission with bearer-authenticated JSON sends. Upload attachments through Assets and pass their IDs; independently verify the domain or subdomain.
* Postmark (postmark): replace X-Postmark-Server-Token with Authorization: Bearer. Map From/To/Subject/HtmlBody/TextBody to from/to/subject/html/text and recreate the transactional or broadcast stream and templates.
* Amazon SES (ses): replace SigV4 only for the Mail calls being migrated. Map FromEmailAddress, Destination and Content.Simple to from, to/cc/bcc, subject and html/text. Replace configuration-set behavior with streams, tags and webhooks; regional identities do not transfer.
* SendByte (sendbyte): create new test/live Stackshift credentials, verify the sending domain, rebuild sends against the Stackshift example and compare your provider payload against its API reference. The planner does not claim an automatic one-to-one template or account migration.
* Generic SMTP (smtp): update host, credentials and TLS mode, then exercise envelope To/Cc/Bcc, UTF-8 content and attachments with a test credential. Keep certificate verification enabled.
* For every provider: create and sign a new Stackshift webhook integration instead of reusing provider signatures. Keep the old webhook active for in-flight messages. Publish coexistence SPF plus exact new DKIM/return-path records without replacing mailbox MX.

## Authenticated checklist

* GET /v1/mail/migration/checklist?domain=example.com\&provider=resend reads workspace progress. PUT /v1/mail/migration/checklist accepts domain, provider, completed (step IDs) and revision. Use an authenticated Live workspace; test credentials cannot access this resource.
* Valid step IDs, in order: audit, add\_domain, coexist, verify, test, controlled\_send, switch, monitor, retire. Progress is an operator-maintained checklist, not proof that DNS or provider traffic changed.
* Save the current revision. A stale revision returns a conflict; reload before applying another update. updatedAt is response-only: do not echo it in PUT. Public audit requests do not save workspace progress.

```ts theme={null}
const checklist = await liveClient.mail.migration.checklist('example.com', 'resend')
await liveClient.mail.migration.saveChecklist({
  domain: checklist.domain, provider: checklist.provider,
  completed: [...new Set([...checklist.completed, 'audit'])], revision: checklist.revision,
})
```

## Signup continuation and rollback

* The public /mail/migrate page retains domain/provider through signup using redirectTo=/dashboard/mail/migrate?...; checklist progress is saved only after authentication.
* After coexistence DNS verifies, simulate all four outcomes, then separately authorize a controlled live send to an address you own. Switch a small portion of traffic and monitor before retiring old records.
* For rollback, restore the application’s old provider configuration and stop new Stackshift live submissions. Keep both providers’ DNS and webhooks until in-flight delivery ends. Reconcile uncertain messages before resending; changing providers is not duplicate protection.

## Expected result

<Check>
  The report separates observed DNS evidence from proposed changes, and the authenticated checklist records the migration steps you have completed.
</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="Sending-domain health" href="/stackshift-mail/sending-domain-health">
    Monitor outbound authentication, understand holds and repair DNS without treating sender failures as recipient bounces.
  </Card>

  <Card title="Subscriber consent and imports" href="/stackshift-mail/subscriber-consent-and-imports">
    Preview imports row by row, preserve consent evidence and use double opt-in before marketing delivery.
  </Card>
</CardGroup>