Laravel Sendpulse Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require kowap/laravel-sendpulse
   

   Publish the config file:

   php artisan vendor:publish --provider="Kowap\SendPulse\SendPulseServiceProvider"
   

2. Configuration Edit .env with your SendPulse API key:

   SENDPULSE_API_KEY=your_api_key_here
   

3. First Use Case: Sending an Email Use the SendPulseMailer facade or inject the service into a controller:

   use Kowap\SendPulse\Facades\SendPulseMailer;
   
   SendPulseMailer::send([
       'to' => ['email@example.com'],
       'subject' => 'Test Email',
       'html' => '<h1>Hello from SendPulse!</h1>',
   ]);
   

4. Where to Look First

   • Service Provider: Kowap\SendPulse\SendPulseServiceProvider for binding details.
   • Facade: Kowap\SendPulse\Facades\SendPulseMailer for quick usage.
   • Config File: config/sendpulse.php for customization.

Implementation Patterns

Core Workflows

1. Sending Emails Use the facade or service directly:

   SendPulseMailer::send([
       'to' => ['user@example.com', 'admin@example.com'],
       'subject' => 'Welcome',
       'html' => '<p>Welcome to our platform!</p>',
       'text' => 'Welcome to our platform!',
   ]);
   

2. Sending SMS

   SendPulseMailer::sms([
       'to' => '+1234567890',
       'text' => 'Your verification code is 123456.',
   ]);
   

3. Sending Push Notifications

   SendPulseMailer::push([
       'to' => ['device_token_1', 'device_token_2'],
       'title' => 'New Message',
       'message' => 'You have a new notification.',
   ]);
   

4. Integrating with Laravel Mail Override the default mailer in config/mail.php:

   'driver' => 'sendpulse',
   

Advanced Patterns

1. Customizing Templates Use SendPulse’s template IDs for pre-designed emails:

   SendPulseMailer::send([
       'to' => ['user@example.com'],
       'template_id' => 12345, // Your SendPulse template ID
       'variables' => ['name' => 'John'],
   ]);
   

2. Handling Responses Capture SendPulse’s response for logging or retries:

   $response = SendPulseMailer::send([...]);
   if ($response->success) {
       // Handle success
   }
   

3. Queueing Messages Use Laravel’s queue system for async sending:

   SendPulseMailer::later(now()->addMinutes(5), [
       'to' => ['user@example.com'],
       'subject' => 'Delayed Email',
       'html' => '<p>This email was delayed.</p>',
   ]);
   

4. Event Listeners Trigger SendPulse actions on Laravel events (e.g., registered):

   public function handle(Registered $event)
   {
       SendPulseMailer::send([
           'to' => [$event->user->email],
           'subject' => 'Account Created',
           'html' => 'Welcome!',
       ]);
   }
   

Gotchas and Tips

Common Pitfalls

1. API Key Validation

   • Ensure SENDPULSE_API_KEY is correctly set in .env. Missing or invalid keys will throw exceptions.
   • Test with a dummy key first to avoid hitting rate limits:

     SENDPULSE_API_KEY=dummy_key_123
     

2. Rate Limits

   • SendPulse has rate limits (e.g., 100 requests/minute). Queue messages during peak times to avoid throttling.
   • Monitor responses for 429 Too Many Requests errors.

3. Template IDs

   • Hardcoding template IDs is fragile. Fetch them dynamically from a database or config if possible.
   • Verify template IDs exist in SendPulse before use (invalid IDs return 404).

4. Character Limits

   • SMS messages are limited to 1600 characters (SendPulse splits longer messages). Test long messages to ensure proper segmentation.

5. Webhook Delays

   • SendPulse webhooks (e.g., for open/click tracking) may have delays. Avoid relying on real-time data for critical actions.

Debugging Tips

1. Enable Logging Add this to config/sendpulse.php to log all requests:

   'log' => true,
   

   Check storage/logs/laravel.log for details.

2. Inspect Responses Use dd() or Log::debug() to inspect raw responses:

   $response = SendPulseMailer::send([...]);
   Log::debug('SendPulse Response:', $response->toArray());
   

3. Testing Locally Use a mock API key or a local SendPulse sandbox environment to test without real sends.

Extension Points

1. Custom HTTP Client Override the default Guzzle client in the service provider:

   $this->app->singleton('sendpulse.http_client', function () {
       return new \GuzzleHttp\Client(['timeout' => 30]);
   });
   

2. Event Dispatching Extend the package to dispatch Laravel events after sends:

   // In a service provider or trait
   SendPulseMailer::afterSend(function ($response) {
       event(new SendPulseSent($response));
   });
   

3. Batch Processing Use Laravel’s chunk() to process large lists of recipients:

   User::chunk(100, function ($users) {
       $emails = $users->pluck('email')->toArray();
       SendPulseMailer::send(['to' => $emails, 'subject' => 'Batch Email']);
   });
   

4. Fallback Mailers Combine with Laravel’s default mailer for fallback:

   try {
       SendPulseMailer::send([...]);
   } catch (\Exception $e) {
       Mail::raw('Fallback email content', function ($message) {
           $message->to('user@example.com')->subject('Fallback Email');
       });
   }
   

Configuration Quirks

1. Default From Address SendPulse ignores the from field in emails. Use SendPulse’s configured default sender or set it via their dashboard.

2. Unicode Support Ensure SMS/text content uses UTF-8 encoding to avoid garbled characters in some regions.

3. Time Zones SendPulse uses UTC for scheduled messages. Convert Laravel’s timestamps to UTC before scheduling:

   SendPulseMailer::later(now()->timezone('UTC')->addHours(1), [...]);