Managesend Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dreamcampaigns/managesend-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       Managesend\ApiBundle\ManagesendApiBundle::class => ['all' => true],
   ];
   

2. Configuration: Add your API credentials to config/packages/managesend_api.yaml:

   managesend_api:
       api_key: '%env(MANAGESEND_API_KEY)%'
       api_secret: '%env(MANAGESEND_API_SECRET)%'
       client_id: '%env(MANAGESEND_CLIENT_ID)%'  # Optional
       timeout: 60
   

3. First Use Case: Inject the ManagesendApi service into a controller or service:

   use Managesend\ApiBundle\Service\ManagesendApi;
   
   class EmailController extends AbstractController
   {
       public function __construct(private ManagesendApi $managesend)
       {
       }
   
       public function sendEmail()
       {
           $response = $this->managesend->sendEmail([
               'to' => ['email@example.com'],
               'subject' => 'Test Email',
               'html' => '<p>Hello, world!</p>',
           ]);
           return new JsonResponse($response);
       }
   }
   

Implementation Patterns

Core Workflows

1. Email Management:

   • Sending Emails:

     $this->managesend->sendEmail([
         'to' => ['recipient1@example.com', 'recipient2@example.com'],
         'subject' => 'Welcome',
         'html' => '<h1>Welcome!</h1>',
         'text' => 'Plain text fallback',
     ]);
     

   • Templates:

     // Save a template
     $this->managesend->saveTemplate('welcome_email', [
         'subject' => 'Welcome',
         'html' => '<p>Welcome, {{name}}!</p>',
     ]);
     
     // Send using template
     $this->managesend->sendTemplate('welcome_email', ['name' => 'John']);
     

2. Contact Management:

   • Add/Update Contacts:

     $this->managesend->addContact([
         'email' => 'user@example.com',
         'first_name' => 'John',
         'last_name' => 'Doe',
         'custom_fields' => ['membership_level' => 'premium'],
     ]);
     

   • List Management:

     $this->managesend->addContactToList('newsletter', 'user@example.com');
     

3. Campaigns:

   • Trigger Campaigns:

     $this->managesend->triggerCampaign('welcome_series', ['user@example.com']);
     

Integration Tips

• Event Listeners: Use Symfony events to sync contacts or campaigns with your app’s lifecycle (e.g., onUserRegistered).

  // src/EventListener/ManagesendSyncListener.php
  public function onUserRegistered(UserRegisteredEvent $event)
  {
      $this->managesend->addContact([
          'email' => $event->getUser()->getEmail(),
          'first_name' => $event->getUser()->getFirstName(),
      ]);
  }
  

• Batch Operations: For large datasets, use chunking to avoid API rate limits:

  $contacts = $this->contactRepository->findAll();
  array_chunk($contacts, 50, function ($chunk) {
      foreach ($chunk as $contact) {
          $this->managesend->addContact($contact->toArray());
      }
  });
  

• Error Handling: Wrap API calls in try-catch blocks to handle ManagesendApiException:

  try {
      $response = $this->managesend->sendEmail($data);
  } catch (ManagesendApiException $e) {
      $this->logger->error('Managesend API error: ' . $e->getMessage());
      // Retry logic or fallback
  }
  

Gotchas and Tips

Pitfalls

1. API Rate Limits:

   • The bundle doesn’t auto-retry on rate limits. Implement exponential backoff in your service layer.
   • Monitor responses for 429 Too Many Requests and handle accordingly.

2. Configuration Overrides:

   • Avoid hardcoding credentials. Use Symfony’s %env() or parameter bags for secrets.
   • Validate config/packages/managesend_api.yaml exists before use (Symfony may skip missing configs silently).

3. Deprecated Methods:

   • The underlying managesend-php library may change. Check its changelog for breaking changes.

4. Async Operations:

   • Some API calls (e.g., campaign triggers) may return immediately while processing happens in the background. Confirm with DreamCampaigns’ docs.

Debugging

• Enable API Debugging: Set debug: true in config to log raw API requests/responses:

  managesend_api:
      debug: true
  

  Logs appear in var/log/dev.log.

• Common Errors:

  • Invalid API Key: Double-check api_key and api_secret in config.
  • Missing Required Field: Validate payloads against DreamCampaigns API docs.
  • Timeout: Increase timeout in config or optimize payload size.

Extension Points

1. Custom Responses: Extend the ManagesendApi service to transform responses:

   // src/Service/CustomManagesendApi.php
   class CustomManagesendApi extends ManagesendApi
   {
       public function sendEmail(array $data)
       {
           $response = parent::sendEmail($data);
           return $this->formatResponse($response);
       }
   
       private function formatResponse(array $response): array
       {
           // Custom logic (e.g., add metadata)
           return array_merge($response, ['processed_at' => now()->toAtomString()]);
       }
   }
   

   Override the service in config/services.yaml:

   services:
       Managesend\ApiBundle\Service\ManagesendApi: '@custom_managesend_api'
   

2. Webhook Handling: Use Symfony’s HttpKernel to validate and process DreamCampaigns webhooks:

   // src/Controller/ManagesendWebhookController.php
   public function handleWebhook(Request $request, ManagesendApi $managesend)
   {
       $payload = json_decode($request->getContent(), true);
       $signature = $request->headers->get('X-Managesend-Signature');
   
       if (!$managesend->validateWebhook($payload, $signature)) {
           throw $this->createAccessDeniedException();
       }
   
       // Process event (e.g., 'contact.created')
       $this->eventDispatcher->dispatch(new ManagesendWebhookEvent($payload));
   }
   

3. Testing: Mock the ManagesendApi service in PHPUnit:

   $this->mockBuilder->getContainer()
       ->andReturn(self::createMock(ManagesendApi::class), argumentThat(function ($service) {
           return $service instanceof ManagesendApi;
       }));