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

# SMTP submission

> Submit existing MIME email through authenticated TLS while retaining StackShift Mail policy, delivery evidence, and attachment scanning.

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

## Goal

Connect an existing framework, CMS, or SMTP-aware application to StackShift Mail without replacing its mail integration.

## Prerequisites

* A verified sender domain
* A StackShift API key with `mail:send`
* A server-side SMTP client that validates TLS certificates

## Workflow

<Steps>
  <Step>
    Connect to smtp.mail.stackshift.cloud on port 587 with STARTTLS or port 465 with implicit TLS.
  </Step>

  <Step>
    Authenticate with PLAIN or LOGIN. Use a non-empty application label as the username and the API key as the password.
  </Step>

  <Step>
    Submit the MIME message with a verified From domain and authoritative envelope recipients.
  </Step>

  <Step>
    Inspect the resulting message through the same events, timelines, limits, suppressions, and delivery APIs used by native sends.
  </Step>
</Steps>

## Connection settings

* Host: `smtp.mail.stackshift.cloud`.
* STARTTLS: port `587`; implicit TLS: port `465`.
* Authentication: `PLAIN` or `LOGIN`, only after TLS is active.
* Password: a server-side StackShift API key with `mail:send`.

## Nodemailer example

```ts theme={null}
import nodemailer from 'nodemailer'

const transport = nodemailer.createTransport({
  host: 'smtp.mail.stackshift.cloud',
  port: 587,
  secure: false,
  requireTLS: true,
  auth: { user: 'stackshift', pass: process.env.STACKSHIFT_API_KEY },
})

await transport.sendMail({ from: 'Example <noreply@example.com>', to: 'ada@example.net', subject: 'Receipt', text: 'Payment received.' })
```

## StackShift SMTP headers and attachments

* `X-Stackshift-Stream` selects a transactional or broadcast stream slug.
* `X-Stackshift-List-Unsubscribe: true` enables broadcast unsubscribe handling.
* `X-Stackshift-Tag-<name>` adds a lowercase message tag value.
* Attachments are imported into private Assets storage, scanned, and accepted only after a clean verdict.
* Exact duplicate submissions reuse a derived idempotency identity based on workspace, envelope, recipients, and MIME content.

## Expected result

<Check>
  The SMTP message enters the normal StackShift Mail delivery pipeline and remains observable through customer Mail APIs.
</Check>

## Common failures

<Warning>
  * Authenticating before STARTTLS on port 587.
  * Using a key without `mail:send` or outside its allowed sender domains.
  * Selecting a broadcast stream without one-click unsubscribe behavior.
  * Submitting an attachment that fails type, size, or malware checks.
</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="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>
</CardGroup>