Newsletter
Package docs status
Section titled “Package docs status”This page is generated from public package documentation in capell-4/packages and the package manifest checked into the source repository.
| Field | Value |
|---|---|
| Composer package | capell-app/newsletter |
| Package slug | newsletter |
| Product group | Capell Marketing |
| Tier | premium |
| Bundle | newsletter |
| Runtime contexts | admin, frontend |
| Capell version | ^4.0 |
| Source repository | capell-app/packages |
| Source path | packages/newsletter |
| Docs source | packages/newsletter/docs |
| Manifest | capell.json |
Newsletter manages audiences, subscriptions, consent state, imports, notifications, and public subscription routes.
At A Glance
Section titled “At A Glance”- Package:
capell-app/newsletter - Namespace:
Capell\Newsletter\ - Surfaces: Filament admin, console, HTTP, queue, database
- Service providers:
packages/newsletter/src/Providers/AdminServiceProvider.php,packages/newsletter/src/Providers/NewsletterServiceProvider.php - Capell dependencies:
capell-app/admin,capell-app/core,capell-app/form-builder,capell-app/frontend,capell-app/tags
Why It Helps Your Capell Workflow
Section titled “Why It Helps Your Capell Workflow”- Adds subscriber capture, consent state, imports, notifications, and public subscription routes for Capell sites.
- Helps owners build audience workflows without putting newsletter-specific logic into Form Builder or Campaign Studio.
- Gives developers provider sync and subscription Actions that can connect to email, public actions, and growth workflows.
Best Used With
Section titled “Best Used With”What It Adds
Section titled “What It Adds”- Newsletter manages audiences, subscriptions, consent state, imports, notifications, and public subscription routes.
- Admin resources:
FormMappingResource,ImportBatchResource,NewsletterTagResource,ProviderAudienceResource,ProviderConnectionResource,ProviderInterestMappingResource,SegmentResource,SubscriberResource,SyncAttemptResource. - Package setup or maintenance commands.
Technical Shape
Section titled “Technical Shape”- NewsletterServiceProvider registers public routes, admin resources, jobs, listeners, migrations, settings, and translations.
- Subscription, import, consent, and notification behaviour lives in actions and jobs.
- Public endpoints route through controllers and should treat all payloads as untrusted input.
Code Map
Section titled “Code Map”| Area | Path | Purpose |
|---|---|---|
| Actions | packages/newsletter/src/Actions | Domain operations. Test these directly where possible. |
| Data | packages/newsletter/src/Data | Structured payloads, form state, view models, and integration data. |
| Enums | packages/newsletter/src/Enums | Persisted states and Filament option values. |
| Models | packages/newsletter/src/Models | Eloquent records owned by the package. |
| Filament | packages/newsletter/src/Filament | Admin resources, pages, widgets, and settings UI. |
| HTTP | packages/newsletter/src/Http | Controllers, middleware, and request handling. |
| Jobs | packages/newsletter/src/Jobs | Queued work and async side effects. |
| Providers | packages/newsletter/src/Providers | Registration, extension hooks, routes, migrations, and resources. |
| Resources | packages/newsletter/resources | Views, translations, assets, and package resources. |
| Routes | packages/newsletter/routes | Route files loaded by the service provider. |
| Config | packages/newsletter/config | Package configuration and publishable config. |
| Database | packages/newsletter/database | Migrations, seeders, and settings migrations. |
| Tests | packages/newsletter/tests | Package-level Pest coverage. |
Admin Surface
Section titled “Admin Surface”- Resources:
FormMappingResource,ImportBatchResource,NewsletterTagResource,ProviderAudienceResource,ProviderConnectionResource,ProviderInterestMappingResource,SegmentResource,SubscriberResource,SyncAttemptResource. - Pages:
CreateFormMapping,CreateNewsletterTag,CreateProviderAudience,CreateProviderConnection,CreateProviderInterestMapping,CreateSegment,CreateSubscriber,EditFormMapping,EditNewsletterTag,EditProviderAudience,EditProviderConnection,EditProviderInterestMapping,EditSegment,EditSubscriber, and related pages. - Widgets:
NewsletterOverviewStatsWidget. - Settings:
NewsletterSettings.
Runtime Surface
Section titled “Runtime Surface”- Controllers:
ConfirmSubscriptionController,ProviderWebhookController,UnsubscribeController. - Routes:
packages/newsletter/routes/web.php. - Jobs:
SyncSubscriberToProviderJob.
Commands
Section titled “Commands”newsletter:sync-retry-due {--limit= : Maximum number of due attempts to requeue}(packages/newsletter/src/Console/Commands/RequeueDueProviderSyncAttemptsCommand.php)
Data And Persistence
Section titled “Data And Persistence”- Models:
ConsentEvent,FormMapping,ImportBatch,ProviderAudience,ProviderConnection,ProviderInterestMapping,ProviderSubscriber,PublicToken,Segment,Subscriber,SyncAttempt. - Migrations:
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. - Config:
packages/newsletter/config/capell-newsletter.php. - Data objects live in
src/Data/; use them for payloads, form state, and view models.
Extension Points
Section titled “Extension Points”- Contracts:
NewsletterAudienceProvider,NewsletterProviderAdapter,NewsletterSegmentProvider. - Listeners:
SubscribeFromFormSubmission. - Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.
Install Impact
Section titled “Install Impact”- Adds audience, subscriber, subscription, consent, import, segment, and notification tables.
- Adds newsletter admin resources and settings.
- Adds public subscription endpoints and async newsletter processing jobs.
Install And Setup
Section titled “Install And Setup”- Install with
composer require capell-app/newsletterin the host Capell application. - Run migrations through the host application package install flow.
- In this repository, verify package changes with
vendor/bin/pest; do not usephp artisan.
Testing
Section titled “Testing”Run package tests from the repository root:
vendor/bin/pest packages/newsletter/tests --configuration=phpunit.xmlMaintenance Notes
Section titled “Maintenance Notes”- Treat public routes as untrusted input and keep validation, permission checks, and side effects inside actions or dedicated services.
- Put behaviour changes in
src/Actions/; UI classes, commands, and controllers should call actions instead of owning domain logic. - Use package
Dataclasses at boundaries instead of passing anonymous arrays between layers. - Use backed enums for persisted values and enum labels for Filament options.