---
title: "Newsletter Subscribe"
method: POST
path: "/api/v1/newsletter/subscribe"
tags: ["newsletter"]
---

# Newsletter Subscribe

`POST /api/v1/newsletter/subscribe`

## Request

- Base URL: `https://statsmapped.com`
- URL: `https://statsmapped.com/api/v1/newsletter/subscribe`
- Auth: none declared

Capture a newsletter sign-up and email a double opt-in confirmation link.

Creates a new `newsletter_subscribers` row, or refreshes an existing one for
the same email (spec section 5 step 1: "creates (or reuses, if the email
already has a row)") -- an already-`active` subscriber resubmitting the form
keeps their active status (a duplicate confirmation email is harmless; losing
an existing subscription to an accidental double-submit would not be), every
other status is reset to `pending_verification` with a fresh token.

Same failure-handling shape as submit_feedback(): a failed SEND does not fail
the request -- the row is already durably stored -- but is surfaced via
`email_sent: false` rather than hidden.

## Request body

- NewsletterSubscribe
  - `email` string, required
  - `consent_source` string

## Response `200`

Successful Response

- NewsletterSubscribeResult
  - `country` string
  - `status` string, required
  - `email_sent` boolean, nullable

## Other responses

- `400`: Bad request
- `401`: Missing or invalid credentials
- `403`: Not authorized for this request
- `404`: Not found
- `422`: Validation error
- `429`: Rate limited

---

[API](https://skmtc.dev/statsmapped/apis/statsmapped-api.md) · [All operations](https://skmtc.dev/statsmapped/apis/statsmapped-api/llms.txt) · [OpenAPI document](https://skmtc.dev/statsmapped/apis/statsmapped-api/revisions/7c5b264d05b7?raw)