Laravel Lemlist Laravel Package

Getting Started

1. Install via Composer and pin the initial major version, e.g. composer require <vendor>/<package>:^1.0. Use the README for the exact package name.
2. Publish any package config if available, typically php artisan vendor:publish --tag=lemlist-config, then add LEMLIST_API_KEY to .env and run php artisan config:clear.
3. Resolve the client through Laravel’s container or facade from one small service/action class rather than calling it directly throughout controllers.
4. Validate credentials with a harmless read call, such as listing campaigns. First practical use case: find a campaign and add/update a lead, then handle duplicate-lead responses cleanly.
5. Look first at the README, config/lemlist.php if present, the service provider binding, the main client class, and tests/examples. Since 1.0.0 is an initial release, inspect the source for pagination, error handling, and webhook verification details.

Implementation Patterns

• Wrap Lemlist calls in application services or action classes. Keep controllers, jobs, and listeners thin and testable.
• Queue outbound writes such as lead creation, campaign updates, and unsubscribe handling. Use retries with backoff and avoid retrying non-idempotent requests blindly.
• For campaign/lead sync, store the Lemlist campaign ID and lead/email mapping locally. Prefer deterministic matching by email and treat duplicate-lead errors as expected state rather than failures.
• For webhooks, route to a dedicated endpoint, verify signatures if supported, return 200 quickly, and dispatch processing to a queue. Disable CSRF for the webhook route or place it under the appropriate API middleware.
• Make webhook handling idempotent: store event IDs or a deduplication key, and guard against replay/out-of-order delivery.
• Treat unsubscribes as suppression events. Update a local suppression list and stop future sends, while distinguishing global unsubscribe from campaign-specific state if the API exposes both.
• Use activities for audit/history sync. Persist remote activity IDs and timestamps so repeated pulls or webhook deliveries do not create duplicates.
• Configure timeouts, base URL, and retry behavior through config/env rather than hard-coding. Use separate API credentials per environment.
• Test with Http::fake() if the package uses Laravel’s HTTP client, or mock the client contract/binding if it exposes one.

Gotchas and Tips

• This is a 1.0.0 initial release: expect a thinner API surface and less battle-tested edge-case handling. Read the source and tests before relying on undocumented behavior.
• Watch for rate limits. Retry only on 429 and transient 5xx responses, respect Retry-After, and avoid aggressive parallel writes.
• Pagination may be cursor-based, offset-based, or bounded by API defaults. Do not assume a single response contains all campaigns, leads, or activities.
• Duplicate leads, already-unsubscribed contacts, and missing campaigns are normal integration states. Map API errors to domain outcomes instead of generic exceptions.
• Webhook endpoints are a common failure point: CSRF, signature verification, slow processing, and non-idempotent handlers. Log the event ID, verify the payload, and process asynchronously.
• After changing .env values, run php artisan config:clear or config:cache as appropriate; otherwise stale API keys/base URLs are a frequent debugging trap.
• Never log raw API keys or full webhook payloads containing PII. Log request IDs/correlation IDs and sanitized error context.
• Extension points to check first: container binding, publishable config, custom HTTP/Guzzle client injection, and service provider events. Avoid patching vendor code; prefer decorating the client or wrapping it in your own service.