Weave Code
Mailcoach Sdk Php Laravel Package
spatie/mailcoach-sdk-php
A PHP SDK for the Mailcoach API that supports both self-hosted Mailcoach v6 and up and hosted Mailcoach Cloud. It lets you create and send campaigns, send test emails, manage email lists and subscribers, and work with paginated resources using next(). Suitable for Laravel and any PHP application.
spatie/mailcoach-sdk-php is a PHP SDK for the Mailcoach API, supporting both self-hosted Mailcoach (v6+) and hosted Mailcoach Cloud. It lets you manage email lists, subscribers, and campaigns from any PHP application through a clean, fluent interface.
Paginated endpoints (default limit: 1000) are handled elegantly — call ->next() on a result to fetch the following page and iterate with a simple do/while loop.
- Campaign management — create campaigns, send tests, and send them
- Subscriber access — list and iterate subscribers per email list
- Pagination built in — walk large result sets with
->next() - Framework-agnostic — works in Laravel or plain PHP
- One SDK, two platforms — Cloud and self-hosted
Frequently asked questions about Mailcoach Sdk Php
- How do I install and configure spatie/mailcoach-sdk-php in a Laravel app?
- Install it with composer require spatie/mailcoach-sdk-php guzzlehttp/guzzle. Then create a client with new Mailcoach('your-api-key', 'your-mailcoach-endpoint') and pass it around, or bind it as a singleton in a service provider using credentials from config/services.php. There are no migrations, config files, or publishable assets, so the whole setup is a few lines of wiring. Keep the client behind a small repository or service class so the SDK does not leak into your controllers.
- Is spatie/mailcoach-sdk-php a Laravel package with a service provider and facade?
- No. It is a framework-agnostic, Guzzle-backed HTTP client that exposes typed resource objects such as EmailList, Subscriber, and Campaign against the Mailcoach REST API. There is no service provider, facade, config file, or Blade component shipped with it. In Laravel you build the integration yourself: a container binding, a services.mailcoach config entry, a thin repository layer, and queued jobs for writes.
- Does this SDK work with self-hosted Mailcoach and Mailcoach Cloud?
- Yes, both are supported. Self-hosted Mailcoach v6 and up and hosted Mailcoach Cloud use the same API surface, and you simply pass the matching API endpoint and key to the Mailcoach constructor. The trade-off is that with self-hosted installs you also own API availability, rate limits, and upgrade windows. The SDK itself adds no runtime footprint beyond the HTTP calls.
- What PHP version does the SDK require and is it still maintained?
- Release 1.10.0 raised the minimum to PHP 8.3, so teams on PHP 8.1 or 8.2 are pinned to 1.9.x and will not receive new features. Treat the PHP version as a gating prerequisite before you plan the integration. Maintenance is solid: Spatie ships an active changelog and runs Pest and PHPStan in CI, and the MIT license plus small surface area make a fork a matter of days if needed. Watch the changelog on every bump, since 1.8.0 changed isSubscribed() semantics and added isUnconfirmed().
- How do I paginate through all subscribers in an email list?
- Call the resource collection and loop with while ($subscribers = $subscribers->next()) so the SDK fetches each page for you. Mailcoach paginates with a default page size of 1000, so a naive loop over a very large list is both a memory and an API quota hazard. Process records inside the loop instead of collecting them all, and consider chunked background jobs for big lists.
- How do I send a campaign or a test email with the SDK?
- Create the campaign with createCampaign(), passing the email_list_uuid, a name, and the fields for your title and content. Then call sendTest('[email protected]') to deliver a preview, or send() to dispatch the full campaign. Both methods are real POST requests against Mailcoach, so make sure they only run when you actually intend to send.
- Is it safe to retry a queued job that sends a campaign?
- Not blindly. send() and sendTest() are non-idempotent POSTs and the SDK does not accept an idempotency key, so a retried queue job can double-send a campaign to your whole list. Guard the job with a state check on campaign status before sending, or use a single-attempt job with alerting instead of automatic retries. Decide up front what the blast radius of a duplicate send is for your audience.
- Does the SDK handle Mailcoach webhooks like subscriber confirmed or unsubscribed?
- No, the SDK is outbound only. Inbound events such as subscriber confirmed, unsubscribed, or bounced require your own HTTP endpoint, signature verification, and queueing on the Laravel side. Do not scope a two-way sync assuming the SDK covers the inbound direction. Build and test that webhook receiver as a separate piece of the integration.
- How should I handle Mailcoach API rate limits with this SDK?
- The SDK throws a RateLimitedException, added in version 1.9.1, but the backoff policy is yours to define. The usual Laravel approach is to let the job release itself with exponential backoff and a sensible maxAttempts, and to cap concurrency on queues that hammer the API. Remember that self-hosted and Cloud setups can have very different limits.
- Can I create subscribers in bulk with spatie/mailcoach-sdk-php?
- The SDK only offers single-record creation, so there is no bulk endpoint to call. Large backfills mean looping create calls, which makes rate limiting and job batching your responsibility. Throttle the queue workers, keep jobs small and restartable, and consider importing through a dedicated path if you need high throughput. Also note that subscriber state checks changed in 1.8.0, so verify isSubscribed() versus isUnconfirmed() before branching on it.
Weaver
How can I help you explore Laravel packages today?