Sendpulse Mailer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require andrei-mireichyk/sendpulse-mailer
   

2. Configure .env: Choose one of the supported schemes and add to your .env:

   MAILER_DSN=sendpulse://USERNAME:PASSWORD@default
   # OR
   MAILER_DSN=sendpulse+smtp-api://USER_ID:SECRET@default
   # OR (for Automation360 events)
   MAILER_DSN=sendpulse+events://USER_ID:SECRET@default
   

3. First Use Case: Send a basic email using Symfony Mailer’s Email class:

   use Symfony\Component\Mailer\MailerInterface;
   use Symfony\Component\Mime\Email;
   
   public function sendEmail(MailerInterface $mailer)
   {
       $email = (new Email())
           ->from('from@example.com')
           ->to('recipient@example.com')
           ->subject('Test Email')
           ->text('Hello, this is a test email!');
   
       $mailer->send($email);
   }
   

   Inject MailerInterface via dependency injection (Laravel’s Mail facade or Symfony’s DI container).

Implementation Patterns

Core Workflows

1. Basic Email Sending: Use Symfony’s Email class with SendPulse’s DSN. The package seamlessly integrates with Laravel’s Mail facade or Symfony’s MailerInterface.

   Mail::send(new Email()
       ->to('user@example.com')
       ->subject('Welcome')
       ->html('<h1>Welcome!</h1>')
   );
   

2. Custom Headers for SendPulse Features: Leverage SendPulse-specific headers for advanced use cases:

   • Events (Automation360):

     $email->getHeaders()->addTextHeader('X-SendPulse-Event', 'user_signup');
     

   • Variables (Personalization):

     $email->getHeaders()->add(new \Creonit\SendPulseMailer\Header\SendPulseVariableHeader('user_name', 'John'));
     

3. Async Sending (Queue): Laravel users can queue emails for async processing:

   Mail::to('user@example.com')->send(new WelcomeMail());
   

   Ensure your MailerInterface is bound to the SendPulse transport in Laravel’s config/mail.php.

4. Templates: Use SendPulse’s template system by referencing template IDs or names in the Email object (if supported by the package’s future updates).

Integration Tips

1. Laravel-Specific:

   • Bind the SendPulse transport in config/mail.php:

     'sendpulse' => [
         'transport' => 'sendpulse',
         'username' => env('SENDPULSE_USERNAME'),
         'password' => env('SENDPULSE_PASSWORD'),
     ],
     

   • Use Laravel’s Mail facade or inject MailerInterface into controllers/services.

2. Symfony-Specific: Configure the mailer in config/packages/mailer.yaml:

   framework:
       mailer:
           dsn: '%env(MAILER_DSN)%'
   

3. Testing: Mock MailerInterface in tests to avoid real API calls:

   $mailer = $this->createMock(MailerInterface::class);
   $mailer->expects($this->once())->method('send');
   

4. Logging: Enable Symfony’s mailer logging for debugging:

   $mailer->send($email, ['logger' => $logger]);
   

Gotchas and Tips

Pitfalls

1. DSN Configuration:

   • Incorrect Scheme: Ensure the DSN scheme matches SendPulse’s API type (sendpulse, sendpulse+smtp-api, or sendpulse+events). Mixing schemes (e.g., sendpulse+smtp instead of sendpulse+smtp-api) will fail silently or throw errors.
   • Credentials: Verify USERNAME:PASSWORD or USER_ID:SECRET are correct. SendPulse’s SMTP API uses USER_ID (not email) and SECRET (not password).

2. Headers Not Applied:

   • Custom headers like X-SendPulse-Event or SendPulseVariableHeader must be added before sending. Late additions may be ignored.
   • Case sensitivity: Headers like X-SendPulse-Event must match SendPulse’s expected format exactly.

3. Async Delays:

   • SendPulse’s SMTP API may introduce slight delays for processing. Test in staging to account for this.

4. Template Limitations:

   • The package does not natively support SendPulse’s template rendering. Use raw HTML/email content or manually reference template IDs in the subject/body if SendPulse’s API supports it.

5. Error Handling:

   • SendPulse may return HTTP errors (e.g., 401 for invalid credentials). Wrap calls in try-catch:

     try {
         $mailer->send($email);
     } catch (\Symfony\Component\Mailer\Exception\TransportException $e) {
         Log::error('SendPulse error: ' . $e->getMessage());
     }
     

Debugging Tips

1. Enable Verbose Logging: Configure Symfony’s mailer to log raw messages:

   $mailer->send($email, ['logger' => new \Monolog\Logger('mailer', [$this->logger])]);
   

2. Check Raw Headers: Inspect the Email object’s headers before sending:

   dump($email->getHeaders()->all());
   

3. SendPulse API Status: Verify SendPulse’s API status at SendPulse Status Page or use their API docs.

4. Test with SMTP: For debugging, temporarily switch to a local SMTP server (e.g., MailHog) by changing the DSN to:

   MAILER_DSN=smtp://mailhog:1025
   

Extension Points

1. Custom Headers: Extend the package by creating custom header classes (e.g., for SendPulse’s webhook events):

   class SendPulseWebhookHeader extends AbstractHeader
   {
       public function __construct(string $webhookUrl)
       {
           $this->header = 'X-SendPulse-Webhook';
           $this->value = $webhookUrl;
       }
   }
   

2. Event Dispatching: Listen for mailer.message.sent events (Symfony) to log or process SendPulse-specific data:

   $mailer->send($email, ['event_dispatcher' => $dispatcher]);
   

3. Transport Decorator: Decorate the SendPulse transport to add pre-send logic (e.g., analytics):

   $transport = new SendPulseTransport($client, $options);
   $transport = new AnalyticsDecorator($transport);
   

4. Queue Observers: In Laravel, observe mail queue jobs to enrich SendPulse metadata:

   Mail::addObserver(function ($event) {
       if ($event->mailable instanceof WelcomeMail) {
           $event->message->getHeaders()->addTextHeader('X-SendPulse-Campaign', 'welcome_series');
       }
   });