# Overview.Admin ## What it does Email Studio manages Capell's transactional email. Packages register the templates they can send; administrators can create site- and locale-specific overrides, brand them with reusable themes, send tests, and review MailTracker delivery activity. ## Setup requirements Run the package and settings migrations. Configure the host application's Laravel mailers, keep a queue worker running for the queue named by `CAPELL_EMAIL_STUDIO_QUEUE` (the default queue unless changed), and keep Laravel's scheduler running. Email Studio schedules body pruning and MailTracker-row purging daily with overlap and single-server protection. Provision at least one default `EmailProfile` before sending. Email Studio has no admin resource for creating profiles: an installer, seeder, or integration must store the site scope, sender/reply-to identity, provider, tracking choices, and encrypted provider settings. The built-in SMTP adapter sends through a configured Laravel mailer. The Postmark adapter also sends through Laravel's mailer abstraction, defaulting to the `postmark` mailer; it is not a separate native Postmark API client. Never use the Fake profile in production. For a site-scoped send, profile resolution prefers that scope and then `global`. It then chooses a default profile, preferring the configured `default_provider` (`smtp` by default). The database does not enforce one default per scope, so maintain exactly one intended default rather than relying on row order. ## Author templates safely Go to **Email Studio** in the admin: - **Email templates** is the package-registered catalogue. Definitions cannot be created or edited there. Use **Customize** to create a Draft database override for that registration's site scope. - **Template variants** contains the editable subject, preview text, HTML/text body, optional CC/BCC recipients, delivery profile, locale, and theme. - **Template themes** contains reusable branding. A default theme is selected per site-scope key. - **Sent emails** is the read-only MailTracker log, not a queue retry screen or a complete view of Email Studio message records. Preview and save a Draft before activation. **Activate** retires the previous Active variant for the same template, site-scope key, and locale, records approval, and makes the template Approved. If no Active override resolves, a renderable registered definition remains the fallback. **Send test** delivers immediately using the registered sample variables. It does not use the normal queued job, but still requires a resolvable profile and honours global and site-scoped suppressions. Check every locale and any fixed CC/BCC recipients before activation; those addresses receive normal sends that use the variant. ## Delivery, suppression, and recovery Normal sending records the rendered subject, HTML/text body, context, recipients, attachments, profile, and selected variant before dispatching `SendEmailJob`. The worker re-checks suppressions before provider handoff. A provider can return per-recipient failures, producing Failed or Partially failed records. The queued job has four attempts with 60, 300, and 900 second back-offs and a two-hour retry window. However, a thrown provider result is recorded as **Uncertain**, and stale interrupted Sending records also become Uncertain rather than being sent again blindly. Use provider evidence to reconcile uncertain recipients before arranging any deliberate resend. Email Studio has no admin retry action for these message rows; use application queue/log tooling and an integration around the reconciliation action. Bounce and complaint provider events create active suppressions automatically. Global suppressions block every site; site-scoped suppressions block only that site scope. There is currently no suppression management or self-service unsubscribe screen, so manual suppression and release require an integration using the package actions. Do not describe the package as providing marketing-email unsubscribe compliance on its own. ## Provider webhooks and tracking Provider events post to `/mail/provider-events/{token}` by default and are rate-limited. An integration must provision a raw endpoint token while storing only its SHA-256 hash on the profile. Non-Postmark profiles require an HMAC-SHA256 signature in `X-Capell-Email-Studio-Signature`; Postmark profiles require configured Basic-auth username/password credentials. Provider settings are encrypted at rest. Events are stored idempotently per profile and can update recipient state or create a suppression. Correlation uses the provider message ID first. If it is absent or unknown, the action falls back to the latest recipient under that profile with the same email hash. Configure providers to return the message ID and include it in events; without it, repeated sends to one address can be matched to the wrong record. Inbound-reply normalisation and storage types exist, but this package does not expose an inbound-reply ingestion route. Open and click counts are signals, not proof that a recipient read a message. They depend on tracking being enabled and on the mail client loading the pixel or following a rewritten link. Review the privacy basis for tracking before enabling it. ## Permissions and data visibility The resources use their generated `ViewAny`, `View`, `Create`, and `Update` permissions listed in the package manifest; global administrators bypass them. Record policies reject site-owned template records outside a non-global administrator's assigned sites, but the resource base queries are not site-scoped. Global records are available to every permitted role. The MailTracker `sent_emails` rows do not carry a Capell site ID, so **Sent emails** is installation-wide and can expose recipient, sender, subject, content, and tracked links across sites. Grant these permissions only to roles allowed to inspect all listed data; do not treat the resources as a hard tenant boundary. Delivery profiles, Email Studio message/recipient/event/reply/suppression data, rendered bodies, context, failures, and provider payloads use encrypted casts for their sensitive fields. Template variant subject/body and CC/BCC values, theme metadata, attachment references, provider message IDs, lookup hashes, tracking tokens' destination URLs, and MailTracker's sent-email rows are not encrypted by this package. Protect database, storage, queue payloads, logs, backups, and admin access accordingly, and keep the application encryption key available for old records during key rotation. ## Retention and authentication email settings Two daily jobs have different effects: - MailTracker rows and their click rows are deleted after the setting's retention period (60 days by default). Setting that period below one disables this purge. - Email Studio's rendered HTML/text bodies are cleared after `capell-email-studio.body_retention_days` (90 days by default). This deployment config is separate from the settings screen and is clamped to at least one day. The message row, subject, context snapshot, headers, attachment references, recipients, provider events, and delivery metadata remain. No scheduled job deletes Email Studio message, recipient, event, reply, profile, suppression, template, variant, theme, or tracking-token rows, and the package does not contribute a Privacy Center exporter or eraser. Include these records, MailTracker data, provider data, queue payloads, stored attachments, logs, and backups in the installation's subject-access and erasure process. The settings surface enables Email Studio replacements for verification and password-reset mail by default. Welcome, verified, login, lockout, and password-reset-success lifecycle messages are opt-in. Enable them only after testing the active templates and delivery profile, because they add mail to authentication events rather than merely changing presentation.