Constantcontact Laravel Package

Getting Started

Install with Composer:

composer require phpfui/constantcontact

Before writing any code, complete the Constant Contact OAuth 2.0 registration in their developer portal so you have a client_id, client_secret, and a redirect URI. The package is a thin, generated-style wrapper around Constant Contact's v3 REST API, so the namespace hierarchy mirrors the API's endpoint structure rather than providing Laravel-native abstractions (no Contact model, no migrations, no Eloquent). Expect to spend the first hour reading vendor/phpfui/constantcontact/src/ — the class names map almost 1:1 to the API documentation, which is faster than searching for examples.

The first real use case: read-only list of contacts. Wire up a constructor with your credentials, run the authorization code flow once to obtain an access and refresh token, persist both, then instantiate the contacts endpoint class and call its get-style method with a limit parameter. If that returns a JSON-decoded payload with a contacts array, you're connected. Commit the token persistence before you write any business logic — everything else depends on it.

Implementation Patterns

Centralize the client in a service provider. Bind a singleton that hydrates credentials from config/services.php and loads the current access token from your database or cache. Don't instantiate the client inline in controllers; you'll need the same object across jobs, commands, and webhook handlers.

Own the token lifecycle explicitly. Constant Contact access tokens are short-lived. Wrap the client in a small ConstantContactService that catches 401s, calls your refresh routine, persists the new token pair, and retries once. Do not let refresh logic leak into controllers — token refreshes will happen constantly once you have any cron activity.

Use queued jobs for anything that touches contacts. Bulk contact creation and list membership updates are slow and rate-limited. A SyncContactToConstantContact job that upserts by email is the right granularity. This also gives you retries and dead-lettering for free, which matters because the API will 429 under load.

Paginate with cursors, not offsets. Constant Contact v3 returns a meta.pagination.next_cursor. Write a single eachContact(callable $cb) helper that loops until the cursor is empty — you will otherwise re-implement this in five places and get it wrong in three.

Prefer bulk import endpoints for backfills. If you're migrating an existing user table, hitting the per-contact endpoint thousands of times will both be slow and burn your rate limit. The bulk import activity endpoints accept CSV and report progress asynchronously — poll the activity ID until status is COMPLETED.

Integrate at the domain-event level. Fire UserRegistered → queue a job that creates the contact and adds it to the appropriate list. Resist the urge to write to Constant Contact inside your own model observers; keeping the sync asynchronous and idempotent makes the inevitable API outage a non-event.

Handle webhooks idempotently. Constant Contact can retry webhook deliveries. Verify the signature header before doing anything, then use the event ID as a dedupe key in your cache or jobs table.

Gotchas and Tips

• Token storage is your problem, not the package's. The library holds an access token in memory but has no knowledge of persistence. The most common first failure is a token that works in tinker and is null in a queued worker.
• The package is generated from the spec — method signatures drift. Minor library upgrades can change parameter shapes because they track the upstream OpenAPI spec. Pin a specific version in composer.json and read the changelog before upgrading. There is no UPGRADE.md to save you.
• Rate limits are aggressive. Constant Contact enforces per-application and per-account limits (single-digit requests per second on most endpoints). Add a token-bucket or RateLimiter in front of every call. A Retry-After header appears on 429s — respect it rather than using exponential backoff blindly.
• Email confirmation and GDPR rules override your intent. Depending on account settings, newly created contacts land in unconfirmed status and won't receive campaigns. If your "signup" flow assumes an immediate send, test against a sandbox account with the same confirmation settings as production.
• Lists vs. tags. Memberships can be expressed as named list memberships or as tags. Pick one mental model for your app and stick to it; mixing both in the same sync produces contacts that appear on your dashboard but not in your filtered views.
• Deletes are soft. Deleting a contact marks it as deleted but the email address may remain reserved. If you need true removal for a user-deletion request, look for the account-level forget/erase endpoint, not the standard delete.
• Errors come back as structured responses, not exceptions. Check the returned status/response object before assuming success; wrapping every call in try/catch alone will silently swallow validation failures (e.g. duplicate email, invalid list ID).
• Debug by logging the raw request via the package's HTTP client hooks (Laravel's Http::fake won't intercept if the package uses Guzzle directly). Register a Guzzle middleware that dumps URI and body to a dedicated constant-contact log channel. This single step will save you the most time of anything in this list.
• Never point production credentials at the sandbox. Their sandbox requires a separate app registration; tokens are not portable. Read the base URL from config, not from the package default.