Newsletters

Overview

Newsletters track email subscription consent for marketing communications. Each record stores the subscriber's email, consent details, and which lists they've subscribed to.

How It Works

Collect consent - Capture email and consent when a visitor subscribes to your newsletter
Assign to lists - Organize subscribers into different mailing lists
Track source - Record where the subscription originated for compliance

Example: A visitor enters their email in your footer signup form. Create a newsletter record with their email, the consent URL, and assign them to your "Weekly Updates" list.

API Endpoints

Method	Endpoint	Description
`GET`	List newsletters	Retrieve a paginated list of newsletter subscribers
`POST`	Create newsletter	Create a new newsletter subscriber
`GET`	Get newsletter	Retrieve a specific newsletter subscriber
`PUT`	Update newsletter	Update a newsletter subscriber
`DELETE`	Delete newsletter	Permanently delete a newsletter subscriber

Important Behaviors

Source normalization: The source field is automatically lowercased before storage. Submitting Web stores as web.
Hard delete: Deleting a newsletter permanently removes the record and all its history. This is not reversible.
Consent defaults: When consent_url, consent_ip, consent_text, or consent_type are omitted on create/update, they are stored as empty strings ("") not null.
Email uniqueness: Email must be unique per site. Duplicate emails on different sites are allowed.
Update requires email + source: Both email and source are required on every update call, not just on create.

Source Values

Value	Description
`web`	Signed up via website
`phone`	Signed up via phone
`mail`	Signed up via physical mail
`other`	Other source

Newsletter Object

Attribute	Type	Description
`id`	integer	Unique identifier for the newsletter subscriber
`email`	string	Subscriber's email address (unique per site)
`first_name`	string\|null	Subscriber's first name
`last_name`	string\|null	Subscriber's last name
`source`	string	Signup source: `web`, `phone`, `mail`, or `other`
`lists`	string\|null	Free-text field for list assignments (no format enforced)
`consent_url`	string	URL where consent was given (defaults to `""`)
`consent_ip`	string	IP address when consent was given (must be valid IPv4/IPv6, defaults to `""`)
`consent_text`	string	Consent text shown to subscriber (defaults to `""`)
`consent_type`	string	Type of consent given (defaults to `""`)
`postal_code`	string\|null	Subscriber's postal code (max 10 chars)
`created_at`	integer	Unix timestamp of creation
`updated_at`	integer	Unix timestamp of last update