Goal
Queue a message safely and understand the exact response and lifecycle fields returned by StackShift Mail.Prerequisites
- A StackShift API key
- A verified sender domain for production sending
- A backend process, server route, or worker that can keep the API key private
Workflow
1
Create a StackShift client with STACKSHIFT_API_KEY or an explicit apiKey.
2
Call stackshift.mail.send with from, to, subject, and either html, text, or both.
3
Pass idempotencyKey for retry-safe application workflows.
4
Store the returned message id and inspect /mail/messages/{id}, /attempts, /logs, and /timeline when debugging.
TypeScript SDK
REST request
Accepted address shapes
- from accepts a string email address or an object with email and optional name.
- to, cc, and bcc accept a string, an address object, an array of strings, or an array of address objects.
- replyTo accepts a string email address or an address object.
- attachments accept assetId or uploadId plus filename and optional contentType.
Debug after send
Expected result
The API returns a message id, status, and idempotencyStatus. The message is then visible in the message APIs and dashboard.
Common failures
Related guides
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.
Templates and OTP
Create versioned templates, preview and test them, send from a template, and use the built-in one-time-code challenge flow.
Events, webhooks, and timelines
List mail events, inspect per-message timelines, subscribe webhooks, rotate secrets, retry deliveries, and verify webhook signatures.