Subscribe to the newsletter

Subscribes an email address to the newsletter for the current store.

Behavior:

• If the email is already verified for this store, the existing subscription is returned unchanged.
• If the request is unauthenticated (guest), the subscription is created in an unverified state and two events are published: newsletter_subscriber.subscription_requested (carrying the verification_token and the validated redirect_url, intended for headless storefronts that want to send the confirmation email themselves via a webhook handler) and the legacy newsletter_subscriber.subscribed lifecycle event (which the bundled spree_emails package listens to and uses to send a default confirmation email). The confirmation link should point at redirect_url?token=<verification_token> and call POST /newsletter_subscribers/verify when the user clicks it.
• If the request is authenticated via JWT and the customer’s email matches the subscribed email, the subscription is auto-verified and no events are fired — the JWT already proves email ownership, so no confirmation email is needed.

The optional redirect_url is where the verification token should land on the storefront. The server does not return a validation error when the URL is outside the store’s Allowed Origins; instead, the URL is silently omitted from the webhook payload (secure-by-default). When no allow-list is configured on the store, the URL is also omitted. Callers therefore receive the same 201 regardless, and the webhook handler should fall back to the store’s storefront URL when redirect_url is missing from the payload.

Newsletter consent is preserved across registration: if a guest subscribes and later registers with the same email, the existing subscriber record is reused.