Api V3 Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sendinblue/api-v3-sdk:^8.0
   

   Add to composer.json if needed:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "SendinBlue\\": "vendor/sendinblue/api-v3-sdk"
       }
   }
   

2. First Use Case: Fetch account details (replace YOUR_API_KEY):

   use SendinBlue\Client\Api\AccountApi;
   use SendinBlue\Client\ApiException;
   use SendinBlue\Client\Configuration;
   
   $config = Configuration::getDefaultConfiguration()
       ->setApiKey('api-key', 'YOUR_API_KEY');
   
   $api = new AccountApi(null, $config);
   try {
       $account = $api->getAccount();
       dd($account); // Debug account data
   } catch (ApiException $e) {
       dd($e->getResponseBody());
   }
   

Key Entry Points

• API Clients: Organized by feature (e.g., ContactsApi, EcommerceApi).
• Configuration: Centralized in SendinBlue\Client\Configuration.
• Models: Request/response objects in SendinBlue\Client\Model\.

Implementation Patterns

1. Service Layer Integration

Wrap API calls in a Laravel service class for reusability:

namespace App\Services;

use SendinBlue\Client\Api\ContactsApi;
use SendinBlue\Client\Model\Contact;

class ContactService {
    protected $api;

    public function __construct() {
        $this->api = new ContactsApi(null, config('services.sendinblue'));
    }

    public function createContact(array $data): Contact {
        return $this->api->createContact(new Contact($data));
    }
}

2. Batch Operations

Use batch endpoints for efficiency (e.g., bulk contact updates):

$batchData = [
    ['id' => 1, 'email' => '[email protected]'],
    ['id' => 2, 'email' => '[email protected]']
];
$response = $this->api->updateBatchContacts($batchData);

3. Event-Driven Workflows

Listen for SendinBlue webhooks (e.g., contact updates) via Laravel events:

// routes/web.php
Route::post('/sendinblue/webhook', [WebhookController::class, 'handle']);

// app/Http/Controllers/WebhookController.php
public function handle(Request $request) {
    event(new SendinBlueWebhookReceived($request->all()));
}

4. Configuration Management

Store API keys in .env and bind to Laravel config:

SENDINBLUE_API_KEY=your_api_key_here
SENDINBLUE_PARTNER_KEY=your_partner_key_here

// config/services.php
'sendinblue' => [
    'api_key' => env('SENDINBLUE_API_KEY'),
    'partner_key' => env('SENDINBLUE_PARTNER_KEY'),
],

5. Error Handling

Centralize API error responses:

try {
    $result = $api->getContacts();
} catch (ApiException $e) {
    $error = json_decode($e->getResponseBody(), true);
    throw new \RuntimeException($error['message'] ?? $e->getMessage());
}

Gotchas and Tips

1. API Key Management

• Gotcha: The library supports two keys (api-key and partner-key). Ensure you use the correct one for your endpoint (e.g., partner-key for transactional emails).
• Tip: Use Laravel’s config() helper to dynamically switch keys:

  $config = Configuration::getDefaultConfiguration()
      ->setApiKey('api-key', config('services.sendinblue.api_key'));
  

2. Rate Limiting

• Gotcha: SendinBlue enforces rate limits. Exceeding limits returns 429 Too Many Requests.
• Tip: Implement exponential backoff in your service layer:

  use GuzzleHttp\Exception\RequestException;
  
  try {
      $response = $api->getContacts();
  } catch (RequestException $e) {
      if ($e->getCode() === 429) {
          sleep(2); // Retry after delay
          return $this->getContacts();
      }
      throw $e;
  }
  

3. Pagination

• Gotcha: List endpoints (e.g., getContacts()) paginate by default. Use limit and offset parameters:

  $contacts = $api->getContacts(['limit' => 50, 'offset' => 0]);
  

• Tip: For large datasets, implement cursor-based pagination:

  $lastId = null;
  do {
      $params = ['limit' => 100];
      if ($lastId) $params['offset'] = $lastId;
      $contacts = $api->getContacts($params);
      $lastId = end($contacts)->getId();
  } while ($contacts);
  

4. Webhook Verification

• Gotcha: Always verify SendinBlue webhook payloads to prevent spoofing. Use the X-Signature header:

  public function handle(Request $request) {
      $signature = $request->header('X-Signature');
      $payload = $request->getContent();
      $expectedSignature = hash_hmac('sha256', $payload, config('services.sendinblue.webhook_secret'));
  
      if (!hash_equals($signature, $expectedSignature)) {
          abort(403, 'Invalid signature');
      }
  }
  

5. Model Validation

• Gotcha: The SDK auto-maps request data to models, but invalid fields (e.g., email without @) may silently fail.
• Tip: Validate data before sending:

  use Illuminate\Support\Facades\Validator;
  
  $validator = Validator::make($data, [
      'email' => 'required|email',
      'firstName' => 'sometimes|string',
  ]);
  if ($validator->fails()) {
      throw new \InvalidArgumentException($validator->errors()->first());
  }
  

6. Testing

• Gotcha: Mock the SendinBlue\Client\Api classes in tests to avoid real API calls:

  $mockApi = Mockery::mock(SendinBlue\Client\Api\ContactsApi::class);
  $mockApi->shouldReceive('createContact')
      ->once()
      ->andReturn(new Contact(['id' => 123]));
  
  $service = new ContactService($mockApi);
  

• Tip: Use Laravel’s Http facade to stub Guzzle requests:

  Http::fake([
      'api.sendinblue.com/*' => Http::response(['success' => true], 200),
  ]);
  

7. Custom HTTP Client

• Tip: Inject a custom Guzzle client for middleware (e.g., logging, retries):

  $client = new GuzzleHttp\Client([
      'timeout' => 30,
      'headers' => ['User-Agent' => 'MyApp/1.0'],
  ]);
  $api = new ContactsApi($client, $config);
  

8. Deprecation Note

• Gotcha: The package is marked as deprecated in its README. Monitor SendinBlue’s official docs for updates or forks (e.g., spatie/laravel-sendinblue).