The Courier PHP SDK provides typed access to the Courier REST API from any PHP 8.1+ application. It uses named parameters for optional arguments and returns strongly typed response objects.
Available on
Installation Add to your composer.json:
{ "repositories" : [ { "type" : "vcs" , "url" : "git@github.com:trycourier/courier-php.git" } ], "require" : { "trycourier/courier" : "dev-main" } }
Then run composer install. Requires PHP 8.1+.
Quick Start <? php use Courier\ Client ; $client = new Client ( apiKey : getenv ( 'COURIER_API_KEY' )); $response = $client -> send -> message ( message : [ 'to' => [ 'email' => 'you@example.com' ], 'content' => [ 'title' => 'Hello from Courier!' , 'body' => 'Your first notification, sent with the PHP SDK.' , ], ], ); var_dump ( $response -> requestId );
Pass your API key via the COURIER_API_KEY environment variable or directly to the constructor: new Client(apiKey: 'your-key').
Authentication Get your API key from Settings > API Keys in the Courier dashboard. Set it as an environment variable:
export COURIER_API_KEY = "your-api-key"
Or pass it to the client constructor:
$client = new Client ( apiKey : 'your-api-key' );
Sending Notifications With a template $response = $client -> send -> message ( message : [ 'to' => [ 'user_id' => 'user_123' ], 'template' => 'my-template-id' , 'data' => [ 'orderNumber' => '10042' , 'itemName' => 'Courier Hoodie' ], ], );
With inline content $response = $client -> send -> message ( message : [ 'to' => [ 'email' => 'jane@example.com' ], 'content' => [ 'title' => 'Order shipped' , 'body' => 'Your order {{orderNumber}} has shipped!' , ], 'data' => [ 'orderNumber' => '10042' ], 'routing' => [ 'method' => 'single' , 'channels' => [ 'email' ]], ], );
Available Resources The SDK covers the full Courier API.
Resource Namespace Description Send $client->sendSend messages to one or more recipients Messages $client->messagesRetrieve status, history, and content of sent messages Profiles $client->profilesCreate, update, and retrieve user profiles Users $client->usersManage preferences, tenants, and push tokens per user Auth $client->authIssue JWT tokens for client-side SDK authentication Bulk $client->bulkSend messages to large recipient lists via jobs Lists $client->listsManage subscription lists and their subscribers Audiences $client->audiencesDefine and query audience segments Tenants $client->tenantsManage tenants for multi-tenant setups Automations $client->automationsInvoke multi-step automation workflows Brands $client->brandsManage brand settings (logos, colors, templates) Notifications $client->notificationsList and inspect notification templates Translations $client->translationsManage localized content
Common Operations Checking Message Status $message = $client -> messages -> retrieve ( 'your-message-id' ); echo $message -> status ; echo $message -> delivered ;
Managing User Profiles $client -> profiles -> create ( 'user_123' , profile : [ 'email' => 'jane@example.com' , 'phone_number' => '+15551234567' , 'name' => 'Jane Doe' , ]); $profile = $client -> profiles -> retrieve ( 'user_123' );
Issuing JWT Tokens $result = $client -> auth -> issueToken ( scope : 'user_id:user_123 inbox:read:messages inbox:write:events' , expiresIn : '2 days' , ); echo $result -> token ;
Scope Permission user_id:<id>Which user the token is for (required) inbox:read:messagesRead inbox messages inbox:write:eventsMark messages as read/archived read:preferencesRead notification preferences write:preferencesUpdate notification preferences write:user-tokensRegister push notification tokens
Configuration Error Handling The SDK throws typed exceptions for API failures. All extend Courier\Core\Exceptions\APIException:
use Courier\Core\Exceptions\ APIConnectionException ; use Courier\Core\Exceptions\ RateLimitException ; use Courier\Core\Exceptions\ APIStatusException ; try { $client -> send -> message ( message : [ 'to' => [ 'user_id' => 'user_123' ], 'template' => 'my-template' , ]); } catch ( APIConnectionException $e ) { echo "The server could not be reached \n " ; } catch ( RateLimitException $e ) { echo "Rate limited; back off a bit. \n " ; } catch ( APIStatusException $e ) { echo "API error: " . $e -> getMessage () . " \n " ; }
Retries The SDK automatically retries failed requests up to 2 times with exponential backoff.
// Disable retries $client = new Client ( requestOptions : [ 'maxRetries' => 0 ]); // Or per-request $client -> send -> message ( message : [ 'to' => [ 'user_id' => 'user_123' ], 'template' => 'my-template' ], requestOptions : [ 'maxRetries' => 5 ], );
More Operations The SDK covers the full Courier REST API . Here are a few more resources beyond what’s documented above:
Resource Method Use case User preferences $client->users->preferences->retrieve($userId)Fetch a user’s notification preferences for your preference center Cancel a message $client->messages->cancel($messageId)Cancel a delayed or queued message before delivery Push tokens $client->users->tokens->addSingle($token, userId: $userId)Register a device push token for iOS , Android , or React Native Automations $client->automations->invoke->invokeAdHoc(automation: ...)Run a multi-step workflow via Automations
