PHPackages creamailer/creamailer-api-sdk - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Mail & Notifications](/categories/mail) 4. / 5. creamailer/creamailer-api-sdk ActiveLibrary[Mail & Notifications](/categories/mail) creamailer/creamailer-api-sdk ============================= Official PHP SDK for the Creamailer API v2 v2.0.1(1mo ago)01.1kMITPHPPHP ^8.0 Since Feb 28Pushed 1mo ago2 watchersCompare [ Source](https://github.com/Creamailer/creamailer-api-sdk)[ Packagist](https://packagist.org/packages/creamailer/creamailer-api-sdk)[ Docs](https://github.com/creamailer/creamailer-api-sdk)[ RSS](/packages/creamailer-creamailer-api-sdk/feed)WikiDiscussions main Synced today READMEChangelog (5)Dependencies (3)Versions (8)Used By (0) Creamailer API SDK for PHP ========================== [](#creamailer-api-sdk-for-php) Official PHP SDK for the [Creamailer API v2](https://github.com/Creamailer/Creamailer-laravel/blob/master/docs/api-v2.md). Upgrading from v1? See [MIGRATION.md](MIGRATION.md). Release history: [CHANGELOG.md](CHANGELOG.md). Contents -------- [](#contents) - [Requirements](#requirements) - [Installation](#installation) - [Getting Started](#getting-started) - [Authentication](#authentication) - [Access Levels & Rate Limiting](#access-levels--rate-limiting) - [Error Handling](#error-handling) - [Lists](#lists) - [Subscribers](#subscribers) - [Subscriber Activity (CRM Integration)](#subscriber-activity-crm-integration) - [Suppressions](#suppressions) - [Pagination](#pagination) - [Manual Testing Against a Live API](#manual-testing-against-a-live-api) - [Testing in Your App](#testing-in-your-app) Requirements ------------ [](#requirements) - PHP 8.0+ - `ext-curl`, `ext-json` Installation ------------ [](#installation) ``` composer require creamailer/creamailer-api-sdk ``` > **Note:** This SDK targets the Creamailer API **v2**. If you are still using the v1 API, pin the v1 SDK: `composer require creamailer/creamailer-api-sdk:^1.0`. Getting Started --------------- [](#getting-started) You need your `ACCESS_TOKEN` and `SHARED_SECRET` from Creamailer Settings → API. ``` use Creamailer\Client; $creamailer = new Client( accessToken: getenv('CREAMAILER_ACCESS_TOKEN'), sharedSecret: getenv('CREAMAILER_SHARED_SECRET'), ); $result = $creamailer->ping(); print_r($result); // ['message' => 'Connection successful.'] ``` Authentication -------------- [](#authentication) The SDK signs every request with HMAC-SHA256 and a ±5-minute timestamp window. No additional configuration is needed beyond your credentials. Access Levels & Rate Limiting --------------------------------- [](#access-levels--rate-limiting) Each API key has an access level configured server-side: LevelPermissions`read`GET requests only — list/find/activity`write`All requests — create, update, delete, import, suppression managementA `403 AuthorizationException` is thrown if a `read` key calls a write endpoint. **Rate limit:** 100 requests per hour per API key. When the limit is hit, the SDK throws `RateLimitException` (HTTP 429). Implement back-off in your integration: ``` use Creamailer\Exceptions\RateLimitException; try { $client->subscribers()->all($listId); } catch (RateLimitException $e) { sleep(60); // back off and retry later } ``` Error Handling -------------- [](#error-handling) Failed requests throw typed exceptions: HTTPException401`Creamailer\Exceptions\AuthenticationException`403`Creamailer\Exceptions\AuthorizationException`404`Creamailer\Exceptions\NotFoundException`422`Creamailer\Exceptions\ValidationException` (see `->getErrors()`)429`Creamailer\Exceptions\RateLimitException`5xx`Creamailer\Exceptions\ServerException`network`Creamailer\Exceptions\TransportException`other`Creamailer\Exceptions\ApiException```` use Creamailer\Exceptions\ValidationException; try { $creamailer->lists()->create(['name' => '']); } catch (ValidationException $e) { foreach ($e->getErrors() as $field => $messages) { echo "$field: ".implode(', ', $messages).PHP_EOL; } } ``` Lists ----- [](#lists) ``` // List all lists $creamailer->lists()->all(); // Get a single list $creamailer->lists()->get(123); // Create $creamailer->lists()->create([ 'name' => 'Monthly Newsletter', 'language' => 'fi', 'auto_suppress' => true, ]); // Update $creamailer->lists()->update(123, ['name' => 'Renamed']); // Delete $creamailer->lists()->delete(123); // Get custom fields defined on the list $creamailer->lists()->fields(123); ``` Subscribers ----------- [](#subscribers) ``` // List subscribers (with optional filters) $creamailer->subscribers()->all(123, [ 'status' => 'active', // all, active, unsubscribed, bounced, spamreport, deleted 'pagesize' => 100, 'page' => 1, 'date' => '2024-01-01', // joined after this date ]); // Find one subscriber by email $creamailer->subscribers()->find(123, 'subscriber@example.com'); // Create $creamailer->subscribers()->create(123, [ 'email' => 'new@example.com', 'name' => 'Jane Smith', 'company' => 'Acme Inc', 'send_autoresponders' => true, 'custom_fields' => [ 'department' => 'Marketing', ], ]); // Update (use 'new_email' to change the email itself) $creamailer->subscribers()->update(123, [ 'email' => 'old@example.com', 'new_email' => 'new@example.com', 'name' => 'Updated Name', ]); // Delete (unsubscribe) $creamailer->subscribers()->delete(123, 'subscriber@example.com'); // Bulk import (max 500 per call) $creamailer->subscribers()->import(123, [ ['email' => 'a@example.com', 'name' => 'A'], ['email' => 'b@example.com', 'name' => 'B', 'update_existing' => true], ]); ``` Subscriber Activity (CRM Integration) ------------------------------------- [](#subscriber-activity-crm-integration) Retrieve a contact's full message history across **all your lists** — every campaign they received, opens, clicks, bounces, unsubscribes, and a direct browser-viewable link to each email. Ideal for showing email engagement timelines inside your CRM. ``` $activity = $creamailer->subscribers()->activity('contact@example.com', pagesize: 20); ``` ### Response shape [](#response-shape) ``` [ 'data' => [ 'email' => 'contact@example.com', 'summary' => [ 'total_messages' => 46, 'total_opens' => 37, 'total_clicks' => 53, 'total_bounces' => 0, 'total_unsubscribes' => 3, 'first_message_date' => '2021-06-06 17:43:17', ], 'messages' => [ 'current_page' => 1, 'last_page' => 10, 'data' => [ [ 'campaign_name' => 'March Newsletter', 'subject' => 'Our March Update', 'sender_name' => 'Acme Inc', 'sender_email' => 'news@acme.com', 'sent_date' => '2025-03-01 09:00:00', 'opens' => 3, 'clicks' => [ ['url' => 'https://example.com/offer', 'count' => 2], ], 'web_version_url' => 'https://acme.creamailer.fi/email/abc1234567890', ], // ... ], ], ], ] ``` ### Why this matters [](#why-this-matters) `web_version_url` links are **publicly accessible** (no authentication needed) and render the exact email content the contact received. Embed them in your CRM record so support staff can preview the email a customer is asking about. The endpoint is paginated — see [Pagination](#pagination) for how to walk all pages. Suppressions ------------ [](#suppressions) ``` // List suppressions $creamailer->suppressions()->all(pagesize: 200); // Add suppression $creamailer->suppressions()->create('blocked@example.com'); // Remove suppression $creamailer->suppressions()->delete('blocked@example.com'); ``` Pagination ---------- [](#pagination) Collection endpoints (`subscribers()->all()`, `subscribers()->activity()`, `suppressions()->all()`) return Laravel-style paginated responses. Pass `page` and `pagesize` (max 1000) and iterate: ``` $page = 1; do { $response = $client->subscribers()->all($listId, [ 'pagesize' => 500, 'page' => $page, ]); foreach ($response['data'] as $subscriber) { // ... process row } $lastPage = $response['meta']['last_page'] ?? 1; $page++; } while ($page 200, 'body' => '{"data": []}']; } } $client = new Client('token', 'secret', 'https://api.cmfile.net', new StubTransport); ``` License ------- [](#license) MIT — see [LICENSE](LICENSE). Support ------- [](#support) Report issues at [github.com/Creamailer/creamailer-api-sdk/issues](https://github.com/Creamailer/creamailer-api-sdk/issues). ### Health Score 47 — FairBetter than 93% of packages Maintenance90 Actively maintained with recent releases Popularity18 Limited adoption so far Community8 Small or concentrated contributor base Maturity59 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~307 days Recently: every ~384 days Total 6 Last Release 50d ago Major Versions v1.0.3 → v2.0.02026-05-15 PHP version history (2 changes)v1.0.0PHP >=5.6 v2.0.0PHP ^8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/fd985f5994954f75efc0c35bc0be2befebf031a212599a6a953daf33081ae867?d=identicon)[jami.pietila](/maintainers/jami.pietila) --- Top Contributors [![jamipietila](https://avatars.githubusercontent.com/u/16705804?v=4)](https://github.com/jamipietila "jamipietila (12 commits)") --- Tags apiemailmarketingnewslettercreamailer ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/creamailer-creamailer-api-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/creamailer-creamailer-api-sdk/health.svg)](https://phpackages.com/packages/creamailer-creamailer-api-sdk) ``` ### Alternatives [ecomailcz/ecomail Ecomail.cz API Wrapper 17418.3k4](/packages/ecomailcz-ecomail)[hocza/sendy Sendy API implementation for Laravel 71205.8k](/packages/hocza-sendy) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)