Getting Started

Minimal Steps

Installation:
```
composer require spatie/laravel-newsletter
php artisan vendor:publish --tag="newsletter-config"
```
Configure .env with your provider-specific credentials (e.g., NEWSLETTER_API_KEY, NEWSLETTER_LIST_ID).
Choose a Driver:
- Mailcoach: Set NEWSLETTER_DRIVER=Spatie\Newsletter\Drivers\MailcoachDriver and install spatie/mailcoach-sdk-php.
- MailChimp: Set NEWSLETTER_DRIVER=Spatie\Newsletter\Drivers\MailChimpDriver and install drewm/mailchimp-api.
- MailerLite: Set NEWSLETTER_DRIVER=Spatie\Newsletter\Drivers\MailerLiteDriver and install mailerlite/mailerlite-php.

First Use Case: Subscribe a user to the default list:

use Spatie\Newsletter\Facades\Newsletter;

Newsletter::subscribe('user@example.com');

Implementation Patterns

Core Workflows

Subscription Management:
- Basic Subscription: Use subscribe() for one-time additions.
```
Newsletter::subscribe('user@example.com');
```
- Update or Subscribe: Use subscribeOrUpdate() to modify existing subscribers or add new ones.
```
Newsletter::subscribeOrUpdate('user@example.com', ['first_name' => 'John']);
```
- Unsubscribe: Remove a user from the list.
```
Newsletter::unsubscribe('user@example.com');
```
- Delete: Permanently remove a user (use sparingly; loses history).
```
Newsletter::delete('user@example.com');
```
List-Specific Operations: Specify a list name (configured in config/newsletter.php) to target a specific list:
```
Newsletter::subscribe('user@example.com', listName: 'customers');
```
Provider-Specific Attributes:
- Mailcoach: Pass custom attributes (e.g., ['first_name' => 'John']).
- MailChimp: Use merge variables (e.g., ['FNAME' => 'John']).
- MailerLite: Use subscriber fields (e.g., ['name' => 'John']).

Group/Interest Management (MailChimp): Subscribe users to specific groups/interests:

Newsletter::subscribeOrUpdate(
    'user@example.com',
    ['FNAME' => 'John'],
    'customers',
    ['interests' => ['group1_id' => true]]
);

Subscriber Lookup: Check subscription status or fetch details:

if (Newsletter::hasMember('user@example.com')) {
    $member = Newsletter::getMember('user@example.com');
}

Integration Tips

Form Handling: Attach newsletter subscription to user registration/login forms:

// In a registration controller
Newsletter::subscribeOrUpdate($request->email, [
    'first_name' => $request->first_name,
    'last_name' => $request->last_name
]);

Event-Driven Subscriptions: Trigger subscriptions via Laravel events (e.g., Registered):

event(new Registered($user));
// In event listener:
Newsletter::subscribeOrUpdate($user->email, $user->toArray());

API Access: Access the underlying API for advanced use cases:

$api = Newsletter::getApi();
$api->someCustomMethod(); // Provider-specific

Testing: Use the NullDriver for local development/testing (set NEWSLETTER_DRIVER=Spatie\Newsletter\Drivers\NullDriver in .env).

Gotchas and Tips

Pitfalls

Driver Configuration:
- Ensure endpoint is null for MailChimp/MailerLite; only Mailcoach requires an endpoint.
- Verify list.id matches the provider’s list/group ID (e.g., MailChimp’s list ID is not the same as its name).
Attribute Naming:
- MailChimp uses merge variables (e.g., FNAME, LNAME).
- Mailcoach/MailerLite use custom fields (e.g., first_name).
- Mismatched keys will fail silently or return unexpected results.
Unsubscribe vs. Delete:
- unsubscribe() marks users as inactive but retains history.
- delete() removes users permanently (use only for GDPR compliance or data cleanup).

Rate Limits:

MailChimp/MailerLite enforce API rate limits. Handle exceptions gracefully:

try {
    Newsletter::subscribe('user@example.com');
} catch (\Exception $e) {
    Log::error('Newsletter API error: ' . $e->getMessage());
}

List Name Ambiguity:
- If no listName is provided, the package uses config('newsletter.default_list_name').
- Omitting listName in multi-list setups may lead to unintended subscriptions.

Debugging

API Errors:

For MailChimp, inspect errors with:
```
Newsletter::getApi()->getLastError();
```

Log the raw API response for troubleshooting:

\Log::debug('MailChimp API Response:', ['response' => $api->getLastResponse()]);

NullDriver Quirks:
- The NullDriver supports method chaining but does not persist data. Useful for testing but not production.
Environment-Specific Issues:
- Test .env configurations locally before deploying (e.g., NEWSLETTER_DRIVER=log to log API calls without hitting endpoints).

Extension Points

Custom Drivers: Extend the package by creating a custom driver:

namespace App\Newsletter\Drivers;

use Spatie\Newsletter\Drivers\Driver;

class CustomDriver implements Driver {
    public function subscribe(string $email, array $attributes = []): void {
        // Custom logic
    }
    // Implement other required methods
}

'driver' => App\Newsletter\Drivers\CustomDriver::class,

Service Provider Hooks: Override the default facade binding in your service provider:

public function register() {
    $this->app->bind(
        \Spatie\Newsletter\Facades\Newsletter::class,
        function ($app) {
            return new \App\Newsletter\CustomFacade();
        }
    );
}

Event Listeners: Listen for newsletter events (e.g., Subscribed, Unsubscribed) to trigger side effects:

// In EventServiceProvider
protected $listen = [
    \Spatie\Newsletter\Events\Subscribed::class => [
       \App\Listeners\SendWelcomeEmail::class,
   ],
];

Testing Utilities: Create a test double for the newsletter service:

$this->mock(Newsletter::class)
    ->shouldReceive('subscribe')
    ->once()
    ->with('user@example.com');

Provider-Specific Tips

Mailcoach:
- Use UUIDs for list.id (found in Mailcoach’s list settings).
- Leverage Mailcoach’s SDK for advanced features (e.g., campaigns, templates).
MailChimp:
- Group IDs are required for segmenting subscribers. Fetch them via the API:
```
$groups = Newsletter::getApi()->getGroups();
```
- Use campaigns and automations endpoints for marketing flows.
MailerLite:
- Groups are identified by group.id (not list.id). Ensure your config matches.
- Use MailerLite’s webhooks for real-time subscriber updates.

Laravel Newsletter Laravel Package