# Newsletter sign-ups

Collects newsletter subscribers with explicit consent. When the base email settings are set up, each subscriber gets
a confirmation email (double opt-in) and is listed as `confirmed` after clicking it; otherwise sign-ups are stored as
`unconfirmed`. Every subscriber has a one-click unsubscribe link.

Requires the `base` package. Sending the newsletter itself is done from the owner's email tool with the exported list.

## Install

Use the verified installer in the website container. It installs dependencies, checks checksums, and refuses to replace customer changes:

```sh
python /opt/runalio/catalog_install.py newsletter
python /opt/runalio/catalog_install.py --status
```

Review the preview and click Publish to promote backend code and pages. Production data remains separate.

To undo the last installation before publishing: `python /opt/runalio/catalog_install.py --rollback`.

## Add it to a page

Copy `site/newsletter.js` into `/workspace/site`, then:

```html
<form data-runalio-newsletter>
  <label>Email <input name="email" type="email" required></label>
  <label><input name="consent" type="checkbox" value="yes" required> Send me the newsletter. I can unsubscribe at any time.</label>
  <input name="website" tabindex="-1" autocomplete="off" hidden>
  <button>Sign up</button>
  <p role="status"></p>
</form>
<script src="newsletter.js" defer></script>
```

The hidden `website` field catches bots. The consent sentence is stored with each subscriber.

## API

| Request | Purpose |
|---|---|
| `POST api/newsletter/subscribe` | `{email, consent: "yes", consent_text?}` |
| `GET api/newsletter/confirm?token=` | Confirmation link from the email |
| `GET` or `POST api/newsletter/unsubscribe?token=` | One-click unsubscribe |

## What the customer needs to do

1. Recommended: set up the base email settings (provider, API key, verified sender) for confirmation emails.
2. Download subscribers from the admin area (Newsletter subscribers, Download CSV). The CSV includes each
   unsubscribe link; include it in every newsletter.
3. Send newsletters from their email tool and only to `confirmed` (or, without email settings, `unconfirmed`) subscribers.