Download the PHP package upanupstudios/upaknee-php-client without Composer

Upaknee PHP Client

A PHP client for the Upaknee (Cloud Messaging Stack Enterprise) REST API.

The client is scoped to what the Upaknee Mailout Drupal module needs: checking a token, reading the list's sending identity, resolving the recipients of a newsletter, and submitting a mailing. It is not a full binding of the API.

Requirements

• PHP 8.1+
• A PSR-18 HTTP client and PSR-17 factories. The library does not depend on a specific implementation — install any one you like, for example Guzzle:

Authentication

The API uses HTTP Basic authentication. Your token (a 32-character alphanumeric string) and an optional security password are obtained from the Settings tab of Campaign Manager.

Usage

The HTTP client and factories are auto-discovered from whatever PSR-18/PSR-17 implementation you have installed:

Lists

A token is scoped to one contact list, which carries the account's sending identity.

Note: the sending identity is read-only. There is no route for changing a list, so the from name and from address are configured in Campaign Manager. The API models no reply-to address at all — it appears nowhere in the documented endpoints.

Newsletters

A newsletter is the subscription list a subscriber opts in to, and is the closest thing the API offers to a "group" of recipients.

subscriptions() always returns a list, including when the newsletter has exactly one subscriber — XML cannot distinguish a one-element collection from a single object, so the client normalizes it.

Note: the API publishes no route for listing the newsletters on an account — only the total count, and the subscriptions of a newsletter whose ID you already hold. Newsletter IDs have to come from Campaign Manager rather than from discovery. status, limit and offset are documented on the sibling /subscribers/{profile-id}/subscriptions route but not on this one; they are passed through for servers that honour them, and profileIds() re-filters on status client-side so an ignored filter cannot cause an unsubscribed contact to be mailed.

Mailings

Upaknee sends against a trigger — a message template configured in Campaign Manager. The API does not author content: it submits the recipients to mail and the merge-tag values to interpolate into the template. Anything variable in the message (subject line, body HTML) must be exposed as a merge tag on the trigger.

Merge-tag values named in the serializer's CDATA list (body by default) are emitted as CDATA, so HTML survives intact. Pass a different list to XmlSerializer if your trigger names its HTML tag something else:

$scheduledFor accepts the three formats the API documents:

Bring your own HTTP client

For full control (custom middleware, timeouts, testing), construct the transport yourself:

Error handling

Successful responses are decoded from XML into associative arrays. Errors throw typed exceptions that all implement Upanupstudios\Upaknee\Php\Client\Exception\ExceptionInterface:

Tests

License

MIT