README

Laravel ConvertKit

A PHP/Laravel client for the ConvertKit REST API v3. Covers subscribers, forms, sequences, tags and broadcasts through a simple, typed API built on Laravel's Http client.

Features

Subscribers: list, get, update, unsubscribe
Forms: list, subscribe
Sequences: list, subscribe
Tags: list, subscribe, remove
Broadcasts: list, create
Picks the right credential per endpoint — api_secret where ConvertKit requires it, api_key for the public/subscribe endpoints
Throws ConvertKitException (with the original API error body) on any non-2xx response
Throws InvalidArgumentException before hitting the API when the required credential for an endpoint isn't configured

Installation

You can install the package via composer:

composer require jeffersongoncalves/laravel-convertkit

Publish the config file:

php artisan vendor:publish --tag=convertkit-config

Set your ConvertKit credentials in .env:

CONVERTKIT_API_KEY=your-api-key
CONVERTKIT_API_SECRET=your-api-secret

Both values are found under Settings > Advanced in your ConvertKit account. CONVERTKIT_API_KEY is enough for the public endpoints (forms, sequences and tags: list and subscribe); every other endpoint (subscribers, broadcasts, removing a tag) needs CONVERTKIT_API_SECRET.

Configuration

// config/convertkit.php
return [
    'api_key' => env('CONVERTKIT_API_KEY', ''),
    'api_secret' => env('CONVERTKIT_API_SECRET', ''),
    'base_url' => env('CONVERTKIT_BASE_URL', 'https://api.convertkit.com/v3'),
];

Usage

The package is resolved via the ConvertKit facade or by injecting JeffersonGoncalves\ConvertKit\ConvertKit. Each resource is exposed as a method returning a dedicated resource class.

Subscribers

Requires convertkit.api_secret:

use JeffersonGoncalves\ConvertKit\Facades\ConvertKit;

$subscribers = ConvertKit::subscribers()->list();

// Paginated
$subscribers = ConvertKit::subscribers()->list(page: 2);

$subscriber = ConvertKit::subscribers()->get(12345);

ConvertKit::subscribers()->update(12345, firstName: 'Jane', fields: ['plan' => 'pro']);

ConvertKit::subscribers()->unsubscribe('jane@example.com');

Forms

Uses convertkit.api_key:

$forms = ConvertKit::forms()->list();

ConvertKit::forms()->subscribe(
    formId: 123,
    email: 'jane@example.com',
    firstName: 'Jane',
    fields: ['plan' => 'pro'],
);

Sequences

Uses convertkit.api_key:

$sequences = ConvertKit::sequences()->list();

ConvertKit::sequences()->subscribe(123, 'jane@example.com');

Broadcasts

Requires convertkit.api_secret:

$broadcasts = ConvertKit::broadcasts()->list();

// Paginated
$broadcasts = ConvertKit::broadcasts()->list(page: 2);

ConvertKit::broadcasts()->create(
    subject: 'Hello World',
    content: '<p>Hi there!</p>',
    template: 'plain',
);

Error handling

Any non-2xx API response throws JeffersonGoncalves\ConvertKit\Exceptions\ConvertKitException, which exposes the decoded error body:

use JeffersonGoncalves\ConvertKit\Exceptions\ConvertKitException;

try {
    ConvertKit::subscribers()->get(999999);
} catch (ConvertKitException $e) {
    logger()->error($e->getMessage(), $e->errorBody());
}

Calling an api_secret-only method without convertkit.api_secret configured (or an api_key-only method without convertkit.api_key) throws InvalidArgumentException before any HTTP call is made.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

jeffersongoncalves / laravel-convertkit

Maintainers

Package info

Fund package maintenance!

Statistics

Security