Documentation

StackShift Mail overview

A verified map of the current StackShift Mail surface: outbound send, sender domains, bounces, suppressions, templates, OTP, events, webhooks, reputation, scheduled mail, batch mail, inbound mail, attachments, and analytics.

Try StackShiftRead the overview

Search Docs

StackShift Mail

StackShift Mail overview

Live

A verified map of the current StackShift Mail surface: outbound send, sender domains, bounces, suppressions, templates, OTP, events, webhooks, reputation, scheduled mail, batch mail, inbound mail, attachments, and analytics.

Goal

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

Current status

Live

This area is documented as current, user-reliable behavior.

Workflow

  1. 1Use the mail API base URL, not the core API base URL, for Mail SDK calls.
  2. 2Verify every production sender domain before sending from it.
  3. 3Send individual messages directly, from a versioned template, as a scheduled message, or as a batch.
  4. 4Track message state through messages, attempts, logs, events, timelines, bounces, suppressions, and webhooks.
  5. 5Use limits and reputation endpoints before increasing volume.
  6. 6Use 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, 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.
  • Advanced delivery and intake: scheduled messages, batch sends, batch-template sends, batch item inspection, inbound domains/messages, attachments, and analytics.

Delivery status meaning

The Mail message status values are queued, sending, sent, deferred, failed, bounced, and suppressed. A sent message has been accepted into StackShift outbound MTA processing.

Use bounces, suppressions, message timelines, and webhook events to inspect what happens after MTA acceptance.

Official SDK surfaces

  • TypeScript: stackshift.mail with domains, messages, suppressions, bounces, otp, templates, events, webhooks, limits, reputation, scheduled, batch, inbound, and analytics clients.
  • Python: stackshift.mail plus MailEventsClient, MailWebhooksClient, MailLimitsClient, MailReputationClient, and verify_webhook_signature exports.
  • Go: client.Mail with Domains, Messages, Suppressions, Bounces, Templates, Events, Webhooks, Limits, Reputation, OTP, Scheduled, Batch, Inbound, and Analytics clients.

Expected result

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