---
title: "Subscribe an email address to the newsletter"
method: POST
path: "/api/newsletter/subscribe"
tags: ["account"]
---

# Subscribe an email address to the newsletter

`POST /api/newsletter/subscribe`

## Request

- Base URL: `https://voltplan.app`
- URL: `https://voltplan.app/api/newsletter/subscribe`
- Auth: none required

No authentication. Uses an unauthenticated PocketBase client (`POCKETBASE_URL`); no superuser client is involved.

- `email` is only checked for presence: it is not trimmed, lowercased or format-validated and is used verbatim.
- An existing `users` record with this email (or a PocketBase `validation_not_unique` error on `email`) answers 200 with `isExisting: true`.
- Otherwise a `users` record is created via `POST <POCKETBASE_URL>/api/collections/users/records` with a random server-side password, `name` derived from the email local part, `emailVisibility: false`, `newsletter_source` (= `source`, default `landing_page`) and `newsletter_subscribed_at`. The PocketBase verification email is then requested; a failure there is ignored. The answer is 200 with `needsVerification: true`.
- Any other PocketBase failure answers 500 `Failed to subscribe`; a non-JSON or `null` body answers 500 `Internal server error`.

## Request body

- NewsletterSubscribeRequest
  - `email` string, required: Only checked for presence; not trimmed, lowercased or format-validated.
  - `source` string: Sign-up origin stored as `newsletter_source`.

## Response `200`

Account created (verification pending) or already subscribed.

- union: New account awaiting verification, or an already subscribed address.
  - NewsletterSubscribeCreatedResponse: Account created; the PocketBase verification email was requested.
    - `success` unknown, required
    - `message` 'Please check your email to verify your subscription', required
    - `needsVerification` unknown, required
  - NewsletterSubscribeExistingResponse: An account with this email already exists.
    - `success` unknown, required
    - `message` 'Already subscribed', required
    - `isExisting` unknown, required

## Other responses

- `400`: `email` missing or empty.
- `500`: PocketBase failed, or the body could not be read.

---

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