Domain audit and migration

​

Goal

​

Prerequisites

• Keep Mail credentials on your backend. API examples use https://api.stackshift.cloud/v1 unless a public /api/v1 route is stated.

​

Workflow

​

Public endpoints and request fields

• GET 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

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

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

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

​

Related guides