Sendpulse Mailer Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require creonit/sendpulse-mailer
   

   Add the package to config/mail.php under mailers:

   'sendpulse' => [
       'transport' => env('MAILER_DSN', 'sendpulse://default'),
   ],
   

2. Environment Configuration Use one of the supported DSN formats in .env:

   # SMTP (legacy)
   MAILER_DSN=sendpulse://USERNAME:PASSWORD@default
   
   # SMTP API (recommended)
   MAILER_DSN=sendpulse+smtp-api://USER_ID:SECRET@default
   
   # Automation360 Events
   MAILER_DSN=sendpulse+events://USER_ID:SECRET@default
   

3. First Use Case Send a basic email with SendPulse-specific headers:

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

Implementation Patterns

Core Workflows

1. Standard Email Sending Leverage Symfony Mailer’s fluent API with SendPulse’s transport:

   $mailer->send($email)
       ->then(function () { /* Success */ })
       ->otherwise(function (Throwable $e) { /* Failure */ });
   

2. Dynamic Headers for Automation Attach SendPulse-specific metadata:

   $email->getHeaders()
       ->addTextHeader('X-SendPulse-Event', 'user_signup')
       ->add(new \Creonit\SendPulseMailer\Header\SendPulseVariableHeader('user_id', $user->id));
   

3. Batch Processing Use Symfony’s MailerInterface with queues (e.g., Symfony Messenger or Laravel Queues):

   $mailer->send($email); // Non-blocking if async transport is configured
   

Integration Tips

• Laravel-Specific: Bind the mailer in AppServiceProvider:

  public function register()
  {
      $this->app->bind(MailerInterface::class, function ($app) {
          return new Mailer($app->make(SendPulseTransportFactory::class)->createTransport());
      });
  }
  

• Testing: Mock the MailerInterface in unit tests:

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

Gotchas and Tips

Pitfalls

1. DSN Format Sensitivity

   • Incorrect DSN (e.g., missing +smtp-api) will fail silently or throw cryptic errors.
   • Fix: Validate with php artisan config:clear after changes.

2. Header Injection Risks

   • Custom headers (e.g., X-SendPulse-Event) must be text-based or use SendPulseVariableHeader.
   • Fix: Avoid raw addHeader(); use the package’s header classes.

3. Rate Limits

   • SendPulse’s free tier has strict limits (e.g., 100 emails/day).
   • Fix: Monitor usage via SendPulse dashboard or implement retries with exponential backoff.

Debugging

• Enable Symfony Mailer Debug:

  $mailer = new Mailer($transport, [
      'debug' => true,
  ]);
  

• Check Raw Requests: Log the transport’s HTTP client (e.g., Guzzle) to inspect payloads:

  $transport->getClient()->setHandler(new \GuzzleHttp\HandlerStack([
      new \GuzzleHttp\Middleware::tap(function ($request) {
          \Log::debug('SendPulse Request', ['request' => $request]);
      }),
  ]));
  

Extension Points

1. Custom Headers Extend SendPulseVariableHeader for complex data:

   class CustomSendPulseHeader extends SendPulseVariableHeader
   {
       public function __construct(string $name, array $data)
       {
           parent::__construct($name, json_encode($data));
       }
   }
   

2. Transport Factories Override SendPulseTransportFactory to add middleware or logging:

   class CustomSendPulseTransportFactory extends SendPulseTransportFactory
   {
       protected function createTransport(): TransportInterface
       {
           $transport = parent::createTransport();
           // Add custom middleware
           return new HttpTransport($transport->getClient(), $transport->getUri());
       }
   }
   

3. Event Tracking Use X-SendPulse-Event for automation triggers, but validate event names against SendPulse’s API docs (e.g., user_signup vs USER_SIGNUP).