Skip to content

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.

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.

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.

With audience() installed it errors until:

  • a finished privacy page exists (you are collecting email addresses), and
  • AUDIENCE_PROVIDER names 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.

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

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.