Transactional Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install the Package

   composer require mailchimp/transactional
   

   Add to composer.json if not using Composer globally:

   "require": {
       "mailchimp/transactional": "^1.0"
   }
   

2. Configure API Key Store your Mailchimp API key in Laravel’s .env:

   MAILCHIMP_TRANSACTIONAL_API_KEY=your_api_key_here
   MAILCHIMP_TRANSACTIONAL_REGION=us12  # e.g., us12, eu1, etc.
   

3. Create a Service Class In app/Services/MailchimpService.php:

   <?php
   namespace App\Services;
   
   use MailchimpTransactional\ApiClient;
   
   class MailchimpService
   {
       protected $client;
   
       public function __construct()
       {
           $this->client = new ApiClient();
           $this->client->setApiKey(config('services.mailchimp.api_key'));
           $this->client->setServer(config('services.mailchimp.region'));
       }
   
       // Add methods here (see Implementation Patterns)
   }
   

4. Register in config/services.php

   'mailchimp' => [
       'api_key' => env('MAILCHIMP_TRANSACTIONAL_API_KEY'),
       'region'  => env('MAILCHIMP_TRANSACTIONAL_REGION', 'us12'),
   ],
   

5. First Use Case: Send an Email Bind the service in AppServiceProvider and send a test email:

   $mailchimp = app(MailchimpService::class);
   $response = $mailchimp->sendEmail([
       'message' => [
           'to' => [['email' => 'user@example.com']],
           'from' => 'sender@example.com',
           'subject' => 'Test Email',
           'html' => '<p>Hello, world!</p>',
       ],
   ]);
   

Implementation Patterns

1. Email Sending Workflows

Basic Email

$response = $mailchimp->messages->send([
    'message' => [
        'to' => [['email' => 'user@example.com']],
        'from' => 'sender@example.com',
        'subject' => 'Welcome!',
        'html' => '<p>Your content here.</p>',
    ],
]);

Async Sending (Queue Job)

Create a job (app/Jobs/SendMailchimpEmail.php):

use App\Services\MailchimpService;

class SendMailchimpEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable;

    public function handle(MailchimpService $mailchimp)
    {
        $mailchimp->sendEmail($this->payload);
    }
}

Dispatch in a controller:

SendMailchimpEmail::dispatch($emailData)->onQueue('mailchimp');

Templates

Publish a template:

$mailchimp->templates->publish([
    'name' => 'Welcome Template',
    'content' => [
        'type' => 'html',
        'value' => '<p>Welcome!</p>',
    ],
]);

Send using a template:

$mailchimp->messages->send([
    'message' => [
        'to' => [['email' => 'user@example.com']],
        'template_id' => 'template_123',
        'merge_vars' => [
            ['name' => 'FIRST_NAME', 'content' => 'John'],
        ],
    ],
]);

2. Event-Driven Integrations

Webhooks for Campaign Events

Configure a route in routes/web.php:

Route::post('/mailchimp/webhook', [MailchimpWebhookController::class, 'handle']);

Handle inbound webhooks (app/Http/Controllers/MailchimpWebhookController.php):

public function handle(Request $request)
{
    $payload = $request->getContent();
    $signature = $request->header('X-Mailchimp-Signature');

    // Verify signature (use \MailchimpTransactional\Webhook::verify())
    if (Webhook::verify($payload, $signature, config('services.mailchimp.webhook_secret'))) {
        $event = json_decode($payload, true);
        // Process event (e.g., update user model)
    }
}

3. Batch Operations

Bulk Email Sends

$recipients = [
    ['email' => 'user1@example.com'],
    ['email' => 'user2@example.com'],
];

$mailchimp->messages->sendMany([
    'message' => [
        'to' => $recipients,
        'from' => 'sender@example.com',
        'subject' => 'Batch Send',
        'html' => '<p>Batch content.</p>',
    ],
]);

Subscriber Management

Add a subscriber:

$mailchimp->lists->addListMember('list_id', [
    'email_address' => 'user@example.com',
    'merge_fields' => [
        'FIRST_NAME' => 'John',
        'LAST_NAME' => 'Doe',
    ],
]);

4. Error Handling

Wrap API calls in a try-catch:

try {
    $response = $mailchimp->messages->send($emailData);
} catch (\MailchimpTransactional\Exception\ApiException $e) {
    Log::error('Mailchimp API Error: ' . $e->getMessage());
    // Retry logic or notify admin
}

Gotchas and Tips

Common Pitfalls

1. API Key vs. Region Mismatch

   • Ensure setServer() matches your Mailchimp account’s region (e.g., us12, eu1).
   • Example: setServer('us12') for US accounts.

2. Rate Limits

   • Mailchimp enforces rate limits (e.g., 100 requests/minute for Transactional).
   • Implement exponential backoff in retries:

     use Symfony\Component\RateLimiter\RateLimiterFactory;
     
     $factory = new RateLimiterFactory();
     $limiter = $factory->create($this->client, 100, 'minute');
     if (!$limiter->consume()) {
         sleep($limiter->wait());
     }
     

3. Webhook Verification

   • Always verify webhook payloads using Webhook::verify() to prevent spoofing.
   • Store the webhook secret in .env:

     MAILCHIMP_WEBHOOK_SECRET=your_webhook_secret_here
     

4. Template IDs

   • Template IDs are not the same as template_name. Fetch IDs via:

     $templates = $mailchimp->templates->getAll();
     $templateId = $templates['templates'][0]['id'];
     

5. Async Deliverability

   • Emails sent via the API may land in spam. Use:
     • Dedicated sending domains.
     • SPF/DKIM/DMARC records.
     • Mailchimp’s Transactional Email Guide.

Debugging Tips

1. Enable Debug Mode Configure the client to log requests:

   $mailchimp->setDebug(true);
   

   Logs appear in storage/logs/laravel.log.

2. Inspect Raw Responses Dump the full response object:

   dd($response->getBody());
   

3. Validate Payloads Use Mailchimp’s API Validator to test payloads before sending.

Extension Points

1. Custom Middleware Add middleware to the client for logging or transformations:

   $mailchimp->getHttpClient()->setDefaultOption('middleware', [
       new class implements \GuzzleHttp\Middleware {
           public function __invoke(callable $handler) {
               return function ($request, $options) {
                   // Modify request/options (e.g., add headers)
                   return $handler($request, $options);
               };
           }
       },
   ]);
   

2. Event Dispatching Trigger Laravel events after API calls:

   event(new MailchimpEmailSent($response));
   

3. Fallback for Failures Implement a fallback (e.g., send via Laravel’s Mail facade):

   try {
       $mailchimp->sendEmail($data);
   } catch (\Exception $e) {
       Mail::send([], [], function ($message) use ($data) {
           $message->to($data['to'])->subject($data['subject']);
       });
   }
   

Configuration Quirks

1. Timeouts Default timeout is 10 seconds. Adjust in Guzzle options:

   $mailchimp->getHttpClient()->setDefaultOption('timeout', 30);
   

2. Proxy Support