Sendinblue Notifier Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require symfony/sendinblue-notifier
   

   Ensure sendinblue-notifier is enabled in config/services.php:

   'sendinblue' => [
       'api_key' => env('SENDINBLUE_API_KEY'),
       'default_from' => env('SENDINBLUE_DEFAULT_FROM', 'noreply@example.com'),
   ],
   

2. First Use Case: Sending an Email Inject the SendinblueNotifier service into a controller or command:

   use Symfony\Component\Notifier\NotifierInterface;
   use Symfony\Component\Notifier\Bridge\Sendinblue\SendinblueTransportFactory;
   
   public function sendWelcomeEmail(NotifierInterface $notifier)
   {
       $notifier->send(
           new Email('Welcome!', 'user@example.com', 'Hello, welcome to our platform!')
       );
   }
   

3. Configuration

   • Set SENDINBLUE_API_KEY in .env:

     SENDINBLUE_API_KEY=your_api_key_here
     

   • Optionally configure default sender in config/services.php.

Implementation Patterns

Common Workflows

1. Sending Emails Use the Email message class for transactional emails:

   $notifier->send(
       new Email('Subject', 'to@example.com', 'Body', ['from@example.com'])
   );
   

2. Sending SMS Use the Sms message class:

   $notifier->send(
       new Sms('Your code is 1234', 'to:+1234567890')
   );
   

3. Templates For reusable templates, define them in config/packages/sendinblue_notifier.yaml:

   sendinblue_notifier:
       templates:
           welcome_email:
               template_id: 123
               variables:
                   name: '{{ user.name }}'
   

   Then use them in code:

   $notifier->send(
       new Email('Welcome', 'user@example.com', null, null, null, ['template_id' => 'welcome_email'])
   );
   

4. Async Sending Use the AsyncNotifier wrapper for background processing:

   $asyncNotifier = new AsyncNotifier($notifier);
   $asyncNotifier->send($email);
   

Integration Tips

• Laravel Events: Trigger emails from events:

  public function handle(UserRegistered $event)
  {
      $this->notifier->send(
          new Email('Welcome', $event->user->email, 'Welcome content!')
      );
  }
  

• Validation: Validate email addresses before sending:

  if (filter_var($email, FILTER_VALIDATE_EMAIL)) {
      $notifier->send($email);
  }
  

• Logging: Log failed sends for debugging:

  try {
      $notifier->send($email);
  } catch (\Exception $e) {
      \Log::error('Sendinblue error: ' . $e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never hardcode SENDINBLUE_API_KEY in code. Always use .env.
   • Restrict API key permissions in Sendinblue dashboard to only necessary actions.

2. Rate Limits

   • Sendinblue enforces rate limits (e.g., 100 emails/minute for free tier). Handle TooManyRequestsHttpException gracefully:

     try {
         $notifier->send($email);
     } catch (\Symfony\Component\Notifier\Exception\TooManyRequestsHttpException $e) {
         // Retry later or queue the email
     }
     

3. Template IDs

   • Ensure template IDs in config match those in Sendinblue’s dashboard. Mismatches will fail silently.

4. Async Delays

   • Async sending may introduce delays. Use AsyncNotifier only for non-critical emails.

Debugging

• Enable Debug Mode Set SENDINBLUE_DEBUG=true in .env to log raw API responses:

  SENDINBLUE_DEBUG=true
  

• Check HTTP Status Codes Wrap sends in try-catch to inspect HttpException details for failed requests.

Extension Points

1. Custom Transports Extend SendinblueTransport to add custom logic (e.g., retry logic):

   class CustomSendinblueTransport extends SendinblueTransport
   {
       protected function doSend(Message $message): void
       {
           // Custom logic before sending
           parent::doSend($message);
       }
   }
   

   Register it in config/packages/sendinblue_notifier.yaml:

   sendinblue_notifier:
       transport: App\Transport\CustomSendinblueTransport
   

2. Event Listeners Subscribe to NotifierEvent to intercept sends:

   $notifier->on('send', function (NotifierEvent $event) {
       if ($event->getMessage() instanceof Email) {
           // Modify or log the email
       }
   });
   

3. Webhook Validation Validate Sendinblue webhook signatures if using inbound APIs:

   use Symfony\Component\Notifier\Bridge\Sendinblue\WebhookValidator;
   
   $validator = new WebhookValidator('your_webhook_secret');
   if ($validator->validate($request->getContent(), $request->headers->get('X-Signature'))) {
       // Process webhook
   }
   

Config Quirks

• Default From Address Override the default from address per message:

  new Email('Subject', 'to@example.com', 'Body', ['custom@example.com'])
  

• Bcc/Reply-To Use the Email constructor’s replyTo and bcc parameters:

  new Email('Subject', 'to@example.com', 'Body', null, null, null, ['reply_to' => 'support@example.com'])