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
Verify every production sender domain before sending from it.
3
Send individual messages directly, from a versioned template, as a scheduled message, or as a batch.
4
Track message state through messages, attempts, logs, events, timelines, bounces, suppressions, and webhooks.
5
Use limits and reputation endpoints before increasing volume.
6
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.
  • Both 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.
  • Audiences and campaigns: consent-evidenced member imports and template-backed sends on the isolated broadcast stream.
  • 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.

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 send template-backed campaigns 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.