sendpulse / rest-api
Official PHP SDK for the SendPulse REST API
Requires
- php: >=8.3
- ext-curl: *
- ext-json: *
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.64
- phpstan/phpstan: ^2.0
- phpunit/phpunit: ^11.0
- psr/http-client: ^1.0
- psr/http-factory: ^1.1
- psr/simple-cache: ^3.0
Suggests
- psr/http-client: To plug in your own PSR-18 HTTP client (Guzzle, Symfony) instead of the bundled curl transport
- psr/simple-cache: To use your own PSR-16 cache for token storage instead of the default file cache
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-11 11:04:52 UTC
README
Official PHP client for the SendPulse REST API.
- PHP ≥ 8.3, zero runtime dependencies (
ext-curl,ext-json) - Thin transport: OAuth / API-key auth, automatic token refresh, typed exceptions
- Chained endpoint surface with IDE autocomplete —
$client->crm->deals->getDeal([...]) - Raw
get/post/...fallback for any endpoint - PSR-18 HTTP client and PSR-16 cache adapters available as optional drop-ins
- Ships
llms.txtfor AI coding assistants · PHPStan max · PSR-12
Requirements
- php: >=8.3
- ext-json: *
- ext-curl: *
Installation
composer require sendpulse/rest-api
Quick start
API key auth
use Sendpulse\RestApi\Client; $client = new Client(apiKey: 'YOUR_API_KEY');
OAuth (client credentials)
$client = new Client( clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', );
Tokens are fetched automatically and stored on disk between requests. A 401 is
retried once with a freshly minted token.
Calling endpoints
Chained surface
Mapped endpoints are reachable as a chain — service → resource → operation —
with IDE autocomplete for every segment and the parameter keys:
$campaigns = $client->email->campaigns->getCampaigns(['limit' => 10]); $campaign = $client->email->campaigns->getCampaignById(['id' => 12345]); $deal = $client->crm->deals->getDeal(['dealId' => 42]); $client->smtp->emails->sendSmtpEmail([ 'email' => [ 'subject' => 'Hello', 'from' => ['name' => 'Me', 'email' => 'me@example.com'], 'to' => [['name' => 'You', 'email' => 'you@example.com']], 'html' => base64_encode('<p>Hi!</p>'), ], ]);
You pass one associative array. Path params ({id}) and declared query
params are routed automatically; any other key goes to the JSON body (for a
GET it becomes a query param). Every call returns the decoded JSON response as
an array (empty body → []), or throws one of the exceptions below.
Hyphenated services (
file-manager,live-chat,viber-chatbot,web-push) cannot use the->arrow directly — wrap the service name in braces:$client->{'file-manager'}->directory->getDirectoryTree([]).
The full list of chains, paths and parameters lives in
resources/operations/ and is mirrored in
llms.txt.
Raw requests
For any endpoint not in the map — or when you want full control — call a path directly:
$client->get('/campaigns', ['limit' => 10]); // also query params $client->post('/smtp/emails', ['email' => [/* ... */]]); // put / patch / delete too // lowest level: $client->request('GET', '/campaigns'); $client->send(new \Sendpulse\RestApi\Http\Request(method: 'GET', uri: '/campaigns'));
IDE autocomplete
The chained surface is powered by generated stub definitions in
resources/ide/stubs.php:
-
PhpStorm / VS Code index them automatically — no setup.
-
PHPStan users: register them (they add no runtime cost) —
parameters: scanFiles: - vendor/sendpulse/rest-api/resources/ide/stubs.php
Error handling
use Sendpulse\RestApi\Exception\AuthException; use Sendpulse\RestApi\Exception\ForbiddenException; use Sendpulse\RestApi\Exception\RateLimitException; use Sendpulse\RestApi\Exception\ApiException; use Sendpulse\RestApi\Exception\NetworkException; use Sendpulse\RestApi\Exception\ProtocolException; try { $campaigns = $client->email->campaigns->getCampaigns(); } catch (AuthException $e) { // 401 — invalid or expired credentials } catch (ForbiddenException $e) { // 403 — tariff or permission restriction } catch (RateLimitException $e) { // 429 — back off and retry } catch (ApiException $e) { echo $e->httpStatus; // other 4xx / 5xx echo $e->rawBody; } catch (ProtocolException $e) { // response received but could not be parsed (malformed JSON from API) } catch (NetworkException $e) { // curl / transport error }
All six implement Sendpulse\RestApi\Exception\SendPulseExceptionInterface, so a
single catch (SendPulseExceptionInterface $e) covers every SDK error.
Configuration
$client = new Client( apiKey: 'key', connectTimeout: 10, // seconds, default requestTimeout: 30, // seconds, default );
Custom HTTP client (PSR-18)
use Sendpulse\RestApi\Http\Adapter\Psr18Adapter; $client = new Client( apiKey: 'key', httpClient: new Psr18Adapter( client: $yourPsr18Client, requestFactory: $requestFactory, streamFactory: $streamFactory, ), );
Custom token storage
use Sendpulse\RestApi\Token\Psr16TokenStorage; use Sendpulse\RestApi\Token\InMemoryTokenStorage; // PSR-16 cache (e.g. Symfony Cache, Laravel Cache) $storage = new Psr16TokenStorage($psr16Cache); // In-memory (tokens lost on process exit) $storage = new InMemoryTokenStorage(); $client = new Client( clientId: 'id', clientSecret: 'secret', tokenStorage: $storage, );
Default is FileTokenStorage (system temp directory or custom cacheDir).
Documentation
| Topic | |
|---|---|
| Authentication & token storage | docs/authentication.md |
| Exception reference | docs/exceptions.md |
| Testing | docs/testing.md |
| Laravel integration | docs/laravel.md |
| Upgrading | docs/upgrading.md |
| AI assistants | llms.txt |
License
MIT