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

# Automated Newsletter Dogfooding

> How Quixa visual flows orchestrate automated email campaigns and recurring dispatches with zero third-party marketing bloat.

At Quixa, we believe in **drinking our own champagne**. Instead of relying on expensive external marketing automation SaaS platforms with rigid schemas and vendor lock-in, **The Quixa Dispatch** is powered entirely by Quixa's visual workflow engine, scheduled triggers, and REST endpoints.

***

## 1. Architecture Overview

The automated newsletter pipeline operates on a decoupled architecture comprising a dedicated subscriber repository, secured management endpoints, and a visual workflow executed on a recurring cron schedule.

```mermaid theme={null}
graph LR
    subgraph Trigger
        Cron[Scheduled Cron Trigger]
    end

    subgraph Quixa Visual Workflow
        Fetch[HTTP: Get Active Subscribers]
        Loop[For Loop: Iterate Recipients]
        Send[HTTP: Dispatch Dispatch Email]
        Throttle[Wait: 250ms Rate Limit]
        Stop[Stop Flow: Complete]
    end

    subgraph Quixa API & Email Gateway
        SubscribersDB[(NewsletterSubscribers)]
        SMTP[Email Gateway / Resend]
    end

    Cron --> Fetch
    Fetch -->|subscribers array| Loop
    Loop -->|per subscriber| Send
    Send --> Throttle
    Throttle --> Loop
    Loop -->|complete| Stop
    Fetch -.-> SubscribersDB
    Send -.-> SMTP
```

***

## 2. API Endpoints

The newsletter subsystem provides five core endpoints under `/api/newsletter`:

| Method | Endpoint | Access | Purpose |
| :- | :- | :- | :- |
| `POST` | `/api/newsletter/subscribe` | Public | Subscribes an email address with IP and referrer tracking. |
| `GET` | `/api/newsletter/unsubscribe` | Public | One-click unsubscribe link with responsive HTML confirmation. |
| `GET` | `/api/newsletter/subscribers` | Protected | Fetches active subscriber batches for the workflow loop. |
| `POST` | `/api/newsletter/send` | Protected | Renders and dispatches the HTML dispatch issue to a recipient. |
| `GET` | `/api/newsletter/preview` | Public | In-browser preview of the rendered dark-mode template. |

### Subscribing a User

```bash theme={null}
curl -X POST https://api.example.com/api/newsletter/subscribe \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "source": "website_footer"
  }'
```

### Fetching Active Subscribers

```bash theme={null}
curl -X GET "https://api.example.com/api/newsletter/subscribers?status=Active&page=1&pageSize=100" \
  -H "X-Newsletter-Secret: qxa_live_YOUR_KEY"
```

***

## 3. The Visual Workflow Recipe

You can build this automated campaign directly on the Quixa Canvas using the following drag-and-drop recipe:

### Step 1: Fetch Active Subscribers Node

* **Node Type**: `http`
* **Method**: `GET`
* **URL**: `https://api.example.com/api/newsletter/subscribers?status=Active`
* **Headers**: `X-Newsletter-Secret: {{variables.NEWSLETTER_SECRET}}`

### Step 2: For-Loop Iterator Node

* **Node Type**: `for`
* **Collection**: `{{GetSubscribers.response.subscribers}}`
* **Item Variable**: `subscriber`
* **Index Variable**: `loopIndex`

### Step 3: Dispatch Issue Node

* **Node Type**: `http`
* **Method**: `POST`
* **URL**: `https://api.example.com/api/newsletter/send`
* **Headers**:
  * `Content-Type: application/json`
  * `X-Newsletter-Secret: {{variables.NEWSLETTER_SECRET}}`
* **Payload**:

```json theme={null}
{
  "recipientEmail": "{{subscriber.email}}",
  "unsubscribeToken": "{{subscriber.unsubscribeToken}}",
  "subject": "The Quixa Dispatch: docs.quixa.io is Live, Switch Routers & Dogfooding"
}
```

### Step 4: Rate-Limit Throttle

* **Node Type**: `wait`
* **Duration**: `250ms` (fixed buffer to stay within SMTP or provider limits).

### Step 5: Terminal Completion Node

* **Node Type**: `stop`
* **Scope**: `terminate-flow`
* **Exit Status**: `Completed`
* **Message**: `Newsletter campaign execution completed successfully.`

***

## 4. Unsubscription & GDPR Compliance

Every email dispatched includes an RFC-compliant one-click unsubscribe URL containing an unguessable 128-bit cryptographic GUID token:

```text theme={null}
https://api.example.com/api/newsletter/unsubscribe?token=3f8a1b2c4d5e6f7a8b9c0d1e2f3a4b5c
```

When clicked:

1. The subscriber's status is atomically changed from `Active` to `Unsubscribed`.
2. The `UnsubscribedAt` timestamp is recorded.
3. Subsequent workflow dispatch requests for this email address are immediately rejected with HTTP `400 Bad Request`.
4. The user is presented with a branded, dark-mode confirmation page with options to return to the homepage or resubscribe.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.