Newsletter

Package docs status

This page is generated from package source documentation in the Capell packages repository and the checked-in manifest. Source documentation is not distribution status. Before running a Composer command, verify that the exact package and compatible 1.x release are available through public Packagist or the authenticated marketplace account.

Field	Value
Composer package	`capell-app/newsletter`
Package slug	`newsletter`
Product group	Capell Marketing & Growth
Tier	premium
Bundle	`marketing-growth`
Runtime contexts	`admin`, `frontend`
Capell version	`^1.0`
Catalogue role	extension
Release channel	Beta
Source repository	`capell-app/packages`
Source path	`packages/newsletter`
Docs source	`packages/newsletter/docs`
Manifest	`capell.json`

What This Plugin Adds

Newsletter is an Available, Schema-owning Capell package in the Capell Marketing & Growth product group. It ships as capell-app/newsletter and extends these surfaces: admin, frontend.

Newsletter adds subscriber consent, double opt-in, segments, preference routes, and provider handoff for Mailchimp, Kit, and Campaign Monitor.

Visitors can subscribe, confirm, update preferences, and unsubscribe. Expired confirmation and preference links offer a private, rate-limited email reissue, while unsubscribe links never expire and remain single-use.

Status details:

Status: Available
Tier: premium
Bundle: marketing-growth
Composer package: capell-app/newsletter
Namespace: Capell\Newsletter
Theme key: not applicable

Why It Matters

For developers: Provider and send-handoff contracts separate subscriber lifecycle rules from external email APIs and queued synchronization.

For teams: Teams keep consent and audience rules in Capell while using their email provider for campaign authoring, delivery, and provider-side reporting.

Screens And Workflow

Screenshot contract: docs/screenshots.json.

Illustrative subscribers admin index preview

Illustrative subscribers admin index preview (frontend, required evidence).
Create/edit subscriber form (admin, required evidence).
Provider connections admin index and form (admin, required evidence).
Provider audiences admin index and form (admin, required evidence).
Provider interest mappings admin index and form (admin, required evidence).
Form mappings admin index and form (admin, required evidence).
Newsletter tags admin index and form (admin, required evidence).
Segments admin index and form (admin, required evidence).
Import batches admin index (admin, required evidence).
Sync attempts admin index (admin, required evidence).
Newsletter overview stats (admin, required evidence).
Subscription confirmation route response (frontend, required evidence).
Unsubscribe route response (frontend, required evidence).
Provider connections admin index and form with admin sidebar menu open (admin, supplementary evidence).

Technical Shape

Service providers

Capell\Newsletter\Providers\NewsletterServiceProvider
Capell\Newsletter\Providers\AdminServiceProvider

Config files

packages/newsletter/config/capell-newsletter.php

Migrations

packages/newsletter/database/migrations/2026_05_10_190861_01_create_newsletter_provider_connections_table.php
packages/newsletter/database/migrations/2026_05_10_190861_02_create_newsletter_subscribers_table.php
packages/newsletter/database/migrations/2026_05_10_190861_03_create_newsletter_provider_audiences_table.php
packages/newsletter/database/migrations/2026_05_10_190861_04_create_newsletter_consent_events_table.php
packages/newsletter/database/migrations/2026_05_10_190861_05_create_newsletter_provider_interest_mappings_table.php
packages/newsletter/database/migrations/2026_05_10_190861_06_create_newsletter_provider_subscribers_table.php
packages/newsletter/database/migrations/2026_05_10_190861_07_create_newsletter_public_tokens_table.php
packages/newsletter/database/migrations/2026_05_10_190861_08_create_newsletter_segments_table.php
packages/newsletter/database/migrations/2026_05_10_190861_09_create_newsletter_sync_attempts_table.php
packages/newsletter/database/migrations/2026_05_10_190861_10_create_newsletter_form_mappings_table.php
packages/newsletter/database/migrations/2026_05_10_190861_11_create_newsletter_import_batches_table.php
packages/newsletter/database/migrations/2026_05_10_190861_12_create_newsletter_processed_webhook_events_table.php
packages/newsletter/database/migrations/2026_05_31_120000_13_create_newsletter_sends_table.php
packages/newsletter/database/migrations/2026_07_10_120000_14_add_handoff_state_to_newsletter_sends_table.php
packages/newsletter/database/migrations/2026_07_22_120000_15_create_newsletter_import_row_receipts_table.php
packages/newsletter/database/migrations/2026_09_23_000001_add_provider_request_marker_to_sync_attempts.php
packages/newsletter/database/migrations/2026_09_25_000001_add_source_files_deleted_at_to_newsletter_import_batches.php
packages/newsletter/database/migrations/2026_09_29_120000_remove_implicit_timestamp_updates_from_newsletter.php
packages/newsletter/database/migrations/2026_09_30_000001_add_subscriber_type_used_index_to_newsletter_public_tokens.php

Settings migrations

packages/newsletter/database/settings/2026_07_11_000001_create_newsletter_settings.php

Settings classes

NewsletterSettings

Models

ConsentEvent
FormMapping
ImportBatch
ImportRowReceipt
NewsletterSend
ProviderAudience
ProviderConnection
ProviderInterestMapping
ProviderSubscriber
PublicToken
Segment
Subscriber
SyncAttempt

Filament classes

ScopesNewsletterResourcesToAssignedSites
FormMappingResource
CreateFormMapping
EditFormMapping
ListFormMappings
ImportBatchResource
ListImportBatches
NewsletterSendResource
CreateNewsletterSend
EditNewsletterSend
ListNewsletterSends
NewsletterTagResource
CreateNewsletterTag
EditNewsletterTag
ListNewsletterTags
CreateProviderAudience
EditProviderAudience
ListProviderAudiences
ProviderAudienceResource
CreateProviderConnection
EditProviderConnection
ListProviderConnections
ProviderConnectionResource
CreateProviderInterestMapping
EditProviderInterestMapping
ListProviderInterestMappings
ProviderInterestMappingResource
CreateSegment
EditSegment
ListSegments
SegmentResource
CreateSubscriber
EditSubscriber
ListSubscribers
SubscriberResource
ListSyncAttempts
SyncAttemptResource
NewsletterSettingsSchema
NewsletterOverviewStatsFilamentWidget

Route files

packages/newsletter/routes/web.php

Policies

AbstractNewsletterResourcePolicy
FormMappingPolicy
ImportBatchPolicy
NewsletterSendPolicy
ProviderAudiencePolicy
ProviderConnectionPolicy
ProviderInterestMappingPolicy
SegmentPolicy
SubscriberPolicy
SyncAttemptPolicy

Extension contracts

NewsletterAudienceProvider
NewsletterProviderAdapter
NewsletterSegmentProvider
NewsletterSendHandoff
ReconcilesNewsletterProviderSync

Events

NewsletterSendHandoffRequested
SubscriberConfirmed
SubscriberUnsubscribed

Listeners

SubscribeFromFormSubmission

Actions

AnonymizeNewsletterSubscriberAction
ApplyNewsletterTagsAction
AssertNewsletterSendHandoffAvailableAction
BuildDueNewsletterSendsAction
BuildListUnsubscribeHeadersAction
BuildNewsletterHealthDiagnosticsAction
BuildNewsletterSendHandoffPayloadAction
ConfirmSubscriberAction
CreatePreferenceCenterTokenAction
CreateUnsubscribeTokenAction
DeleteSubscriberImportFilesAction
EvaluateNewsletterSegmentAction
ExportSubscribersAction
FailSubscriberImportAction
FailSubscriberImportChunkAction
HandleProviderWebhookAction
ImportSubscribersAction
InvalidateSubscriberConfirmationTokensAction
ParseSubscriberCsvRowsAction
PrepareNewsletterScreenshotTokenAction
PrepareSubscriberCsvImportAction
ProcessSubscriberImportChunkAction
QueueDueNewsletterSendsAction
QueueProviderSyncAction
QueueSubscriberCsvImportAction
RecordConsentEventAction
RecoverStalledSubscriberImportsAction
RedactNewsletterProviderErrorMessageAction
ReissueConfirmationTokenAction
ReissuePreferenceCenterTokenAction
RenderPublicNewsletterPageAction
RequestDoubleOptInAction
RequeueDueProviderSyncAttemptsAction
ResolveNewsletterSendRecipientEligibilityAction
ResolvePreferenceCenterAction
ResolveUtmAttributionAction
ScheduleNewsletterSendAction
SeedNewsletterScreenshotFixtureAction
SubscribeFromFormSubmissionAction
SubscribeFromPublicRequestAction
SyncNewsletterSubscriberContactAction
SyncSubscriberToProviderAction
TransitionSubscriberImportBatchAction
UnsubscribeSubscriberAction
UpdateNewsletterSendStatusAction
UpdatePreferenceCenterAction
UpsertSubscriberAction
ValidateSubscriberImportRowsAction

Data objects

ConfirmSubscriberResultData
ConsentEvidenceData
FormMappingData
PreferenceCenterData
PreferenceCenterResolutionData
PreferenceCenterSegmentData
PreferenceCenterUpdateData
ProviderAudienceData
ProviderInterestData
ProviderSubscriberData
ProviderSyncResultData
ProviderWebhookEventData
PublicNewsletterPageData
SubscriberData
SubscriberImportSourceData
UtmAttributionData

Jobs

HandoffNewsletterSendJob
PrepareSubscriberCsvImportJob
ProcessSubscriberImportChunkJob
SyncSubscriberToProviderJob

Command signatures

newsletter:handoff-due-sends
newsletter:recover-stalled-imports
newsletter:sync-retry-due

Manifest action API

applyNewsletterTags: Capell\Newsletter\Actions\ApplyNewsletterTagsAction
buildDueNewsletterSends: Capell\Newsletter\Actions\BuildDueNewsletterSendsAction
buildListUnsubscribeHeaders: Capell\Newsletter\Actions\BuildListUnsubscribeHeadersAction
buildNewsletterSendHandoffPayload: Capell\Newsletter\Actions\BuildNewsletterSendHandoffPayloadAction
confirmSubscriber: Capell\Newsletter\Actions\ConfirmSubscriberAction
createPreferenceCenterToken: Capell\Newsletter\Actions\CreatePreferenceCenterTokenAction
createUnsubscribeToken: Capell\Newsletter\Actions\CreateUnsubscribeTokenAction
evaluateNewsletterSegment: Capell\Newsletter\Actions\EvaluateNewsletterSegmentAction
exportSubscribers: Capell\Newsletter\Actions\ExportSubscribersAction
handleProviderWebhook: Capell\Newsletter\Actions\HandleProviderWebhookAction
importSubscribers: Capell\Newsletter\Actions\ImportSubscribersAction
parseSubscriberCsvRows: Capell\Newsletter\Actions\ParseSubscriberCsvRowsAction
queueDueNewsletterSends: Capell\Newsletter\Actions\QueueDueNewsletterSendsAction
queueProviderSync: Capell\Newsletter\Actions\QueueProviderSyncAction
recordConsentEvent: Capell\Newsletter\Actions\RecordConsentEventAction
recoverStalledSubscriberImports: Capell\Newsletter\Actions\RecoverStalledSubscriberImportsAction
requestDoubleOptIn: Capell\Newsletter\Actions\RequestDoubleOptInAction
requeueDueProviderSyncAttempts: Capell\Newsletter\Actions\RequeueDueProviderSyncAttemptsAction
resolvePreferenceCenter: Capell\Newsletter\Actions\ResolvePreferenceCenterAction
resolveUtmAttribution: Capell\Newsletter\Actions\ResolveUtmAttributionAction
scheduleNewsletterSend: Capell\Newsletter\Actions\ScheduleNewsletterSendAction
subscribeFromFormSubmission: Capell\Newsletter\Actions\SubscribeFromFormSubmissionAction
subscribeFromPublicRequest: Capell\Newsletter\Actions\SubscribeFromPublicRequestAction
syncNewsletterSubscriberContact: Capell\Newsletter\Actions\SyncNewsletterSubscriberContactAction
syncSubscriberToProvider: Capell\Newsletter\Actions\SyncSubscriberToProviderAction
unsubscribeSubscriber: Capell\Newsletter\Actions\UnsubscribeSubscriberAction
updateNewsletterSendStatus: Capell\Newsletter\Actions\UpdateNewsletterSendStatusAction
updatePreferenceCenter: Capell\Newsletter\Actions\UpdatePreferenceCenterAction
upsertSubscriber: Capell\Newsletter\Actions\UpsertSubscriberAction

Scheduled commands

newsletter:handoff-due-sends (everyMinute; package registered)
newsletter:recover-stalled-imports (everyMinute; package registered)
newsletter:sync-retry-due (everyFiveMinutes; package registered)

Console command classes

HandoffDueNewsletterSendsCommand
RecoverStalledSubscriberImportsCommand
RequeueDueProviderSyncAttemptsCommand
SeedNewsletterScreenshotFixtureCommand

Manifest contributions

admin-resource: Capell\Newsletter\Manifest\NewsletterAdminResourcesContribution
console-command: Capell\Newsletter\Manifest\NewsletterConsoleCommandsContribution
dashboard-widget: Capell\Newsletter\Manifest\NewsletterOverviewFilamentWidgetContribution
health-check: Capell\Newsletter\Manifest\NewsletterHealthContribution
migration: Capell\Newsletter\Manifest\NewsletterMigrationsContribution
model: Capell\Newsletter\Manifest\NewsletterModelsContribution
overview-stat: Capell\Newsletter\Manifest\NewsletterOverviewStatsContribution
route: Capell\Newsletter\Manifest\NewsletterFrontendRoutesContribution
scheduled-job: Capell\Newsletter\Manifest\NewsletterImportRecoveryScheduleContribution
scheduled-job: Capell\Newsletter\Manifest\NewsletterSendHandoffScheduleContribution
scheduled-job: Capell\Newsletter\Manifest\NewsletterSyncRetryScheduleContribution
setting: Capell\Newsletter\Manifest\NewsletterSettingsContribution

Health checks

Capell\Newsletter\Health\NewsletterHealthCheck

Blade views

packages/newsletter/resources/views/layouts/fallback.blade.php
packages/newsletter/resources/views/preference-center.blade.php
packages/newsletter/resources/views/public-page.blade.php

Cache tags

newsletter

Data Model

Required tables: newsletter_provider_connections, newsletter_subscribers, newsletter_provider_audiences, newsletter_consent_events, newsletter_provider_interest_mappings, newsletter_provider_subscribers, newsletter_public_tokens, newsletter_segment_subscriber, newsletter_segments, newsletter_sync_attempts, newsletter_form_mappings, newsletter_import_batches, newsletter_import_row_receipts, newsletter_processed_webhook_events, newsletter_sends.
Models: ConsentEvent, FormMapping, ImportBatch, ImportRowReceipt, NewsletterSend, ProviderAudience, ProviderConnection, ProviderInterestMapping, ProviderSubscriber, PublicToken, Segment, Subscriber, SyncAttempt.
Core record references in migrations: sites via site_id.
Migration files: 2026_05_10_190861_01_create_newsletter_provider_connections_table.php, 2026_05_10_190861_02_create_newsletter_subscribers_table.php, 2026_05_10_190861_03_create_newsletter_provider_audiences_table.php, 2026_05_10_190861_04_create_newsletter_consent_events_table.php, 2026_05_10_190861_05_create_newsletter_provider_interest_mappings_table.php, 2026_05_10_190861_06_create_newsletter_provider_subscribers_table.php, 2026_05_10_190861_07_create_newsletter_public_tokens_table.php, 2026_05_10_190861_08_create_newsletter_segments_table.php, 2026_05_10_190861_09_create_newsletter_sync_attempts_table.php, 2026_05_10_190861_10_create_newsletter_form_mappings_table.php, 2026_05_10_190861_11_create_newsletter_import_batches_table.php, 2026_05_10_190861_12_create_newsletter_processed_webhook_events_table.php, 2026_05_31_120000_13_create_newsletter_sends_table.php, 2026_07_10_120000_14_add_handoff_state_to_newsletter_sends_table.php, 2026_07_22_120000_15_create_newsletter_import_row_receipts_table.php, 2026_09_23_000001_add_provider_request_marker_to_sync_attempts.php, 2026_09_25_000001_add_source_files_deleted_at_to_newsletter_import_batches.php, 2026_09_29_120000_remove_implicit_timestamp_updates_from_newsletter.php, 2026_09_30_000001_add_subscriber_type_used_index_to_newsletter_public_tokens.php.
Migration impact: run host migrations through the package install flow before opening package surfaces.
Deletion/retention behaviour: migrations declare cascade-on-delete relationships and null-on-delete relationships; no timed pruning or retention schedule is declared in capell.json.

Install Impact

Required packages: capell-app/admin, capell-app/core, capell-app/form-builder, capell-app/frontend, capell-app/tags.
Admin navigation: declares admin-resource: NewsletterAdminResourcesContribution; each Filament page or resource controls its own navigation visibility.
Admin/editor extensions: dashboard-widget: NewsletterOverviewFilamentWidgetContribution, overview-stat: NewsletterOverviewStatsContribution.
Permissions: access also governed by package policies: AbstractNewsletterResourcePolicy, FormMappingPolicy, ImportBatchPolicy, NewsletterSendPolicy, ProviderAudiencePolicy, ProviderConnectionPolicy, ProviderInterestMappingPolicy, SegmentPolicy, SubscriberPolicy, SyncAttemptPolicy.
Public routes: loads routes/web.php; registers NewsletterFrontendRoutesContribution.
Database changes: package migrations are declared.
Config: config/capell-newsletter.php.
Settings: Capell\Newsletter\Settings\NewsletterSettings.
Queues or schedules: scheduled commands newsletter:handoff-due-sends (everyMinute; package registered), newsletter:recover-stalled-imports (everyMinute; package registered), newsletter:sync-retry-due (everyFiveMinutes; package registered); queue jobs HandoffNewsletterSendJob, PrepareSubscriberCsvImportJob, ProcessSubscriberImportChunkJob, SyncSubscriberToProviderJob.
Cache tags: newsletter.
Commands: newsletter:handoff-due-sends, newsletter:recover-stalled-imports, newsletter:sync-retry-due.

Common Pitfalls

Keep required Capell packages on compatible v4 releases: capell-app/admin, capell-app/core, capell-app/form-builder, capell-app/frontend, capell-app/tags.
Run migrations before opening package resources or public routes.
Review package configuration before production-like verification: config/capell-newsletter.php, Capell\Newsletter\Settings\NewsletterSettings.
Review middleware, throttling, signatures, and public-output safety in routes/web.php before exposing routes.
Keep the host Laravel scheduler running so package-registered schedules can execute: newsletter:handoff-due-sends (everyMinute; package registered), newsletter:recover-stalled-imports (everyMinute; package registered), newsletter:sync-retry-due (everyFiveMinutes; package registered).
Keep public Blade and cached HTML free of authoring markers, model IDs, permissions, signed editor URLs, and lazy database queries.
Custom write integrations must preserve invalidation for newsletter cache tags.

Troubleshooting

Symptom	Likely cause	Check	Fix
Package surface is missing after install	Provider or manifest is not loaded	Confirm `capell.json`, package `composer.json`, and provider registration	Reinstall the package, refresh Composer autoload, and clear host caches
Admin screen or command fails on missing table	Package migrations have not run	Check the tables listed in `Data Model`	Run host migrations and rerun the focused package test
Route returns unexpected output	Route cache, middleware, or signed URL setup does not match the package route file	Check the route files listed in `Technical Shape`	Clear route cache and verify middleware before exposing public routes
Background work does not run	Queue worker or declared schedule is not active	Check the jobs and scheduled commands listed in `Technical Shape`	Start the queue worker or host scheduler, then run the focused command or package test
Public output leaks unexpected state	Render data, cache variation, or authoring boundary has regressed	Check public Blade, cache tags, and public-output safety tests	Move data loading out of Blade and rerun the package public-output tests

Quick Start

Install the package: composer require capell-app/newsletter.
Open the package admin surface at /admin/newsletter/subscribers/{first-record}/edit and confirm Newsletter is available.

Next Steps

Package docs
Overview
Worked extension examples
Admin guide
Configuration files: config/capell-newsletter.php.
Troubleshooting
Screenshot contract
Marketplace assets
Capell content language plan
Capell documentation design system
Capell and package ERD notes
Related packages: Form Builder, Tags, Contacts, Customer Portal.