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

# StackShift Mail overview

> A verified map of the current StackShift Mail surface: outbound send, sender domains, bounces, suppressions, templates, OTP, events, webhooks, reputation, scheduled mail, batch mail, inbound mail, attachments, and analytics.

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

## Goal

Understand exactly what StackShift Mail does today and which API surface owns each workflow.

## Prerequisites

* A StackShift API key with access to the workspace that will send mail
* A backend environment that can keep the API key server-side

## Workflow

<Steps>
  <Step>
    Use the mail API base URL, not the core API base URL, for Mail SDK calls.
  </Step>

  <Step>
    Verify every production sender domain before sending from it.
  </Step>

  <Step>
    Send individual messages directly, from a versioned template, as a scheduled message, or as a batch.
  </Step>

  <Step>
    Track message state through messages, attempts, logs, events, timelines, bounces, suppressions, and webhooks.
  </Step>

  <Step>
    Use limits and reputation endpoints before increasing volume.
  </Step>

  <Step>
    Use inbound domains only when you want StackShift to receive and store incoming email for a domain.
  </Step>
</Steps>

## API base URLs

* Mail SDK calls default to [https://api.stackshift.cloud/v1](https://api.stackshift.cloud/v1).
* Core project and asset SDK calls default to [https://api.stackshift.cloud/api/v1](https://api.stackshift.cloud/api/v1).
* Both TypeScript, Python, and Go clients expose a separate mailBaseUrl or MailBaseURL option for overriding the mail API target.
* Public mail routes are mounted under /v1/mail in the server router. Internal bounce and inbound ingestion routes are mounted separately under /internal/mail.

## Implemented public resource groups

* Sending: POST /mail/send and POST /mail/send-template.
* Messages: list, get, attempts, logs, timeline, and message-scoped bounces.
* Sender domains: create, list, get, verify, delete, and DNS record status.
* Templates: create, list, get, update, delete, versions, activate version, preview, test send, and send from template.
* OTP: send, verify, list challenges, get challenge, and cancel challenge.
* Bounces and suppressions: list bounces, list/create/delete suppressions, and automatic hard-bounce suppression.
* Events and webhooks: event list/get, message timeline, webhook CRUD, secret rotation, delivery list/detail, retry, and SDK signature verification.
* Reputation and limits: workspace/domain reputation, usage limits, warmup stage, manual review state, and reputation events.
* Advanced delivery and intake: scheduled messages, batch sends, batch-template sends, batch item inspection, inbound domains/messages, attachments, and analytics.

## Delivery status meaning

The Mail message status values are queued, sending, sent, deferred, failed, bounced, and suppressed. A sent message has been accepted into StackShift outbound MTA processing.

Use bounces, suppressions, message timelines, and webhook events to inspect what happens after MTA acceptance.

## Official SDK surfaces

* TypeScript: stackshift.mail with domains, messages, suppressions, bounces, otp, templates, events, webhooks, limits, reputation, scheduled, batch, inbound, and analytics clients.
* Python: stackshift.mail plus MailEventsClient, MailWebhooksClient, MailLimitsClient, MailReputationClient, and verify\_webhook\_signature exports.
* Go: client.Mail with Domains, Messages, Suppressions, Bounces, Templates, Events, Webhooks, Limits, Reputation, OTP, Scheduled, Batch, Inbound, and Analytics clients.

## Expected result

<Check>
  You can choose the correct StackShift Mail API for each email workflow and avoid relying on assumptions that are not implemented.
</Check>

## Related guides

<CardGroup cols={2}>
  <Card title="Send email" href="/stackshift-mail/send-email">
    Send a single outbound email with the official SDK or REST API, then inspect the message, attempts, logs, and timeline.
  </Card>

  <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="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>

  <Card title="Bounces, suppressions, and reputation" href="/stackshift-mail/bounces-suppressions-and-reputation">
    Handle hard and soft bounces, workspace-scoped suppressions, sending limits, warmup stage, domain reputation, and reputation events.
  </Card>

  <Card title="Scheduled, batch, inbound, attachments, and analytics" href="/stackshift-mail/scheduled-batch-inbound-and-analytics">
    Use the Mail APIs for scheduled delivery, batch sending, batch-template sending, inbound domain capture, asset-backed attachments, and aggregate analytics.
  </Card>
</CardGroup>