#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');

#Tags

list() and subscribe() use convertkit.api_key; remove() requires convertkit.api_secret:

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

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

// Remove tag 123 from subscriber 12345
ConvertKit::tags()->remove(tagId: 123, subscriberId: 12345);

#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

• Jefferson Gonçalves
• All Contributors

#License

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