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

Send email

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

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.

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.

Scheduled, batch, inbound, attachments, and analytics

Use the Mail APIs for scheduled delivery, batch sending, batch-template sending, inbound domain capture, asset-backed attachments, and aggregate analytics.