Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
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

1
Connect to smtp.mail.stackshift.cloud on port 587 with STARTTLS or port 465 with implicit TLS.
2
Authenticate with PLAIN or LOGIN. Use a non-empty application label as the username and the API key as the password.
3
Submit the MIME message with a verified From domain and authoritative envelope recipients.
4
Inspect the resulting message through the same events, timelines, limits, suppressions, and delivery APIs used by native sends.

​
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

​
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

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

​
Common failures

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

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.

Events, webhooks, and timelines

List mail events, inspect per-message timelines, subscribe webhooks, rotate secrets, retry deliveries, and verify webhook signatures.

Bounces, suppressions, and reputation

Handle hard and soft bounces, workspace-scoped suppressions, sending limits, warmup stage, domain reputation, and reputation events.