> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Send email

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

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## 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

<Steps>
  <Step>
    Create a StackShift client with STACKSHIFT\_API\_KEY or an explicit apiKey.
  </Step>

  <Step>
    Call stackshift.mail.send with from, to, subject, and either html, text, or both.
  </Step>

  <Step>
    Pass idempotencyKey for retry-safe application workflows.
  </Step>

  <Step>
    Store the returned message id and inspect /mail/messages/\{id}, /attempts, /logs, and /timeline when debugging.
  </Step>
</Steps>

## TypeScript SDK

```ts theme={null}
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

```bash theme={null}
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

```ts theme={null}
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

<Check>
  The API returns a message id, status, and idempotencyStatus. The message is then visible in the message APIs and dashboard.
</Check>

## Common failures

<Warning>
  * Missing API key or wrong base URL. Mail uses [https://api.stackshift.cloud/v1](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.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Sender domains and DNS" href="/stackshift-mail/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.
  </Card>

  <Card title="Templates and OTP" href="/stackshift-mail/templates-and-otp">
    Create versioned templates, preview and test them, send from a template, and use the built-in one-time-code challenge flow.
  </Card>

  <Card title="Events, webhooks, and timelines" href="/stackshift-mail/events-webhooks-and-timelines">
    List mail events, inspect per-message timelines, subscribe webhooks, rotate secrets, retry deliveries, and verify webhook signatures.
  </Card>
</CardGroup>