Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Understand exactly what StackShift Mail does today and which API surface owns each workflow.

​
Prerequisites

  • A StackShift API key with access to the workspace that will send mail
  • A backend environment that can keep the API key server-side

​
Workflow

1
Use the mail API base URL, not the core API base URL, for Mail SDK calls.
2
Choose Live for actual delivery or create a Test credential for isolated simulation; Test requires no domain verification.
3
Verify every production sender domain before sending from it. Create an explicit brand before creating an audience.
4
Send individual messages directly, from a versioned template, as a scheduled message, or as a batch.
5
Track message state through messages, attempts, logs, events, timelines, bounces, suppressions, and webhooks.
6
Use limits and reputation endpoints before increasing volume.
7
Use inbound domains only when you want StackShift to receive and store incoming email for a domain.

​
API base URLs

  • Mail SDK calls default to https://api.stackshift.cloud/v1.
  • Core project and asset SDK calls default to https://api.stackshift.cloud/api/v1.
  • TypeScript, Python, and Go clients expose a separate mailBaseUrl or MailBaseURL option for overriding the mail API target.
  • Public mail routes are mounted under /v1/mail in the server router. Internal bounce and inbound ingestion routes are mounted separately under /internal/mail.

​
Implemented public resource groups

  • Sending: POST /mail/send and POST /mail/send-template.
  • Messages: list, get, attempts, logs, timeline, and message-scoped bounces.
  • Sender domains: create, list, get, verify, delete, and DNS record status.
  • Templates: create, list, get, update, delete, versions, activate version, preview, deterministic content diagnostics, test send, and send from template.
  • OTP: send, verify, list challenges, get challenge, and cancel challenge.
  • Bounces and suppressions: list bounces, list/create/delete suppressions, and automatic hard-bounce suppression.
  • Events and webhooks: event list/get, message timeline, webhook CRUD, secret rotation, delivery list/detail, retry, and SDK signature verification.
  • Reputation and limits: workspace/domain reputation, usage limits, warmup stage, manual review state, and reputation events.
  • Brands, shared contacts and consent: explicit brandId on audiences, import previews with row-level reasons, double opt-in and branded preferences/unsubscribe pages.
  • Campaigns: guided content drafts, template/preset selection, image uploads, A/B variants, previews/tests, scheduling, cost estimates and whole-campaign budget reservation.
  • Public DNS audit and provider migration guides use /api/v1/mail/audit, /migration-plan and /migration-guides. Authenticated checklist progress uses /v1/mail/migration/checklist.
  • Mail spending uses included recipients plus explicitly opted-in, capped Mail-only prepaid funds; no launch prices are assumed before administrator rate-card activation.
  • Advanced delivery and intake: scheduled messages, batch sends, batch-template sends, batch item inspection, inbound domains/messages, attachments, and analytics.
  • Exports: asynchronous recipient-delivery JSONL exports encrypted with the production object-storage KMS key and retained for seven days.
  • Diagnostics and previews: rendered-content checks for unsafe links, active elements, compatibility, accessibility, remote-image/read-receipt risk, and message size; plus sandboxed local previews with no paid rendering-provider dependency.

​
Delivery status meaning

The Mail message status values are queued, sending, mta_accepted, delayed, delivered, bounced, failed, suppressed, complained, and partial. Delivered means the recipient MX accepted the message; it does not claim inbox placement or human receipt. Use bounces, suppressions, message timelines, and webhook events to inspect what happens after MTA acceptance.

​
Official SDK surfaces

  • TypeScript: stackshift.mail includes streams, audiences, campaigns, exports, diagnostics, delivery, inbound, and operations clients.
  • Python: stackshift.mail includes streams, audiences, campaigns, exports, diagnostics, events, webhooks, reputation, inbound, and analytics clients.
  • Go: client.Mail includes Streams, Audiences, Campaigns, Exports, template Diagnostics, delivery, inbound, and operations clients.

​
Expected result

You can choose the correct StackShift Mail API for each email workflow and avoid relying on assumptions that are not implemented.

Test environment

Exercise delivery, bounce, complaint and delay paths with isolated Mail data and no real email delivery.

Brands and shared contacts

Create explicit sending identities and share contact profiles within a brand while keeping audience consent independent.

Subscriber consent and imports

Preview imports row by row, preserve consent evidence and use double opt-in before marketing delivery.

Tracking and engagement

Configure optional open/click tracking and interpret engagement without confusing automated activity with human reads.

Sending-domain health

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

Domain audit and migration

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

Mail spending controls

Inspect recipient allowance and reserve capped Mail-only prepaid credit without automatic additional spending.

Send email

Send a single outbound email with the official SDK or REST API, then inspect the message, attempts, logs, and timeline.

SMTP submission

Submit existing MIME email through authenticated TLS while retaining StackShift Mail policy, delivery evidence, and attachment scanning.

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.

Streams, audiences, and campaigns

Separate transactional and broadcast traffic, retain consent evidence, and build private campaign drafts with unsubscribe protection.

Inbound mail

Receive mail on verified domains, inspect parsed messages, and securely download scanned raw messages and attachments.

Diagnostics, analytics, and exports

Diagnose rendered templates, measure Mail operations, and create encrypted recipient-level delivery exports.

Events, webhooks, and timelines

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

Bounces, suppressions, and reputation

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

Scheduling, batches, and attachments

Use first-class Mail APIs for delayed delivery, direct or template fan-out, batch inspection, and scanned asset-backed attachments.