Filament Cloudflare Mail Sender Laravel Package

Getting Started

• Install with composer require draliragab/filament-cloudflare-mail-sender:^1.0. The ^1.0 constraint means v1.0.1 lands automatically as a patch — no composer.json edit needed to pick up the docs improvements.
• Look here first: the README quick start (rewritten in v1.0.1 as a numbered walkthrough) and the package's published config file. v1.0.1 also added config tables, so you can map every option to its env var in one place rather than reading the config source.
• Typical setup order: publish the config → add the credentials to .env (and .env.example) → confirm the mailer is wired into config/mail.php → send one test message.
• First use case: send a single transactional email from a Filament context — a password reset or a test notification — before touching anything else. If that one message arrives, credentials, sender domain, and transport wiring are all proven at once. Don't start by rewiring the whole app's default mailer; switch the default only after the isolated test succeeds.
• v1.0.1 is documentation-only: no code, config, or API changes. The only action item is reading the new quick start and config tables in place of whatever you inferred from v1.0.0.

Implementation Patterns

• Keep the driver behind env, not code. Set the mailer in .env (MAIL_MAILER or the package's own driver key) so staging can fall back to log or SMTP while production uses Cloudflare. Hardcoding the mailer in config/mail.php is the fastest way to break local development.
• Isolate the mailer definition. Add the package's transport as a named mailer rather than overwriting smtp. That lets you send selectively — Mail::mailer('cloudflare')->to(...) for real recipients while everything else stays on the default driver during rollout.
• Filament notifications and auth mail are the main consumers. Filament's password reset, email verification, and notification emails all route through Laravel's mailer, so once the driver is configured they work without per-feature changes. Verify the password reset flow explicitly — it's the one users hit on day one.
• Queue anything user-triggered. The Cloudflare call is an outbound HTTP request inside the mail send. Wrap notifications and mailables in ShouldQueue so a slow or failing upstream doesn't block the Filament request cycle.
• Test with Mail::fake() in feature tests. Assertions on Mail::assertSent() keep the suite free of network calls; reserve one real send per environment for smoke testing after deploy.
• Pin the constraint, not the patch. ^1.0 is correct here; there's no reason to pin 1.0.1 exactly, since the patch introduced no behavioral change.

Gotchas and Tips

• Your sending domain must be onboarded and verified in Cloudflare first. Configuration that looks correct will still fail at send time if the domain isn't active there or the From address doesn't belong to a verified domain. This is the single most common cause of "the package doesn't work."
• Token scope matters more than token validity. A token that authenticates but lacks permission for the mail endpoint produces an authorization error that reads like a config error. Create a scoped token for exactly this purpose and store it in .env, never in a committed config file.
• Run php artisan config:clear after editing .env. On cached-config environments (staging, production) the new values silently won't apply, and you'll debug a problem that doesn't exist.
• Read errors from the transport, not the app. Failures surface from Laravel's mail layer, not from Filament. Check storage/logs/laravel.log for the underlying response body before assuming the Filament integration is at fault.
• Local development should never hit Cloudflare. Send to log or Mailpit locally; use a real send only in one staging smoke test. Otherwise you'll burn through quota and clutter deliverability stats on test traffic.
• Verify env var names against the new config tables rather than guessing. The v1.0.1 tables are the authoritative mapping; the naming is not always what you'd assume from the package name.
• Extension points: the mail transport is registered through Laravel's mail manager, so if you need custom headers, a different From per notification, or a wrapper that logs payloads, a custom Mailable or a small transport decorator is the clean seam — no need to fork the package.