Documentation

Send email

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

Try StackShiftRead the overview

Search Docs

StackShift Mail

Send email

Live

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

Goal

Queue a message safely and understand the exact response and lifecycle fields returned by StackShift Mail.

Current status

Live

This area is documented as current, user-reliable behavior.

Workflow

  1. 1Create a StackShift client with STACKSHIFT_API_KEY or an explicit apiKey.
  2. 2Call stackshift.mail.send with from, to, subject, and either html, text, or both.
  3. 3Pass idempotencyKey for retry-safe application workflows.
  4. 4Store the returned message id and inspect /mail/messages/{id}, /attempts, /logs, and /timeline when debugging.

TypeScript SDK

Example

ts
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

Example

bash
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

Example

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