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.

POST

api

store

newsletter_subscribers

Spree SDK

import { createClient } from '@spree/sdk'

const client = createClient({
  baseUrl: 'https://your-store.com',
  publishableKey: '<api-key>',
})

const subscriber = await client.newsletterSubscribers.create({
  email: 'subscriber@example.com',
  redirect_url: 'https://your-store.com/newsletter/confirm',
})

curl --request POST \
  --url http://{defaultHost}/api/v3/store/newsletter_subscribers \
  --header 'Content-Type: application/json' \
  --header 'x-spree-api-key: <api-key>' \
  --data '
{
  "email": "subscriber@example.com",
  "redirect_url": "https://your-store.com/newsletter/confirm"
}
'

{
  "id": "sub_UkLWZg9DAJ",
  "email": "philip.jast@schadenhamill.biz",
  "created_at": "2026-07-11T15:39:29.709Z",
  "updated_at": "2026-07-11T15:39:29.711Z",
  "verified": true,
  "verified_at": "2026-07-11T15:39:29Z",
  "customer_id": "cus_UkLWZg9DAJ"
}

{
  "error": {
    "code": "validation_error",
    "message": "Email is invalid",
    "details": {
      "email": [
        "is invalid"
      ]
    }
  }
}

Authorizations

x-spree-api-key

string

header

required

Publishable API key for store access

Headers

x-spree-api-key

string

required

Authorization

string

Optional Bearer JWT — when present, links the subscription to that customer

Body

application/json

string<email>

required

Example:

"subscriber@example.com"

redirect_url

string<uri>

Storefront URL the verification token should be appended to. Silently omitted from the webhook payload when the store has allowed origins configured and this URL does not match one of them, or when no allowed origins are configured at all.

Example:

"https://your-store.com/newsletter/confirm"

Response

auto-verified when JWT matches subscribed email

string

required

string

required

created_at

string

required

updated_at

string

required

verified

boolean

required

verified_at

string | null

required

customer_id

string | null

required

Remove item from wishlist

Verify a newsletter subscription

⌘I

Spree SDK

import { createClient } from '@spree/sdk'

const client = createClient({
  baseUrl: 'https://your-store.com',
  publishableKey: '<api-key>',
})

const subscriber = await client.newsletterSubscribers.create({
  email: 'subscriber@example.com',
  redirect_url: 'https://your-store.com/newsletter/confirm',
})

curl --request POST \
  --url http://{defaultHost}/api/v3/store/newsletter_subscribers \
  --header 'Content-Type: application/json' \
  --header 'x-spree-api-key: <api-key>' \
  --data '
{
  "email": "subscriber@example.com",
  "redirect_url": "https://your-store.com/newsletter/confirm"
}
'

{
  "id": "sub_UkLWZg9DAJ",
  "email": "philip.jast@schadenhamill.biz",
  "created_at": "2026-07-11T15:39:29.709Z",
  "updated_at": "2026-07-11T15:39:29.711Z",
  "verified": true,
  "verified_at": "2026-07-11T15:39:29Z",
  "customer_id": "cus_UkLWZg9DAJ"
}

{
  "error": {
    "code": "validation_error",
    "message": "Email is invalid",
    "details": {
      "email": [
        "is invalid"
      ]
    }
  }
}