# Overview.Admin ## What it does Newsletter captures site-specific subscribers and consent evidence, groups them with tags and segments, and synchronises eligible people to Mailchimp, Kit, or Campaign Monitor. Capell owns subscription state, confirmation and preference links, imports, and send handoff records; campaign authoring, test sends, delivery, and open/click analytics remain in the connected provider. ## Setup requirements Run the package and settings migrations, configure application mail, and keep both Laravel's scheduler and a queue worker running. Capell-owned double opt-in sends its confirmation email through the application's mail channel. Provider synchronisation and scheduled-send handoffs run as queued jobs. The package schedules: - `newsletter:handoff-due-sends` every minute to claim due send records and queue their external handoff; - `newsletter:sync-retry-due` every five minutes to requeue provider attempts whose retry time has arrived. Before scheduling a send, the host application must register a `NewsletterSendHandoff` transport or a listener for the handoff event. Without one, send creation is rejected. Use Newsletter Diagnostics to check the transport, listener, storage tables, webhook idempotency store, segment evaluation, and exhausted sync attempts. ## Configure subscription capture Open **Marketing Studio > Advanced** and configure these in order: 1. Add a **Provider Connection** for the correct site, credentials, webhook secret, and provider. Credentials, OAuth tokens, and webhook secrets are encrypted in the database and are not loaded back into the edit form; leave credentials blank to preserve the stored values. 2. Add a **Provider Audience** that maps the site connection to the remote audience. Disabled connections do not receive sync attempts. 3. Add **Provider Interest Mappings** when newsletter tags should become provider interests. 4. Add an active **Form Mapping** for each Form Builder form that should create subscribers. Map the email and optional name/consent/tag fields, then choose whether Capell or the provider owns confirmation. Public subscription requests are attached to the current frontend site and use double opt-in by default. Capell-owned confirmation tokens expire after 72 hours by default. An expired link offers a private form that can email a fresh link, while a rapid repeat request reuses the outstanding token without sending another email during the default ten-minute cooldown. Provider-owned confirmation queues the pending subscriber to the provider instead. Set the default and per-site resubscribe policy in **Newsletter** package settings. Unsubscribed people require double opt-in again by default. Bounced, complained, and suppressed addresses are globally suppressed: anonymous resubscribe attempts do not restore them, and no new provider sync is queued for them. ## Operate subscribers and audiences Use **Marketing Studio > Subscribers** to filter by site, status, or exact email, and to create or edit the site, identity, and status. A manual status change is recorded through the subscriber lifecycle and queues provider synchronisation where appropriate, but the edit form does not collect detailed consent evidence; use a mapped form or an import with a truthful consent basis when evidence is required. Use **Newsletter Tags** and **Segments** to prepare provider audiences. Static segments contain selected subscribers; saved-filter segments are evaluated from their current rules. The public preference centre only accepts active segment handles belonging to that subscriber's site. **Export subscribers** produces a site-scoped CSV containing email, name, status, and subscription/unsubscription timestamps. Segment export uses the same fields. Treat these files as personal data and store or delete them under your organisation's retention policy. For imports, use **Marketing Studio > Import batches** and run **Dry-run import** first. The default limits are a 2 MB file and 10,000 rows. Every import requires a consent basis, rejects duplicate or invalid emails, and creates no subscribers when any row is invalid. A committed import marks valid rows subscribed, records the supplied consent basis, applies selected tags, and queues provider sync; if queueing fails, the batch is marked failed even though the transaction may already have created the local subscribers, so inspect the subscriber list before repeating it. ## Monitor provider synchronisation Provider changes create **Sync Attempts** and are processed once by a queue worker. A failed attempt is scheduled again after 5, 30, and 120 minutes by default; after the configured delays are consumed it becomes **Exhausted**. Globally suppressed subscribers fail permanently without a retry. The Sync Attempts screen is read-only. Fix credentials, connection state, audience mappings, webhook secrets, or subscriber data first. Due retry-scheduled attempts are picked up automatically by the five-minute scheduler; exhausted attempts are reported by Diagnostics and are not automatically reset by this package. Provider webhooks can update local subscription and suppression state. Configure the provider to call the connection-specific webhook URL with the stored secret. Invalid signatures fail closed, duplicate events are claimed before subscriber state changes, and a missing `newsletter_processed_webhook_events` table stops processing rather than risking duplicate consent records. ## Schedule send handoffs Use **Marketing Studio > Newsletter Sends** to record a site, name, subject, schedule, segment or provider audience, and optional UTM values. This is an external handoff, not a campaign editor or mail sender. The queue job suppresses a send when it has no eligible recipients; otherwise it emits an idempotent handoff payload for the configured consumer. A handoff job tries up to three times with one- and five-minute backoffs. The minute scheduler recovers an undispatched **Sending** record after the default 15-minute lease. When all job attempts fail, the record becomes **Failed** with a redacted error. A successful handoff only records that the downstream consumer accepted the request; that consumer must report later lifecycle changes such as sent or failed, and delivery analytics remain in the email provider. ## Access, privacy, and retention Newsletter resources use their generated Filament resource permissions. Global administrators bypass those permission checks; other administrators need the relevant view/create/update/delete ability and can only query or act on records for their assigned sites. Bulk import/export and segment export validate the submitted site or segment again, so a tampered site ID is rejected. Subscriber email, names, profile data, consent evidence, provider payload metadata, connection credentials, OAuth tokens, and webhook secrets are encrypted at rest. Newsletter also stores an email hash for exact matching. Consent evidence can include IP address, user agent, page URL, referrer, source identifiers, and UTM attribution, so restrict database access, exports, logs, backups, provider accounts, and webhook payload access accordingly. When Privacy Center is available, its Newsletter eraser anonymises a Subscriber: it replaces the email, clears identity/profile and consent evidence, suppresses the record, deletes public tokens, detaches segments, and removes stored remote identifiers. It does not delete the local row or remove the person from the external provider; complete any provider-side erasure separately. Newsletter does not schedule general retention cleanup. Subscriber, consent, import, sync, handoff, and processed-webhook records remain until your application deletes or anonymises them. Public preference tokens expire after 72 hours by default and offer a rate-limited fresh-link request after expiry. Unsubscribe links never expire, stay one-click capable, and are single-use.