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

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

  • Missing API key or wrong base URL. Mail uses https://api.stackshift.cloud/v1 by default.
  • Sender domain is not verified, disabled, or missing required DNS records.
  • Recipient is suppressed because of a hard bounce, manual block, repeated soft bounce, complaint, blocked status, or unsubscribe.
  • Request is missing both html and text bodies.

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.