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

# Ghost transactional mail and newsletters

> Use StackShift Mail for Ghost transactional messages, select a verified sender, and optionally connect Mailgun for Ghost bulk newsletters without exposing provider secrets.

<Warning>
  **Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
</Warning>

## Goal

Configure the two distinct Ghost email paths correctly: StackShift Mail for transactional delivery and Mailgun for bulk newsletters.

## Prerequisites

* A running native Ghost project
* A verified StackShift Mail domain for a branded transactional sender
* A Mailgun account, sending domain, and API key only if newsletters are required

## Workflow

<Steps>
  <Step>
    Start with the generated StackShift transactional sender.
  </Step>

  <Step>
    Optionally verify your own sender domain in StackShift Mail.
  </Step>

  <Step>
    Save an address on the verified domain as the Ghost transactional sender.
  </Step>

  <Step>
    If you send newsletters, add the Mailgun domain, region, from address, and API key.
  </Step>

  <Step>
    Send controlled transactional and newsletter tests to verify both paths independently.
  </Step>
</Steps>

## Two mail paths

* Transactional mail includes staff invitations, member sign-in links, password resets, and other application messages. It uses SMTP to the private StackShift bridge, which forwards into StackShift Mail.
* Bulk newsletter mail uses Ghost’s Mailgun integration. It does not replace the transactional bridge.
* Removing Mailgun disables the newsletter provider configuration but leaves transactional StackShift Mail active.

## Default transactional sender

Each production installation receives a unique address on the StackShift-controlled Ghost sender domain. The address includes the project ID and uses a platform-managed, DKIM-signed domain. This lets fresh sites send transactional messages without sharing a reusable SMTP credential.

## Use your own verified sender

* Add and verify the domain in StackShift Mail first.
* Enter a complete sender address, not only a domain.
* StackShift accepts the shared platform domain or a domain whose StackShift Mail status is verified.
* Changing the sender updates Ghost’s `mail__from` value and redeploys the native stack.
* The bridge overwrites the submitted From address with the installation’s approved sender, so Ghost cannot choose an unverified address at delivery time.

## How the private bridge is secured

* The mail service is not exposed by ingress.
* The bridge image is pinned by exact digest.
* Its credential is randomly generated, stored only as a hash in the control plane, and scoped to one Ghost project.
* The endpoint rejects disabled mail, non-running installations, invalid credentials, and a mismatched project header.
* Restore rotates the bridge credential; staging never copies it.

```text Transactional path theme={null}
Ghost web service
  -> private SMTP service `mail:2525`
  -> HTTPS internal StackShift Mail endpoint
  -> project-bound sender and StackShift Mail delivery pipeline
```

## Connect Mailgun for newsletters

* Enter the Mailgun sending domain.
* Choose US or EU so Ghost uses the matching Mailgun API base URL.
* Enter a newsletter From address and the Mailgun API key.
* The provider credential is stored in StackShift’s encrypted email-provider storage and is never returned to the dashboard.
* StackShift maps the provider into Ghost’s `bulkEmail__mailgun__apiKey`, `bulkEmail__mailgun__domain`, and `bulkEmail__mailgun__baseUrl` configuration and redeploys Ghost.

## Update or remove Mailgun

Saving a new key replaces the encrypted provider secret. The settings response exposes only safe fields such as domain, region, and whether a key exists. Removing Mailgun deletes the Ghost bulk-email environment mapping and then deletes the stored provider configuration.

## Test safely

* Use a small internal recipient list for the first newsletter.
* Test transactional member sign-in separately from newsletter delivery.
* Confirm SPF, DKIM, tracking, bounce handling, and sender alignment in the relevant provider.
* Never enable production outbound mail on a staging clone.

## Expected result

<Check>
  Ghost transactional messages flow through the private StackShift bridge with an approved sender, while newsletters use the separately configured Mailgun bulk-email settings.
</Check>

## Common failures

<Warning>
  * The transactional sender domain has not reached verified status in StackShift Mail.
  * A Mailgun US domain is configured with the EU region, or vice versa.
  * The API key is invalid or lacks permission for the sending domain.
  * The site is stopped or still provisioning, so its project-bound mail credential is not authorized.
  * Mailgun is expected to fix transactional delivery even though it configures only Ghost newsletters.
</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="Ghost troubleshooting and limitations" href="/ghost/troubleshooting-and-limitations">
    Diagnose native Ghost provisioning, database, image, routing, mail, recovery, staging, and upgrade failures using persisted operation state and clear resource boundaries.
  </Card>
</CardGroup>