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

import { StackShift } from '@stackshift-cloud/sdk'

const stackshift = new StackShift({
  apiKey: process.env.STACKSHIFT_API_KEY!,
})

const message = await stackshift.mail.send({
  from: { email: 'noreply@example.com', name: 'Example App' },
  to: [{ email: 'ada@example.net', name: 'Ada' }],
  subject: 'Your receipt is ready',
  html: '<p>Your receipt is attached.</p>',
  text: 'Your receipt is attached.',
  idempotencyKey: 'receipt_12345_v1',
})

console.log(message.id, message.status, message.idempotencyStatus)

​
REST request

curl -X POST 'https://api.stackshift.cloud/v1/mail/send' \
  -H 'Authorization: Bearer $STACKSHIFT_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": {"email": "noreply@example.com", "name": "Example App"},
    "to": [{"email": "ada@example.net", "name": "Ada"}],
    "subject": "Your receipt is ready",
    "html": "<p>Your receipt is attached.</p>",
    "text": "Your receipt is attached.",
    "idempotencyKey": "receipt_12345_v1"
  }'

​
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

const detail = await stackshift.mail.messages.get(message.id)
const attempts = await stackshift.mail.messages.attempts(message.id)
const logs = await stackshift.mail.messages.logs(message.id)
const timeline = await stackshift.mail.messages.timeline(message.id)

console.log(detail.status, attempts.data, logs.data, timeline.data)

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