Templates and OTP

​

Goal

​

Prerequisites

• A StackShift API key
• A verified sender domain for production sends

​

Workflow

​

Template lifecycle

• Templates have active, archived, or deleted status.
• Every create or content update creates template version data with subject, html, text, variables, and versionNumber.
• A template can expose activeVersion and versions in detail responses.
• Preview renders subject, html, and text and returns missingVariables.
• Diagnostics analyze the rendered content for unsafe or unsupported markup, insecure links, missing text and image alternatives, remote-image/read-receipt risk, subject quality, and oversized HTML.
• Test send returns messageId and status.

​

Create, preview, and send a template

await stackshift.mail.templates.create({
  name: 'Welcome email',
  slug: 'welcome-email',
  subject: 'Welcome, {{firstName}}',
  html: '<h1>Welcome, {{firstName}}</h1>',
  text: 'Welcome, {{firstName}}',
})

const preview = await stackshift.mail.templates.preview('welcome-email', {
  data: { firstName: 'Ada' },
})

const message = await stackshift.mail.sendTemplate({
  template: 'welcome-email',
  from: 'noreply@example.com',
  to: 'ada@example.net',
  data: { firstName: 'Ada' },
  idempotencyKey: 'welcome_user_123_v1',
})

console.log(preview.missingVariables, message.id, message.status)

​

OTP challenge flow

const challenge = await stackshift.mail.otp.send({
  to: 'ada@example.net',
  from: 'security@example.com',
  purpose: 'login',
  expiresIn: '10m',
  codeLength: 6,
  brandName: 'Example App',
  idempotencyKey: 'login_ada_2026_05_10',
})

const result = await stackshift.mail.otp.verify({
  challengeId: challenge.id,
  code: '123456',
})

console.log(result.verified, result.status)

​

OTP challenge states

• Challenge status is pending, verified, expired, failed, or canceled.
• Responses include attempts, maxAttempts, attemptsRemaining, expiresAt, resendAvailableAt, and optional messageId.
• Admin-style challenge APIs can list, fetch, and cancel challenges.

​

Expected result

​

Common failures

​

Related guides