Skip to content

docs: sync README from mintlify-docs #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xehl merged 1 commit into from
Feb 20, 2026
Merged

docs: sync README from mintlify-docs #70

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 19 additions & 157 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,13 @@
<!-- AUTO-GENERATED-OVERVIEW:START — Do not edit this section. It is synced from mintlify-docs. -->
# Courier PHP API library
# Courier PHP SDK

The Courier PHP library provides convenient access to the Courier REST API from any PHP 8.1.0+ application.
> **Beta**: The PHP SDK is in beta. APIs may change between releases. [Share feedback or report issues on GitHub.](https://github.com/trycourier/courier-php/issues/new)

It is generated with [Stainless](https://www.stainless.com/).

## Documentation

The REST API documentation can be found on [www.courier.com](https://www.courier.com/docs).
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.

## Installation

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

<!-- x-release-please-start-version -->
Add to your `composer.json`:

```json
{
Expand All @@ -29,169 +23,37 @@ To use this package, install via Composer by adding the following to your applic
}
```

<!-- x-release-please-end -->
Then run `composer install`.

## Usage

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

```php
<?php

use Courier\Client;
use CourierClient;

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

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

var_dump($response->requestId);
```

### Value Objects

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')`.

### Handling errors

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
<?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'],
'to' => ['email' => 'you@example.com'],
'content' => [
'title' => 'Hello from Courier!',
'body' => 'Your first notification, sent with the PHP SDK.',
],
);
} 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:

| Cause | Error Type |
| ---------------- | ------------------------------ |
| HTTP 400 | `BadRequestException` |
| HTTP 401 | `AuthenticationException` |
| HTTP 403 | `PermissionDeniedException` |
| HTTP 404 | `NotFoundException` |
| HTTP 409 | `ConflictException` |
| HTTP 422 | `UnprocessableEntityException` |
| HTTP 429 | `RateLimitException` |
| HTTP >= 500 | `InternalServerException` |
| Other HTTP error | `APIStatusException` |
| Timeout | `APITimeoutException` |
| Network error | `APIConnectionException` |

### Retries

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
<?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],
);
```

## Advanced concepts

### Making custom or undocumented requests

#### Undocumented properties

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
<?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'],
],
);
```

#### Undocumented request params

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.

#### Undocumented endpoints

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
<?php

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

## Versioning
The client reads your API key from the constructor argument. Set `COURIER_API_KEY` in your environment and pass it with `getenv('COURIER_API_KEY')`.

This package follows [SemVer](https://semver.org/spec/v2.0.0.html) 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.

## Requirements

PHP 8.1.0 or higher.
## Documentation

## Contributing
Full documentation: **[courier.com/docs/sdk-libraries/php](https://www.courier.com/docs/sdk-libraries/php/)**

See [the contributing documentation](https://github.com/trycourier/courier-php/tree/main/CONTRIBUTING.md).
- [Quickstart](https://www.courier.com/docs/getting-started/quickstart/)
- [Send API](https://www.courier.com/docs/platform/sending/send-message/)
- [API Reference](https://www.courier.com/docs/reference/get-started/)
<!-- AUTO-GENERATED-OVERVIEW:END -->