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

Warm a new sending domain safely, keep it authenticated and aligned, and check where your mail lands before you send to a large list.

​
Prerequisites

  • A sending domain added to StackShift Mail
  • Access to the domain’s DNS, or a connected Cloudflare account so StackShift can publish the records

​
Workflow

1
Add the domain, publish the SPF, DKIM, return-path and DMARC records, and verify it.
2
Start with transactional mail. Watch the warm-up status on the domain.
3
Run a seed test to see where a message lands at the large providers.
4
Read your DMARC report and move your policy from none towards quarantine only when the readiness signal says you are ready.
5
Send broadcasts once the domain has enough clean sending history.

​
What we can and cannot promise

No mail service controls where Gmail or Outlook puts a message. The receiving provider and the recipient’s own behaviour decide. StackShift does not promise inbox placement. What StackShift does promise is the work that makes placement likely: every domain is authenticated and aligned, warmed on a schedule, held back before it damages itself, and visible to you at every step.

​
Authentication and alignment

  • Each sending domain gets its own DKIM key, a return-path record and an SPF include. Publish exactly the records returned by POST /mail/domains or GET /mail/domains/{domainId}.
  • If your DNS is on Cloudflare, connect it once with PUT /mail/dns/cloudflare and apply the records with POST /mail/domains/{domainId}/dns/managed. POST /mail/domains/{domainId}/dns/repair fixes records that drifted.
  • POST /mail/domains/{domainId}/stream-domains creates separate subdomains for transactional and broadcast mail, each with its own keys, so one stream’s reputation never affects the other.
  • Hourly health checks watch your records. A degraded domain stops new live sends, and recovery releases held mail. See Sending-domain health.

​
Warm-up

  • A new domain moves from new to warming to trusted. GET /mail/domains/{domainId}/warmup returns the status, the day and the reason if growth is held or paused. GET …/warmup/history shows daily allowance against what you sent.
  • The daily allowance grows on a schedule that StackShift enforces, with hourly caps that spread sending across the day. Mail over the cap waits in a queue, and nothing is dropped.
  • Transactional and sign-in code mail goes first within the allowance. Broadcasts wait until the domain has had enough clean transactional days.
  • A domain and its news. and notify. stream subdomains count their sending and clean days together, so marketing sent from news. unlocks on the transactional mail sent from the root or notify.
  • The first broadcast on a new domain is capped and goes to your most engaged contacts first. A campaign that needs a review is held until it is approved.
  • Warm-up pauses on its own when bounces or complaints go over the limits, and tells you why. Webhooks subscribed to mail.domain.warmup.paused, mail.domain.warmup.resumed and mail.domain.warmup.trusted tell your app.

​
Bridge mode

  • While your domain is warming, you can send through StackShift’s own warm address until your domain is trusted. GET /mail/domains/{domainId}/bridge shows whether it is available and active, and the host used.
  • Turn it on with PUT /mail/domains/{domainId}/bridge and { “enabled”: true }. includeTransactional chooses whether transactional mail also goes through the bridge.
  • Mail sent through the bridge comes From our address with your name as the display name and your address as Reply-To, so replies still reach you. The dashboard says plainly that mail comes from our address until your domain is trusted.
  • The bridge switches off automatically when the domain becomes trusted.

​
Checks before you send

  • POST /mail/presend/check returns canSend and a warnings list. The composer shows the same checks.
  • Findings include url_shortener, link_domain_mismatch, missing_text_part, no_reply_sender, sender_site_unreachable, brand_impersonation and spf_lookup_limit.
  • A finding marked blocking must be fixed before the message can send. Other findings explain the risk and how to fix it.

​
Where your mail lands

  • A seed test sends one message to our own test inboxes at the large providers and reports the folder at each: inbox, spam, promotions, other or not found. POST /mail/seed-tests starts it and GET /mail/seed-tests/{seedTestId} returns the result. GET /mail/domains/{domainId}/seed-tests/latest returns the most recent.
  • A seed test is a sample, not a guarantee. It is labelled as a sample check wherever it appears.
  • PUT /mail/domains/{domainId}/postmaster enables Google Postmaster data for your domain after you publish the verification record. GET returns what Google reports for the domain once it has enough volume.

​
DMARC

  • Publish the reporting address StackShift gives you in your DMARC record, then GET /mail/domains/{domainId}/dmarc to see the pass rate, SPF and DKIM alignment, and which sending sources are known and which are not.
  • Mark a source you recognise with PUT /mail/domains/{domainId}/dmarc/marks, and clear the mark with DELETE /mail/domains/{domainId}/dmarc/marks/{ip}.
  • The response includes a readiness signal and the next policy step. When canApply is true, POST /mail/domains/{domainId}/dmarc/apply publishes the next step for you, from none towards quarantine and then reject.

​
Mailbox mail

Mail people send from a mailbox uses the same authentication and goes out on its own stream, separate from your API and campaign mail.

​
Expected result

Your domain is authenticated, warmed on a schedule, monitored, and held back automatically before it can damage its own reputation.

​
Common failures

  • A broadcast is held with broadcast_domain_not_ready: the domain has not yet had enough clean transactional days. Send transactional mail first, or wait for the schedule.
  • Warm-up is paused: bounce or complaint rates went over the limit. Fix the cause, then resume with POST /mail/domains/{domainId}/warmup/resume.
  • Mail goes to spam at one provider: the seed test names the folder per provider. Check authentication, links and content before sending more.
  • The domain shows degraded health: a DNS record changed or expired. Repair it from the health issue, then verify again.

Sending-domain health

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

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.

Bounces, suppressions, and reputation

Handle hard and soft bounces, workspace-scoped suppressions, sending limits, warmup stage, domain reputation, and reputation events.

Mailboxes

Host real mailboxes on your own domain: add the domain, create mailboxes, aliases and groups, route addresses, bring mail over from another provider and connect any mail app.