Skip to main content
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 GitHub.
The PHP SDK is currently in beta. APIs may change between releases. Share feedback or report issues on GitHub.

​
Installation

Add to your composer.json: 
{
  "repositories": [
    {
      "type": "vcs",
      "url": "git@github.com:trycourier/courier-php.git"
    }
  ],
  "require": {
    "trycourier/courier": "^5.0"
  }
}
Then run composer install. Requires PHP 8.1+. Find the latest version on GitHub Releases.

​
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.
ResourceNamespaceDescription
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;
ScopePermission
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:
ResourceMethodUse 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

API Reference

Full REST API docs with request/response examples.

Send API

Learn about the Send endpoint, routing, and message options.

Quickstart

Send your first notification in under two minutes.

GitHub

Source code, issues, and changelog.