Email-list signup
An optional endpoint, POST /api/subscribe/, that adds an address to a list at
Resend, Buttondown, ConvertKit or Mailchimp. Nothing is stored on your site.
It is off unless you install it. The endpoint is not under src/pages, so a
site that never installs it has no such route, no dormant handler and no
outbound call. Whether it exists is decided by a line in astro.config.mjs,
never by an environment variable at build time.
Install
Section titled “Install”The starter’s astro.config.mjs carries the three changes, commented out.
Uncomment them:
import { audience, audienceRoutes } from './src/integrations/audience.mjs';
// in integrations, before the guard:audience(),stratolmsGuard({ onDemandRoutes: ON_DEMAND_ROUTES, featureRoutes: [...enabledFeatureRoutes(stratoConfig), ...audienceRoutes],}),The guard refuses any route under /api it was not told about. If you install
audience() but leave featureRoutes alone, the build fails with
STRATO_ROUTE_SHADOWED. That is the guard working, not a bug.
Configure
Section titled “Configure”| Variable | Meaning |
|---|---|
AUDIENCE_PROVIDER |
resend, buttondown, convertkit or mailchimp |
AUDIENCE_API_KEY |
The provider key. RESEND_API_KEY, BUTTONDOWN_API_KEY, CONVERTKIT_API_KEY or MAILCHIMP_API_KEY also work |
AUDIENCE_LIST_ID |
Required for ConvertKit (form id) and Mailchimp (list id); optional segment for Resend |
Set them where your host reads runtime variables. They are read on each request.
What stratolms check enforces
Section titled “What stratolms check enforces”With audience() installed it errors until:
- a finished privacy page exists (you are collecting email addresses), and
AUDIENCE_PROVIDERnames a supported provider and a key, and where the provider needs one a list id, are set.
Without audience() it asks for neither. A commented-out import does not count
as installed.
Behaviour
Section titled “Behaviour”- A valid address makes one call to your provider and returns
{"ok":true}. - Cross-origin requests are refused with 403; an invalid address with 400.
- Unconfigured, or with a provider failure, it returns 503
{"ok":false,"error":"unavailable"}. It never reports success for an address it did not send, and never echoes provider messages. - Post to
/api/subscribe/with the trailing slash. The site redirects a slashless URL and a redirect turns the POST into a GET.
Not included
Section titled “Not included”The starter does not place SubscribeForm on any page; add it where you want
it. Double opt-in and unsubscribe are your provider’s features. Rate-limit the
endpoint at your host or CDN as you would any public form (see
the threat model). Without JavaScript the form
shows the endpoint’s JSON response. Add a creator-owned result page if you need
a separate no-JavaScript confirmation flow.