-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
143 additions
and
140 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,185 +1,188 @@ | ||
| # Courier SDK | ||
|
|
||
| Courier PHP SDK supporting: | ||
|
|
||
| - Send API | ||
| - Messages API | ||
| - Profiles API | ||
| - Preferences API | ||
| - Events API | ||
| - Brands API | ||
| - Lists API | ||
| - Notifications API | ||
| - Automations API | ||
| - Bulk API | ||
| - Audiences API | ||
| - Token Management API | ||
| - Audit Events API | ||
| - Tenants API | ||
| - Users API | ||
|
|
||
| ## Official Courier API docs | ||
|
|
||
| For a full description of request and response payloads and properties, please see the [official Courier API docs](https://docs.courier.com/reference). | ||
| # Courier PHP SDK | ||
|
|
||
| [](https://github.com/fern-api/fern) | ||
| [](https://packagist.org/packages/trycourier/courier) | ||
|
|
||
| The Courier PHP library provides convenient access to the Courier API from PHP. | ||
|
|
||
| ## Requirements | ||
|
|
||
| - PHP 7.2+ | ||
| - ext-json | ||
| Use of the Courier PHP SDK requires: | ||
| * PHP ^8.1 | ||
|
|
||
| ## Installation | ||
|
|
||
| This library uses [HTTPlug](https://github.com/php-http/httplug) as HTTP client. HTTPlug is an abstraction that allows | ||
| this library to support different HTTP Clients. Therefore, you need to provide it with an client and/or adapter for the HTTP | ||
| library you prefer. You can find all the available adapters [in Packagist](https://packagist.org/providers/php-http/client-implementation). | ||
| This documentation assumes you use the Guzzle Client, but you can replace it with any client that you prefer. | ||
| Use Composer to configure and install the Courier PHP SDK: | ||
|
|
||
| The recommended way to install courier-php is through Composer: | ||
|
|
||
| ```bash | ||
| composer require trycourier/courier guzzlehttp/guzzle | ||
| ```shell | ||
| composer require trycourier/courier | ||
| ``` | ||
|
|
||
| ## Configuration | ||
|
|
||
| Instantiate the Courier client class with your authorization token OR username and password. Providing just an authorization token will generate a "Bearer" authorization header, while providing a username and password will generate a "Basic" (base64-encoded) authorization header | ||
| ## Usage | ||
|
|
||
| ```php | ||
| $client = new CourierClient("base-url", "authorization-token", "username", "password"); | ||
| use Courier\CourierClient; | ||
| use Courier\Requests\SendMessageRequest; | ||
| use Courier\Send\Types\ContentMessage; | ||
| use Courier\Send\Types\ElementalContentSugar; | ||
| use Courier\Send\Types\UserRecipient; | ||
|
|
||
| $courier = new CourierClient(); | ||
| $response = $courier->send( | ||
| request: new SendMessageRequest([ | ||
| 'message' => new ContentMessage([ | ||
| 'to' => [ | ||
| new UserRecipient([ | ||
| 'email' => 'marty_mcfly@email.com', | ||
| 'data' => [ | ||
| 'name' => 'Marty', | ||
| ], | ||
| ]), | ||
| ], | ||
| 'content' => new ElementalContentSugar([ | ||
| 'title' => 'Back to the Future', | ||
| 'body' => 'Oh my {{name}}, we need 1.21 Gigawatts!', | ||
| ]), | ||
| ]), | ||
| ]) | ||
| ); | ||
| ``` | ||
|
|
||
| ### Options | ||
| ## Instantiation | ||
|
|
||
| Many methods allow the passing of optional data to the Courier endpoints. This data should be an associative array of key/value pairs. The exact options supported are dependent on the endpoint being called. Please refer to the official Courier documentation for more information. | ||
| To get started with the Courier SDK, instantiate the `CourierClient` class as follows: | ||
|
|
||
| ```php | ||
| $profile = [ | ||
| "firstname" => "Johnny", | ||
| "lastname" => "Appleseed", | ||
| "email" => "courier.pigeon@mail.com" | ||
| ]; | ||
| ``` | ||
|
|
||
| ## Methods | ||
|
|
||
| For a full description of request and response payloads and properties, please see the [official Courier API docs](https://docs.courier.com/reference). | ||
|
|
||
| ### Send API | ||
| use Courier\CourierClient; | ||
|
|
||
| - `sendNotification(string $event, string $recipient, string $brand = NULL, object $profile = NULL, object $data = NULL, object $preferences = NULL, object $override = NULL, string $idempotency_key = NULL): object` [(Send API)](https://www.courier.com/docs/reference/send/message/) | ||
| - `sendEnhancedNotification(object $message, string $idempotency_key = NULL): object` [(Send API)](https://www.courier.com/docs/reference/send/message/) | ||
| - `sendNotificationToList(string $event, string $list = NULL, string $pattern = NULL, string $brand = NULL, object $data = NULL, object $override = NULL, string $idempotency_key = NULL): object` [(Send list API)](https://www.courier.com/docs/reference/send/list/) | ||
|
|
||
| ### Messages API | ||
|
|
||
| - `cancelMessage(string $message_id): object` [[?]](https://www.courier.com/docs/reference/logs/cancel/) | ||
| - `getMessages(string $cursor = NULL, string $event = NULL, string $list = NULL, string $message_id = NULL, string $notification = NULL, string $recipient = NULL): object` [[?]](https://docs.courier.com/reference/messages-api#getmessages) | ||
| - `getMessage(string $message_id): object` [[?]](https://docs.courier.com/reference/messages-api#getmessagebyid) | ||
| - `getMessageHistory(string $message_id, string $type = NULL): object` [[?]](https://docs.courier.com/reference/messages-api#getmessagehistorybyid) | ||
|
|
||
| ### Lists API | ||
|
|
||
| - `getLists(string $cursor = NULL, string $pattern = NULL): object` [[?]](https://docs.courier.com/reference/lists-api#getlists) | ||
| - `getList(string $list_id): object` [[?]](https://docs.courier.com/reference/lists-api#getlist) | ||
| - `putList(string $list_id, string $name): object` [[?]](https://docs.courier.com/reference/lists-api#putlist) | ||
| - `deleteList(string $list_id): object` [[?]](https://docs.courier.com/reference/lists-api#deletelist) | ||
| - `restoreList(string $list_id): object` [[?]](https://docs.courier.com/reference/lists-api#putlistrestore) | ||
| - `getListSubscriptions(string $list_id, string $cursor = NULL): object` [[?]](https://docs.courier.com/reference/lists-api#getlistsubscriptions) | ||
| - `subscribeMultipleRecipientsToList(string $list_id, array $recipients): object` [[?]](https://docs.courier.com/reference/lists-api#createlistsubscriptions) | ||
| - `subscribeRecipientToList(string $list_id, string $recipient_id): object` [[?]](https://docs.courier.com/reference/lists-api#putlistsubscription) | ||
| - `deleteListSubscription(string $list_id, string $recipient_id): object` [[?]](https://docs.courier.com/reference/lists-api#deletelistsubscription) | ||
| $courier = new CourierClient("COURIER_AUTH_TOKEN"); | ||
| ``` | ||
|
|
||
| ### Brands API | ||
| Alternatively, you can omit the token when constructing the client. | ||
| In this case, the SDK will automatically read the token from the | ||
| `COURIER_AUTH_TOKEN` environment variable: | ||
|
|
||
| - `getBrands(string $cursor = NULL): object` [[?]](https://docs.courier.com/reference/brands-api#getbrands) | ||
| - `createBrand(string $id = NULL, string $name, object $settings, object $snippets = NULL, string $idempotency_key = NULL): object` [[?]](https://docs.courier.com/reference/brands-api#createbrand) | ||
| - `getBrand(string $brand_id): object` [[?]](https://docs.courier.com/reference/brands-api#getbrand) | ||
| - `replaceBrand(string $brand_id, string $name, object $settings, object $snippets = NULL): object` [[?]](https://docs.courier.com/reference/brands-api#replacebrand) | ||
| - `deleteBrand(string $brand_id): object` [[?]](https://docs.courier.com/reference/brands-api#deletebrand) | ||
| ```php | ||
| use Courier\CourierClient; | ||
|
|
||
| ### Events API | ||
| $courier = new CourierClient(); // Token is read from the COURIER_AUTH_TOKEN environment variable | ||
| ``` | ||
|
|
||
| - `getEvents(): object` [[?]](https://docs.courier.com/reference/events-api#getevents) | ||
| - `getEvent(string $event_id): object` [[?]](https://docs.courier.com/reference/events-api#geteventbyid) | ||
| - `putEvent(string $event_id, string $id, string $type): object` [[?]](https://docs.courier.com/reference/events-api#replaceeventbyid) | ||
| ### Environment and Custom URLs | ||
|
|
||
| ### Profiles API | ||
| This SDK allows you to configure different environments or custom URLs for API requests. | ||
| You can either use the predefined environments or specify your own custom URL. | ||
|
|
||
| - `getProfile(string $recipient_id): object` [[?]](https://docs.courier.com/reference/profiles-api#getprofilebyrecipientid) | ||
| - `upsertProfile(string $recipient_id, object $profile): object` [[?]](https://docs.courier.com/reference/profiles-api#mergeprofilebyrecipientid) | ||
| - `patchProfile(string $recipient_id, array $patch): object` [[?]](https://docs.courier.com/reference/profiles-api#patchprofilebyrecipientid) | ||
| - `replaceProfile(string $recipient_id, object $profile): object` [[?]](https://docs.courier.com/reference/profiles-api#replaceprofilebyrecipientid) | ||
| - `getProfileLists(string $recipient_id, string $cursor = NULL): object` [[?]](https://docs.courier.com/reference/profiles-api#getlistsforprofilebyrecipientid) | ||
| #### Environments | ||
|
|
||
| ### Preferences API | ||
| ```php | ||
| use Courier\CourierClient; | ||
| use Courier\Environments; | ||
|
|
||
| - `getPreferences(string $recipient_id, string $preferred_channel): object` [[?]](https://docs.courier.com/reference#get-preferencesrecipient_id) | ||
| - `updatePreferences(string $recipient_id, string $preferred_channel): object` [[?]](https://docs.courier.com/reference#put-preferencesrecipient_id) | ||
| $courier = new CourierClient(options: [ | ||
| 'baseUrl' => Environments::Production->value // Used by default | ||
| ]); | ||
| ``` | ||
|
|
||
| ### Notifications API | ||
| #### Custom URL | ||
|
|
||
| - `listNotifications(string $cursor = NULL): object` | ||
| - `getNotificationContent(string $id): object` | ||
| - `getNotificationDraftContent(string $id): object` | ||
| - `postNotificationVariations(string $id, array $blocks, array $channels = NULL): object` | ||
| - `postNotificationDraftVariations(string $id, array $blocks, array $channels = NULL): object` | ||
| - `getNotificationSubmissionChecks(string $id, string $submissionId): object` | ||
| - `putNotificationSubmissionChecks(string $id, string $submissionId, array $checks): object` | ||
| - `deleteNotificationSubmission(string $id, string $submissionId): object` | ||
| ```php | ||
| use Courier\CourierClient; | ||
|
|
||
| ### Automations API | ||
| $courier = new CourierClient(options: [ | ||
| 'baseUrl' => 'https://custom-staging.com' | ||
| ]); | ||
| ``` | ||
|
|
||
| - `invokeAutomation(object $automation, string $brand = NULL, string $template = NULL, string $recipient = NULL, object $data = NULL, object $profile = NULL): object` [[?]](https://docs.courier.com/reference/invokeautomation) | ||
| - `invokeAutomationFromTemplate(string $templateId, string $brand = NULL, object $data = NULL, object $profile = NULL, string $recipient = NULL, string $template = NULL): object` [[?]](https://docs.courier.com/reference/invokeautomationtemplate) | ||
| - `getAutomationRun(string $runId): object` | ||
| ## Enums | ||
|
|
||
| ### Bulk API | ||
| This SDK leverages PHP 8.1's first-class enums to improve type safety and usability. In order to maintain forward | ||
| compatibility with the API—where new enum values may be introduced in the future—we define enum properties as `string` | ||
| and use `value-of` annotations to specify the corresponding enum type. | ||
|
|
||
| - `createBulkJob(object $message): object` [(Create Bulk Job)](https://www.courier.com/docs/reference/bulk/create-job/) | ||
| - `ingestBulkJob(string $jobId, array $users): object` [(Ingest Bulk Job Users)](https://www.courier.com/docs/reference/bulk/ingest-users/) | ||
| - `runBulkJob(string $jobId): object` [(Run Bulk Job)](https://www.courier.com/docs/reference/bulk/run-job/) | ||
| - `getBulkJob(string $jobId): object` [(Get Bulk Job)](https://www.courier.com/docs/reference/bulk/get-job/) | ||
| - `getBulkJobUsers(string $jobId): object` [(Get Bulk Job Users)](https://www.courier.com/docs/reference/bulk/get-users/) | ||
| ### Example Usage | ||
| ```php | ||
| use Courier\Messages\Types\MessageDetails; | ||
| use Courier\Messages\Types\MessageStatus; | ||
|
|
||
| ### Audiences API | ||
| $messageDetails = new MessageDetails([ | ||
| 'status' => MessageStatus::Delivered->value, | ||
| ]); | ||
| ``` | ||
|
|
||
| - `putAudience(object $audience): object` [(Create Audience)](https://www.courier.com/docs/reference/audiences/put-audience/) | ||
| - `getAudience(string $audienceId): object` [(Get Audience)](https://www.courier.com/docs/reference/audiences/get-audience/) | ||
| - `getAudienceMembers(string $audienceId): object` [(List audience members)](https://www.courier.com/docs/reference/audiences/list-audience-members/) | ||
| - `getAudiences(): object` [(List audiences)](https://www.courier.com/docs/reference/audiences/list-audience-members/) | ||
| ### PHPDoc Annotations | ||
| ```php | ||
| /** | ||
| * @var value-of<MessageStatus> $status The current status of the message. | ||
| */ | ||
| ``` | ||
|
|
||
| ### Token Management API | ||
| ## Exception Handling | ||
|
|
||
| - `putUserTokens(string $user_id, array $tokens): object` [(Put User Tokens)](https://www.courier.com/docs/reference/token-management/put-tokens/) | ||
| - `putUserToken(string $user_id, array $token): object` [(Put User Token)](https://www.courier.com/docs/reference/token-management/put-token/) | ||
| - `patchUserToken(string $user_id, string $token, array $patch): object` [(Patch User Token)](https://www.courier.com/docs/reference/token-management/patch-token/) | ||
| - `getUserToken(string $user_id, string $token): object` [(Get User Token)](https://www.courier.com/docs/reference/token-management/get-token/) | ||
| - `getUserTokens(string $user_id): object` [(Get User Tokens)](https://www.courier.com/docs/reference/token-management/get-tokens/) | ||
| When the API returns a non-zero status code, (`4xx` or `5xx` response), a `CourierApiException` will be thrown: | ||
| ```php | ||
| use Courier\Exceptions\CourierApiException; | ||
| use Courier\Exceptions\CourierException; | ||
|
|
||
| try { | ||
| $courier->lists->get(...); | ||
| } catch (CourierApiException $e) { | ||
| echo 'Courier API Exception occurred: ' . $e->getMessage() . "\n"; | ||
| echo 'Status Code: ' . $e->getCode() . "\n"; | ||
| echo 'Response Body: ' . $e->getBody() . "\n"; | ||
| // Optionally, rethrow the exception or handle accordingly | ||
| } | ||
| ``` | ||
|
|
||
| ### Audit Events API | ||
| ## Advanced | ||
|
|
||
| - `getAuditEvent(string $audit_event_id): object` [(Get Audit Event)](https://www.courier.com/docs/reference/audit-events/by-id/) | ||
| - `listAuditEvents(string $cursor = NULL): object` [(List Audit Events)](https://www.courier.com/docs/reference/audit-events/list/) | ||
| ### Pagination | ||
|
|
||
| ### Accounts API (only on v1.12.0) | ||
| The SDK supports pagination for endpoints that return lists of items: | ||
|
|
||
| - `getAccount(): object` [(Get Account)](https://www.courier.com/docs/reference/accounts/get-account/) | ||
| - `listAccounts(string $cursor = NULL): object` [(List Accounts)](https://www.courier.com/docs/reference/accounts/get-accounts/) | ||
| - `putAccount(string $account_id, object $account): object` [(Put Account)](https://www.courier.com/docs/reference/accounts/create-replace/) | ||
| - `deleteAccount(string $account_id): object` [(Delete Account)](https://www.courier.com/docs/reference/accounts/delete-account/) | ||
| ```php | ||
| use Courier\Lists\Requests\GetAllListsRequest; | ||
|
|
||
| $items = $courier->lists->list( | ||
| request: new GetAllListsRequest([ | ||
| 'cursor' => 'abc123', | ||
| 'pageSize' => 10, | ||
| ]) | ||
| )->items; | ||
|
|
||
| foreach ($items as $list) { | ||
| echo "Found list with ID: " . $list->id . "\n"; | ||
| } | ||
| ``` | ||
|
|
||
| ### Tenants API (v2.0.0+) | ||
| ### Custom HTTP Client | ||
|
|
||
| - `getTenant(): object` [(Get Tenant)](https://www.courier.com/docs/reference/tenants/get-tenant/) | ||
| - `listTenants(string $cursor = NULL): object` [(List Tenants)](https://www.courier.com/docs/reference/tenants/get-tenants/) | ||
| - `putTenant(string $tenant_id, object $tenant): object` [(Put Tenant)](https://www.courier.com/docs/reference/tenants/create-replace/) | ||
| - `deleteTenant(string $tenant_id): object` [(Delete Tenant)](https://www.courier.com/docs/reference/tenants/delete-tenant/) | ||
| This SDK is built to work with any HTTP client that implements Guzzle's `ClientInterface`. By default, if no client | ||
| is provided, the SDK will use Guzzle's default HTTP client. However, you can pass your own client that adheres to | ||
| `ClientInterface`: | ||
|
|
||
| ### Users API | ||
| ```php | ||
| use GuzzleHttp\Client; | ||
| use Courier\CourierClient; | ||
|
|
||
| // Create a custom Guzzle client with specific configuration. | ||
| $client = new Client([ | ||
| 'timeout' => 5.0, | ||
| ]); | ||
|
|
||
| // Pass the custom client when creating an instance of the class. | ||
| $courier = new CourierClient(options: [ | ||
| 'client' => $client | ||
| ]); | ||
| ``` | ||
|
|
||
| - `putUser(): object` [(Put User)](https://www.courier.com/docs/reference/users/put-user/) | ||
| - `putUserTenants(): object` [(Put User Tenants)](https://www.courier.com/docs/reference/users/put-user-tenants/) | ||
| ## Contributing | ||
|
|
||
| ## Errors | ||
| While we value open-source contributions to this SDK, this library | ||
| is generated programmatically. Additions made directly to this library | ||
| would have to be moved over to our generation code, otherwise they would | ||
| be overwritten upon the next generated release. Feel free to open a PR as a | ||
| proof of concept, but know that we will not be able to merge it as-is. | ||
| We suggest opening an issue first to discuss with us! | ||
|
|
||
| All unsuccessful (non 2xx) responses will throw a `CourierRequestException`. The full response object is available via the `getResponse()` method. | ||
| On the other hand, contributions to the README are always very welcome! |