README

Introduction

This is an API Client for the ConvertKit mailing list service for PHP versions 8.0 and up

There are several clients available on Packagist, but the main motivation here is being agnostic to the HTTP client in use.

The client uses PSR17 and 18 standards, so you can bring your own preferred libs.

Implemented Features

Retrieve form by id
Subscribe to a form (Custom fields are not yet available)
List and find tags
Create Tags
List custom fields
Crud for custom fields
Fetch form subscriber
Other Crud operations for subscribers
Tagging subscribers post subscribe.
Stuff regarding webhooks and purchases…

Roadmap

It'd be nice to work up the rest of the available features in the API, but it probably won't happen very quickly, I'm more likely to work on different implementations first to firm up the spec there so that stable releases can be made. Shipping a caching client using a psr cache pool would be handy for those aspects of the API that rarely change. It would also be quite trivial to implement.

Installation

Composer is the only supported installation method…

As previously mentioned, you'll need a PSR-18 HTTP Client first and also PSR-7 and PSR-17 implementations. For example:

composer require php-http/curl-client
composer require laminas/laminas-diactoros

You'll then be able to install this with:

composer require list-interop/convertkit-client

Usage

Docs are admittedly thin on the ground.

The lib ships with a PSR11 factory that you can integrate with your container of choice. It falls back to discovery for whatever PSR-7/17/18 stuff that you have installed.

Ultimately, you'll need API Keys to get going, and assuming you can provide the Client constructor with its required constructor dependencies, you'll be able to start issuing commands and getting results:

Add a subscriber…

use ListInterop\ConvertKit\Client;
use ListInterop\ConvertKit\Exception\ApiError;
use ListInterop\ConvertKit\Exception\ConvertKitError;
use ListInterop\ConvertKit\Exception\RequestFailure;

assert($client instanceof Client);

$formId = 123; // Retrieve this from the dashboard or by inspecting the forms returned by the api.

try {
    $client->subscribeToForm($formId, 'me@example.com', 'Fred', ['tag 1', 'tag 2']);
} catch (RequestFailure $error) {
    // Network error - can't reach ConvertKit
} catch (ApiError $error) {
    // Something was wrong with the values provided, or your API key was wonky
    // i.e. The API rejected your request
} catch (ConvertKitError $error) {
    // Generic Error, Assertion failed etc.
    // All exceptions implement this interface, Providing an invalid email address will get you here.
}

You should find that exceptions are consistent and meaningful, but for now, to find out what those are, you'll need to look at the source.

Contributions

Are most welcome, but please make sure that pull requests include relevant tests. There's a handy composer script you can run locally:

composer check

… which will check coding standards, run psalm and phpunit in order.

License

MIT Licensed.

list-interop / convertkit-client

Maintainers

Details