The Courier PHP library provides convenient access to the Courier REST API from any PHP 8.1.0+ application.

It is generated with Stainless.

The REST API documentation can be found on www.courier.com.

To use this package, install via Composer by adding the following to your application's composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "git@github.com:trycourier/courier-php.git"
    }
  ],
  "require": {
    "trycourier/courier": "dev-main"
  }
}

This library uses named parameters to specify optional arguments. Parameters with a default value must be set by name.

<?php

use Courier\Client;

$client = new Client(apiKey: getenv('COURIER_API_KEY') ?: 'My API Key');

$response = $client->send->message(
  message: [
    'to' => ['userID' => 'your_user_id'],
    'template' => 'your_template_id',
    'data' => ['foo' => 'bar'],
  ],
);

var_dump($response->requestId);

It is recommended to use the static with constructor AudienceFilter::with(operator: 'MEMBER_OF', ...) and named parameters to initialize value objects.

However, builders are also provided (new AudienceFilter)->withOperator('MEMBER_OF').

When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of Courier\Core\Exceptions\APIException will be thrown:

<?php

use Courier\Core\Exceptions\APIConnectionException;
use Courier\Core\Exceptions\RateLimitException;
use Courier\Core\Exceptions\APIStatusException;

try {
  $response = $client->send->message(
    message: [
      'to' => ['userID' => 'your_user_id'],
      'template' => 'your_template_id',
      'data' => ['foo' => 'bar'],
    ],
  );
} catch (APIConnectionException $e) {
  echo "The server could not be reached", PHP_EOL;
  var_dump($e->getPrevious());
} catch (RateLimitException $e) {
  echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
} catch (APIStatusException $e) {
  echo "Another non-200-range status code was received", PHP_EOL;
  echo $e->getMessage();
}

Error codes are as follows:

Certain errors will be automatically retried 2 times by default, with a short exponential backoff.

Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.

You can use the maxRetries option to configure or disable this:

<?php

use Courier\Client;

// Configure the default for all requests:
$client = new Client(requestOptions: ['maxRetries' => 0]);

// Or, configure per-request:
$result = $client->send->message(
  message: [
    'to' => ['userID' => 'your_user_id'],
    'template' => 'your_template_id',
    'data' => ['foo' => 'bar'],
  ],
  requestOptions: ['maxRetries' => 5],
);

You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:

Note: the extra* parameters of the same name overrides the documented parameters.

<?php

$response = $client->send->message(
  message: [
    'to' => ['userID' => 'your_user_id'],
    'template' => 'your_template_id',
    'data' => ['foo' => 'bar'],
  ],
  requestOptions: [
    'extraQueryParams' => ['my_query_parameter' => 'value'],
    'extraBodyParams' => ['my_body_parameter' => 'value'],
    'extraHeaders' => ['my-header' => 'value'],
  ],
);

If you want to explicitly send an extra param, you can do so with the extra_query, extra_body, and extra_headers under the request_options: parameter when making a request, as seen in the examples above.

To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using client.request, like so:

<?php

$response = $client->request(
  method: "post",
  path: '/undocumented/endpoint',
  query: ['dog' => 'woof'],
  headers: ['useful-header' => 'interesting-value'],
  body: ['hello' => 'world']
);

This package follows SemVer conventions. As the library is in initial development and has a major version of 0, APIs may change at any time.

This package considers improvements to the (non-runtime) PHPDoc type definitions to be non-breaking changes.

PHP 8.1.0 or higher.

See the contributing documentation.