Laravel ConvertKit

https://github.com/jeffersongoncalves/laravel-convertkit
Admin
Laravel ConvertKit is a PHP and Laravel client for the ConvertKit REST API v3, providing an...
Tokens:34,053
Snippets:276
Trust Score:9.8
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/jeffersongoncalves/laravel-convertkit/blob/main/README.md

Install the package using Composer.

```bash
composer require jeffersongoncalves/laravel-convertkit
```

--------------------------------

### Usage examples: facade, injection, and container resolution

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows how to resolve the ConvertKit singleton via facade, constructor injection, and the app() helper.

```php
use JeffersonGoncalves\ConvertKit\ConvertKit;
use JeffersonGoncalves\ConvertKit\Facades\ConvertKit as ConvertKitFacade;

// Facade resolves the singleton
$subscribers = ConvertKitFacade::subscribers()->list();

// Constructor/property injection works the same way
class NewsletterService
{
    public function __construct(private ConvertKit $convertkit) {}

    public function notify(string $email): void
    {
        $this->convertkit->tags()->subscribe(123, $email);
    }
}

// app(ConvertKit::class) always returns the same instance:
// app(ConvertKit::class) === app(ConvertKit::class) // true
```

--------------------------------

### Basic usage: fetch first page of subscribers

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Creates a ConvertKitClient with API key, secret, and base URL, then calls get('/subscribers', ['page' => 1]) to fetch the first page. The api_secret is automatically appended to the query string for GET requests.

```php
use JeffersonGoncalves\ConvertKit\ConvertKitClient;

$client = new ConvertKitClient('api-key', 'api-secret', 'https://api.convertkit.com/v3');

$page = $client->get('/subscribers', ['page' => 1]); // api_secret appended
```

--------------------------------

### Usage examples for list and subscribe

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows basic usage: listing sequences and subscribing with required or optional parameters. Uses the ConvertKit facade.

```php
use JeffersonGoncalves\ConvertKit\Facades\ConvertKit;

// Basic: list all sequences
$sequences = ConvertKit::sequences()->list();
$firstId = $sequences['courses'][0]['id'] ?? null;

// Subscribe with only the required parameters
ConvertKit::sequences()->subscribe(123, 'jane@example.com');

// Subscribe with custom fields
ConvertKit::sequences()->subscribe(
    sequenceId: 123,
    email: 'jane@example.com',
    firstName: 'Jane',
    fields: ['plan' => 'pro'],
);
```

--------------------------------

### Example usage of ConvertKit constructor

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows how to instantiate ConvertKit directly with named arguments and call the subscribers resource. In Laravel, the facade or DI resolves the singleton instead.

```php
use JeffersonGoncalves\ConvertKit\ConvertKit;

$convertkit = new ConvertKit(
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    baseUrl: 'https://api.convertkit.com/v3',
);

$subscribers = $convertkit->subscribers()->list();
```

--------------------------------

### Usage example: list forms and subscribe

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows basic usage of the Forms resource via the ConvertKit facade: listing forms and subscribing with all optional parameters.

```php
use JeffersonGoncalves\ConvertKit\Facades\ConvertKit;

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

// Subscribe with all optional parameters
$subscription = ConvertKit::forms()->subscribe(
    formId: 123,
    email: 'jane@example.com',
    firstName: 'Jane',
    fields: ['plan' => 'pro'],
);
```

--------------------------------

### get()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Performs an HTTP GET request to the ConvertKit API. The auth parameter is merged into the query string, and authentication uses either api_secret or api_key depending on the useSecret flag.

```APIDOC
## GET

### Description
Performs an HTTP GET request. The auth parameter is merged into the query string. When `$useSecret` is `true` the request is authenticated with `api_secret`; when `false`, with `api_key`.

### Method
GET

### Endpoint
`{base_url}/{path}`

### Parameters
#### Path Parameters
- `$path` (string) - Required - API path relative to the base URL, e.g. `/subscribers`.

#### Query Parameters
- `$query` (array<string, mixed>) - Optional - Query-string parameters merged with the auth parameter.
- `$useSecret` (bool) - Optional - `true` → send `api_secret`; `false` → send `api_key`.

### Response
#### Success Response (200)
- Returns decoded JSON response body as an array (never `null`; `[]` when the body is empty or not JSON). Array shape is the raw ConvertKit payload, unvalidated by this client.

#### Error Responses
- `InvalidArgumentException` — when the credential required for `$useSecret` is not configured.
- `ConvertKitException` — on any non-2xx response.
```

--------------------------------

### Error handling example for create()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows error handling when creating a broadcast. Catches ConvertKitException for validation failures on the request body and InvalidArgumentException when convertkit.api_secret is not configured.

```php
use JeffersonGoncalves\ConvertKit\Exceptions\ConvertKitException;

try {
    ConvertKit::broadcasts()->create(
        subject: 'Hello World',
        content: '<p>Hi there!</p>',
    );
} catch (ConvertKitException $e) {
    // e.g. validation failure on the request body
    logger()->error($e->getMessage(), $e->errorBody());
} catch (\InvalidArgumentException $e) {
    // convertkit.api_secret not configured
}
```

--------------------------------

### Usage example: list and create broadcasts

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows basic usage of the broadcasts resource via the ConvertKit facade. Lists broadcasts with optional pagination and creates a broadcast with the plain layout template. Requires convertkit.api_secret to be configured.

```php
use JeffersonGoncalves\ConvertKit\Facades\ConvertKit;

// Basic: list broadcasts, paginated
$broadcasts = ConvertKit::broadcasts()->list();
$page2 = ConvertKit::broadcasts()->list(page: 2);

// Create a broadcast with the "plain" layout template
$broadcast = ConvertKit::broadcasts()->create(
    subject: 'Hello World',
    content: '<p>Hi there!</p>',
    template: 'plain',
);
```

--------------------------------

### GET /sequences

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists all sequences. Requires an API key as a query parameter.

```APIDOC
## GET /sequences

### Description
Lists all sequences.

### Method
GET

### Endpoint
/sequences

### Parameters
#### Query Parameters
- **api_key** (string) - Required - API key for authentication

### Response
#### Success Response (200)
- **array** - Raw payload; sequences are under a `courses` key
```

--------------------------------

### Error handling example

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows how to catch ConvertKitException for non-2xx responses (e.g., 422 with error_message body) and InvalidArgumentException when api_key is not configured.

```php
use JeffersonGoncalves\ConvertKit\Exceptions\ConvertKitException;

try {
    ConvertKit::forms()->subscribe(123, 'not-an-email');
} catch (ConvertKitException $e) {
    // non-2xx: e.g. 422 with an "error_message" body
    logger()->error($e->getMessage(), $e->errorBody());
} catch (\InvalidArgumentException $e) {
    // convertkit.api_key not configured
}
```

--------------------------------

### GET /tags

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists all tags. Requires an API key as a query parameter.

```APIDOC
## GET /tags

### Description
Lists all tags.

### Method
GET

### Endpoint
/tags

### Parameters
#### Query Parameters
- **api_key** (string) - Required - API key for authentication

### Response
#### Success Response (200)
- **array** - Raw payload; tags are under a `tags` key
```

--------------------------------

### Subscribers Resource Usage

Source: https://github.com/jeffersongoncalves/laravel-convertkit/blob/main/README.md

Requires convertkit.api_secret. Shows listing (with pagination), getting, updating, and unsubscribing subscribers.

```php
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');
```

--------------------------------

### get()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Fetches a single subscriber by id. Performs a GET request to /subscribers/{id} with api_secret, interpolating the id directly into the path.

```APIDOC
## GET /subscribers/{id}

### Description
Fetches a single subscriber by id. Performs `GET /subscribers/{id}` with `api_secret`, interpolating `$id` directly into the path.

### Method
GET

### Endpoint
/subscribers/{id}

### Parameters
#### Path Parameters
- **id** (int|string) - Required - ConvertKit subscriber id (numeric id or string id).

### Response
#### Success Response (200)
- **subscriber** (object) - The subscriber object.

### Throws
- `InvalidArgumentException`
- `ConvertKitException` (e.g. HTTP 404 for a nonexistent subscriber)
```

--------------------------------

### GET /forms

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists all forms. Returns a raw payload with a `forms` key.

```APIDOC
## [GET] /forms

### Description
Lists all forms. Returns a raw payload with a `forms` key.

### Method
GET

### Endpoint
/forms

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Credential added automatically

### Response
#### Success Response (200)
- **array** - Raw payload; the README/source tests exercise a `forms` key
```

--------------------------------

### list()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists tags. Performs GET /tags with api_key on the query string. Takes no arguments.

```APIDOC
## GET /tags

### Description
Lists tags. Performs GET /tags with api_key on the query string. Takes no arguments.

### Method
GET

### Endpoint
/tags

### Parameters
#### Query Parameters
- `api_key` (string) - Required - Public API key for authentication.

### Response
#### Success Response (200)
- **body** (array) - Decoded JSON array, typically with a `tags` key. Shape not validated.

### Throws
- `InvalidArgumentException` (no `api_key`)
- `ConvertKitException` (non-2xx)
```

--------------------------------

### GET /broadcasts

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists all broadcasts. Requires an API secret as a query parameter.

```APIDOC
## GET /broadcasts

### Description
Lists all broadcasts.

### Method
GET

### Endpoint
/broadcasts

### Parameters
#### Query Parameters
- **page** (int) - Optional - Page number; omitted when `null`
- **api_secret** (string) - Required - API secret for authentication

### Response
#### Success Response (200)
- **array** - Raw payload; broadcasts are under a `broadcasts` key
```

--------------------------------

### Usage examples for list, subscribe, and remove

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows basic usage of the Tags resource via the ConvertKit facade: listing tags, subscribing an email with optional first name and custom fields, and removing a tag from a subscriber (which uses api_secret).

```php
use JeffersonGoncalves\ConvertKit\Facades\ConvertKit;

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

// Subscribe an email to a tag
ConvertKit::tags()->subscribe(123, 'jane@example.com');

// With first name and custom fields
ConvertKit::tags()->subscribe(
    tagId: 123,
    email: 'jane@example.com',
    firstName: 'Jane',
    fields: ['plan' => 'pro'],
);

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

--------------------------------

### ConvertKit::subscribers()->get()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Fetches a single subscriber by ID. Throws ConvertKitException on error (e.g., 404).

```APIDOC
## ConvertKit::subscribers()->get()

### Description
Fetches a single subscriber by ID. Throws ConvertKitException on error (e.g., 404).

### Method
get

### Parameters
#### Path Parameters
- **id** (int) - Required - Subscriber ID

### Request Example
```php
$subscriber = ConvertKit::subscribers()->get(12345);
```
```

--------------------------------

### Subscribers get() method signature

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Fetches a single subscriber by id via GET /subscribers/{id} with api_secret. The $id is interpolated directly into the path and can be a numeric or string id. Returns the decoded JSON array, typically with the subscriber under the 'subscriber' key. Throws InvalidArgumentException or ConvertKitException (e.g., HTTP 404 for nonexistent subscriber).

```php
public function get(int|string $id): array
```

--------------------------------

### GET /subscribers

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists subscribers with optional pagination. Returns a raw ConvertKit payload as an array.

```APIDOC
## [GET] /subscribers

### Description
Lists subscribers with optional pagination. Returns a raw ConvertKit payload as an array.

### Method
GET

### Endpoint
/subscribers

### Parameters
#### Query Parameters
- **page** (int) - Optional - Page number for pagination; omitted when `list()` is called without arguments
- **api_secret** (string) - Required - Credential added automatically

### Response
#### Success Response (200)
- **array** - Raw ConvertKit payload, not typed by this package
```

--------------------------------

### subscribers()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Returns a new Subscribers resource instance bound to the shared client. Subscribers::list(), get(), update() and unsubscribe() authenticate with api_secret.

```APIDOC
## subscribers()

### Description
Returns a new Subscribers resource instance bound to the shared client. Subscribers::list(), get(), update() and unsubscribe() authenticate with api_secret.

### Method
GET (implicit)

### Endpoint
N/A (resource accessor)

### Parameters
None

### Response
Returns a `Subscribers` resource instance.

### Example
```php
$subscribers = $convertkit->subscribers();
```
```

--------------------------------

### list()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists forms by performing a GET request to /forms with the api_key on the query string. Takes no arguments and returns the decoded JSON array from ConvertKit, typically containing a 'forms' key with a list of form objects.

```APIDOC
## list()

### Description
Lists forms. Performs `GET /forms` with `api_key` on the query string. Takes no arguments.

### Method
GET

### Endpoint
/forms

### Parameters
No parameters.

### Response
#### Success Response (200)
- **forms** (array) - List of form objects (shape not validated).

### Request Example
```php
$forms = ConvertKit::forms()->list();
```

### Response Example
(No explicit response example provided in source.)
```

--------------------------------

### send() protected method signature

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Protected method that builds the HTTP pipeline for all four verbs (get, post, put, delete). It constructs Http::baseUrl()->acceptJson(), appends query string for get/delete, sends JSON body for post/put, throws ConvertKitException on failure, and returns the JSON response as an array.

```php
/** @param array<string, mixed> $data */
protected function send(string $method, string $path, array $data): array
```

--------------------------------

### list()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists subscribers by performing a GET request to /subscribers with api_secret. The page query parameter is only included when non-null.

```APIDOC
## GET /subscribers

### Description
Lists subscribers. Performs `GET /subscribers` with `api_secret`. The `page` query parameter is only included when non-null, so `list()` without arguments sends no `page` parameter at all.

### Method
GET

### Endpoint
/subscribers

### Parameters
#### Query Parameters
- **page** (int) - Optional - Page number for paginated results; omitted from the query string when null.

### Response
#### Success Response (200)
- **subscribers** (array) - List of subscribers (raw ConvertKit response).

### Throws
- `InvalidArgumentException` (no `api_secret`)
- `ConvertKitException` (non-2xx)
```

--------------------------------

### list()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists broadcasts by performing a GET request to /broadcasts with api_secret. The page parameter is optional and only included when non-null.

```APIDOC
## [GET] /broadcasts

### Description
Lists broadcasts. Performs `GET /broadcasts` with `api_secret`. The `page` query parameter is only included when non-null.

### Method
GET

### Endpoint
/broadcasts

### Parameters
#### Query Parameters
- **page** (?int) - Optional - Page number for paginated results; omitted from the query string when `null`.

### Response
#### Success Response (200)
- **broadcasts** (array) - Typically contains the list of broadcasts. Shape not validated.

### Request Example
```php
$broadcasts = ConvertKit::broadcasts()->list();
$page2 = ConvertKit::broadcasts()->list(page: 2);
```
```

--------------------------------

### list() method signature

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists tags via GET /tags with api_key on the query string. Takes no arguments and returns a decoded JSON array (typically with a tags key). Throws InvalidArgumentException if no api_key and ConvertKitException on non-2xx responses.

```php
public function list(): array
```

--------------------------------

### list()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists sequences by performing a GET request to /sequences with the api_key on the query string. Returns the decoded JSON array from ConvertKit, which contains sequences under a 'courses' key.

```APIDOC
## GET /sequences

### Description
Lists sequences. Performs `GET /sequences` with `api_key` on the query string. Takes no arguments.

### Method
GET

### Endpoint
/sequences

### Parameters
#### Query Parameters
- **api_key** (string) - Required - The public key used for authentication.

### Response
#### Success Response (200)
- **courses** (array) - List of sequences (as returned by ConvertKit).

### Request Example
```php
$sequences = ConvertKit::sequences()->list();
$firstId = $sequences['courses'][0]['id'] ?? null;
```
```

--------------------------------

### GET /subscribers/{id}

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Retrieves a specific subscriber by ID. Returns a raw ConvertKit payload as an array.

```APIDOC
## [GET] /subscribers/{id}

### Description
Retrieves a specific subscriber by ID. Returns a raw ConvertKit payload as an array.

### Method
GET

### Endpoint
/subscribers/{id}

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Subscriber ID

#### Query Parameters
- **api_secret** (string) - Required - Credential added automatically

### Response
#### Success Response (200)
- **array** - Raw ConvertKit payload, not typed by this package
```

--------------------------------

### GET /subscribers

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Retrieves a list of subscribers from the ConvertKit API. This endpoint is called by the ConvertKitClient and requires an api_secret parameter.

```APIDOC
## [GET] /subscribers

### Description
Retrieves a list of subscribers from the ConvertKit API. This endpoint is called by the ConvertKitClient and requires an api_secret parameter.

### Method
GET

### Endpoint
/subscribers

### Parameters
#### Query Parameters
- **api_secret** (string) - Required - ConvertKit API secret for authentication.

### Response
#### Success Response (200)
- Returns the decoded JSON body as an untyped PHP array. Response schema is not validated by the package.
```

--------------------------------

### Catch ConvertKitException with error logging

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Example of catching ConvertKitException when calling an endpoint. Uses the exception's getMessage() and errorBody() to log details.

```php
use JeffersonGoncalves\ConvertKit\Exceptions\ConvertKitException;
use JeffersonGoncalves\ConvertKit\Facades\ConvertKit;

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

--------------------------------

### Catch InvalidArgumentException for missing ConvertKit credentials

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Use this try-catch to handle local configuration errors before any HTTP call. InvalidArgumentException indicates a missing api_secret or api_key, while ConvertKitException indicates the API rejected the request. The example calls ConvertKit::tags()->remove(123, 12345) when api_secret is empty.

```php
use JeffersonGoncalves\ConvertKit\Exceptions\ConvertKitException;

try {
    ConvertKit::tags()->remove(123, 12345);
} catch (\InvalidArgumentException $e) {
    // convertkit.api_secret is empty — fail fast before any HTTP call
    report($e);
} catch (ConvertKitException $e) {
    // the request went out and ConvertKit rejected it
    logger()->error($e->getMessage(), $e->errorBody());
}
```

--------------------------------

### Broadcasts list() method signature

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Lists broadcasts via GET /broadcasts with api_secret. The page query parameter is only included when non-null. Returns a decoded JSON array, typically with a broadcasts key. Throws InvalidArgumentException (no api_secret) or ConvertKitException (non-2xx).

```php
public function list(?int $page = null): array
```

--------------------------------

### Configuration File (config/convertkit.php)

Source: https://github.com/jeffersongoncalves/laravel-convertkit/blob/main/README.md

Default configuration for the package, reading credentials and base URL from environment variables.

```php
// 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'),
];
```

--------------------------------

### Constructor client instantiation

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Inside the constructor, a new ConvertKitClient is created with the provided credentials and base URL.

```php
$this->client = new ConvertKitClient($apiKey, $apiSecret, $baseUrl);
```

--------------------------------

### Run test suite with composer test

Source: https://github.com/jeffersongoncalves/laravel-convertkit/blob/main/README.md

Executes the project's test suite using Composer. Run this command from the project root to verify the package works as expected.

```bash
composer test
```

--------------------------------

### configurePackage() method

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Configures the package name and config file for the ConvertKit package.

```php
public function configurePackage(Package $package): void
```

```php
$package
    ->name('convertkit')
    ->hasConfigFile();
```

--------------------------------

### forms()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Returns a new Forms resource instance. Forms::list() and Forms::subscribe() authenticate with api_key.

```APIDOC
## forms()

### Description
Returns a new Forms resource instance. Forms::list() and Forms::subscribe() authenticate with api_key.

### Method
GET (implicit)

### Endpoint
N/A (resource accessor)

### Parameters
None

### Response
Returns a `Forms` resource instance.

### Example
```php
$forms = $convertkit->forms();
```
```

--------------------------------

### sequences()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Returns a new Sequences resource instance. Sequences::list() and Sequences::subscribe() authenticate with api_key.

```APIDOC
## sequences()

### Description
Returns a new Sequences resource instance. Sequences::list() and Sequences::subscribe() authenticate with api_key.

### Method
GET (implicit)

### Endpoint
N/A (resource accessor)

### Parameters
None

### Response
Returns a `Sequences` resource instance.

### Example
```php
$sequences = $convertkit->sequences();
```
```

--------------------------------

### Full source listing of ConvertKit class

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Complete class definition showing the client property, constructor, and placeholder comments for resource methods.

```php
class ConvertKit
{
    protected ConvertKitClient $client;

    public function __construct(?string $apiKey, ?string $apiSecret, string $baseUrl)
    {
        $this->client = new ConvertKitClient($apiKey, $apiSecret, $baseUrl);
    }

    // subscribers(), forms(), sequences(), tags(), broadcasts()
}
```

--------------------------------

### sequences() method signature

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Returns a new Sequences resource instance. Sequences::list() and Sequences::subscribe() authenticate with api_key.

```php
public function sequences(): Sequences
```

--------------------------------

### Exception handling with facade

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Demonstrates wrapping a facade call in a try-catch block to handle ConvertKitException, logging the error message and error body.

```php
use JeffersonGoncalves\ConvertKit\Exceptions\ConvertKitException;

try {
    ConvertKit::sequences()->subscribe(123, 'jane@example.com');
} catch (ConvertKitException $e) {
    logger()->error($e->getMessage(), $e->errorBody());
}
```

--------------------------------

### forms() method signature

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Returns a new Forms resource instance. Forms::list() and Forms::subscribe() authenticate with api_key.

```php
public function forms(): Forms
```

--------------------------------

### Resolving underlying instance

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows how to obtain the singleton ConvertKit instance via getFacadeRoot() for non-static use, with an assertion to verify the instance type.

```php
use JeffersonGoncalves\ConvertKit\ConvertKit;
use JeffersonGoncalves\ConvertKit\Facades\ConvertKit as ConvertKitFacade;

$manager = ConvertKitFacade::getFacadeRoot(); // the singleton ConvertKit instance
assert($manager instanceof ConvertKit);
```

--------------------------------

### Static access to resources

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows static calls to the facade for listing subscribers, forms, and broadcasts, plus chained resource calls for subscribing a tag and updating a subscriber.

```php
use JeffersonGoncalves\ConvertKit\Facades\ConvertKit;

// Static access to every resource
$subscribers = ConvertKit::subscribers()->list();
$forms = ConvertKit::forms()->list();
$broadcasts = ConvertKit::broadcasts()->list(page: 2);

// Chained resource calls
ConvertKit::tags()->subscribe(123, 'jane@example.com');
ConvertKit::subscribers()->update(12345, firstName: 'Jane');
```

--------------------------------

### Constructor-level configuration (non-Laravel)

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Direct instantiation of ConvertKit with named arguments, the only configuration path outside Laravel.

```php
use JeffersonGoncalves\ConvertKit\ConvertKit;

$convertkit = new ConvertKit(
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    baseUrl: 'https://api.convertkit.com/v3',
);
```

--------------------------------

### Basic subscriber operations with ConvertKit facade

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows how to list, paginate, fetch, update, and unsubscribe subscribers using the ConvertKit facade. The update method performs a partial update, sending only firstName and fields. The unsubscribe method takes an email address.

```php
use JeffersonGoncalves\ConvertKit\Facades\ConvertKit;

// Basic: list, paginate, fetch one
$subscribers = ConvertKit::subscribers()->list();
$page2 = ConvertKit::subscribers()->list(page: 2);

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

// Update: partial update — only firstName + fields are sent
$updated = ConvertKit::subscribers()->update(
    id: 12345,
    firstName: 'Jane',
    fields: ['plan' => 'pro'],
);

// Unsubscribe an email
ConvertKit::subscribers()->unsubscribe('jane@example.com');
```

--------------------------------

### Sequences Resource Usage

Source: https://github.com/jeffersongoncalves/laravel-convertkit/blob/main/README.md

Uses convertkit.api_key. Shows listing sequences and subscribing a subscriber to a sequence.

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

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

--------------------------------

### tags() method signature

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Returns a new Tags resource instance. Tags::list() and Tags::subscribe() authenticate with api_key; Tags::remove() authenticates with api_secret.

```php
public function tags(): Tags
```

--------------------------------

### new ConvertKit($apiKey, $apiSecret, $baseUrl)

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Constructor for the ConvertKit manager class. Creates a new ConvertKit instance with the provided API credentials and base URL, internally instantiating a ConvertKitClient.

```APIDOC
## Constructor

### Description
Creates a new ConvertKit instance, initializing the underlying ConvertKitClient with the given API key, API secret, and base URL.

### Signature
```php
public function __construct(?string $apiKey, ?string $apiSecret, string $baseUrl)
```

### Parameters
- **$apiKey** (?string) - Required - ConvertKit public API key (used by forms/sequences/tags list & subscribe endpoints). Pass `null` when not configured.
- **$apiSecret** (?string) - Required - ConvertKit API secret (used by subscribers, broadcasts, tag removal). Pass `null` when not configured.
- **$baseUrl** (string) - Required - ConvertKit REST API v3 base URL, e.g. `https://api.convertkit.com/v3`.

### Return Type
Returns a new `ConvertKit` instance.

### Example
```php
use JeffersonGoncalves\ConvertKit\ConvertKit;

$convertkit = new ConvertKit(
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    baseUrl: 'https://api.convertkit.com/v3',
);

$subscribers = $convertkit->subscribers()->list();
```
```

--------------------------------

### tags()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Returns a new Tags resource instance. Tags::list() and Tags::subscribe() authenticate with api_key; Tags::remove() authenticates with api_secret.

```APIDOC
## tags()

### Description
Returns a new Tags resource instance. Tags::list() and Tags::subscribe() authenticate with api_key; Tags::remove() authenticates with api_secret.

### Method
GET (implicit)

### Endpoint
N/A (resource accessor)

### Parameters
None

### Response
Returns a `Tags` resource instance.

### Example
```php
$tags = $convertkit->tags();
```
```

--------------------------------

### Constructor signature for ConvertKit

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Defines the constructor parameters: optional API key, optional API secret, and required base URL. The constructor creates a new ConvertKitClient internally.

```php
public function __construct(?string $apiKey, ?string $apiSecret, string $baseUrl)
```

--------------------------------

### Publish config file

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Artisan command to publish the config file into the application's config directory.

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

--------------------------------

### Tags Resource Usage

Source: https://github.com/jeffersongoncalves/laravel-convertkit/blob/main/README.md

list() and subscribe() use convertkit.api_key; remove() requires convertkit.api_secret. Shows listing tags, subscribing a tag, and removing a tag from a subscriber.

```php
$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() method signature

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Returns a new Broadcasts resource instance. Broadcasts::list() and Broadcasts::create() authenticate with api_secret.

```php
public function broadcasts(): Broadcasts
```

--------------------------------

### Forms: list

Source: https://github.com/jeffersongoncalves/laravel-convertkit/blob/main/README.md

Retrieves a list of forms. Uses the api_key credential.

```APIDOC
## Forms: list

### Description
Retrieves a list of forms. Uses the api_key credential.

### Method
GET

### Endpoint
ConvertKit::forms()->list()

### Response
#### Success Response (200)
- **forms** (array) - List of form objects

### Request Example
```php
$forms = ConvertKit::forms()->list();
```
```

--------------------------------

### broadcasts()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Returns a new Broadcasts resource instance. Broadcasts::list() and Broadcasts::create() authenticate with api_secret.

```APIDOC
## broadcasts()

### Description
Returns a new Broadcasts resource instance. Broadcasts::list() and Broadcasts::create() authenticate with api_secret.

### Method
GET (implicit)

### Endpoint
N/A (resource accessor)

### Parameters
None

### Response
Returns a `Broadcasts` resource instance.

### Example
```php
$broadcasts = $convertkit->broadcasts();
```
```

--------------------------------

### packageRegistered() method

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Registers the ConvertKit singleton with the application container, reading credentials from config.

```php
public function packageRegistered(): void
```

```php
$this->app->singleton(ConvertKit::class, function () {
    $apiKey = config('convertkit.api_key');
    $apiSecret = config('convertkit.api_secret');

    return new ConvertKit(
        $apiKey !== null && $apiKey !== '' ? (string) $apiKey : null,
        $apiSecret !== null && $apiSecret !== '' ? (string) $apiSecret : null,
        (string) config('convertkit.base_url', 'https://api.convertkit.com/v3'),
    );
});
```

--------------------------------

### Tags: list

Source: https://github.com/jeffersongoncalves/laravel-convertkit/blob/main/README.md

Retrieves a list of tags. Uses the api_key credential.

```APIDOC
## Tags: list

### Description
Retrieves a list of tags. Uses the api_key credential.

### Method
GET

### Endpoint
ConvertKit::tags()->list()

### Response
#### Success Response (200)
- **tags** (array) - List of tag objects

### Request Example
```php
$tags = ConvertKit::tags()->list();
```
```

--------------------------------

### Singleton resolution in ConvertKitServiceProvider

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Resolves the ConvertKit singleton, normalizing empty credentials to null and applying a defensive base_url fallback.

```php
$this->app->singleton(ConvertKit::class, function () {
    $apiKey = config('convertkit.api_key');
    $apiSecret = config('convertkit.api_secret');

    return new ConvertKit(
        $apiKey !== null && $apiKey !== '' ? (string) $apiKey : null,
        $apiSecret !== null && $apiSecret !== '' ? (string) $apiSecret : null,
        (string) config('convertkit.base_url', 'https://api.convertkit.com/v3'),
    );
});
```

--------------------------------

### subscribers() method signature

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Returns a new Subscribers resource instance bound to the shared client. Subscribers methods authenticate with api_secret.

```php
public function subscribers(): Subscribers
```

--------------------------------

### Sequences: list

Source: https://github.com/jeffersongoncalves/laravel-convertkit/blob/main/README.md

Retrieves a list of sequences. Uses the api_key credential.

```APIDOC
## Sequences: list

### Description
Retrieves a list of sequences. Uses the api_key credential.

### Method
GET

### Endpoint
ConvertKit::sequences()->list()

### Response
#### Success Response (200)
- **sequences** (array) - List of sequence objects

### Request Example
```php
$sequences = ConvertKit::sequences()->list();
```
```

--------------------------------

### ConvertKitClient::__construct

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Creates a new ConvertKitClient instance with the provided API key, API secret, and base URL. The client is a thin wrapper around Laravel's HTTP client for the ConvertKit REST API v3.

```APIDOC
## ConvertKitClient::__construct

### Description
Creates a new ConvertKitClient instance with the provided API key, API secret, and base URL. The client is a thin wrapper around Laravel's HTTP client for the ConvertKit REST API v3.

### Signature
```php
public function __construct(
    protected ?string $apiKey,
    protected ?string $apiSecret,
    protected string $baseUrl,
) {}
```

### Parameters
- **$apiKey** (?string) - Required - ConvertKit public API key, sent as `api_key` when `useSecret` is `false`.
- **$apiSecret** (?string) - Required - ConvertKit API secret, sent as `api_secret` when `useSecret` is `true`.
- **$baseUrl** (string) - Required - Base URL all paths are resolved against (via `Http::baseUrl()`).
```

--------------------------------

### Config file: config/convertkit.php

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Full source of the configuration file. Defines api_key, api_secret, and base_url options, each driven by environment variables with defaults.

```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'),

];
```

--------------------------------

### post()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Performs an HTTP POST request with a JSON body. The auth parameter is merged into the JSON body, and authentication uses either api_secret or api_key depending on the useSecret flag.

```APIDOC
## POST

### Description
Performs an HTTP POST with a JSON body (`Http::asJson()`). The auth parameter is merged into the JSON body.

### Method
POST

### Endpoint
`{base_url}/{path}`

### Parameters
#### Path Parameters
- `$path` (string) - Required - API path relative to the base URL.

#### Request Body
- `$body` (array<string, mixed>|null) - Optional - JSON body; auth parameter is merged in.
- `$useSecret` (bool) - Optional - `true` → `api_secret`; `false` → `api_key`.

### Response
#### Success Response (200)
- Returns decoded JSON body as an array.

#### Error Responses
- `InvalidArgumentException` — when the credential required for `$useSecret` is not configured.
- `ConvertKitException` — on any non-2xx response.
```

--------------------------------

### getFacadeAccessor() method

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Returns the container binding name (FQCN) for the ConvertKit manager singleton. Laravel's facade machinery resolves this binding and forwards static calls to the underlying instance.

```php
protected static function getFacadeAccessor(): string
{
    return \JeffersonGoncalves\ConvertKit\ConvertKit::class;
}
```

--------------------------------

### composer.json extra.laravel.providers and aliases

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Auto-discovery configuration for the Laravel service provider and facade alias.

```json
"extra": {
    "laravel": {
        "providers": [
            "JeffersonGoncalves\\ConvertKit\\ConvertKitServiceProvider"
        ],
        "aliases": {
            "ConvertKit": "JeffersonGoncalves\\ConvertKit\\Facades\\ConvertKit"
        }
    }
}
```

--------------------------------

### Broadcasts Resource Usage

Source: https://github.com/jeffersongoncalves/laravel-convertkit/blob/main/README.md

Requires convertkit.api_secret. Shows listing broadcasts (with pagination) and creating a broadcast.

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

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

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

--------------------------------

### put()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Performs an HTTP PUT request with a JSON body. Identical to post() but issues an HTTP PUT.

```APIDOC
## PUT

### Description
Identical to `post()` but issues an HTTP PUT with a JSON body.

### Method
PUT

### Endpoint
`{base_url}/{path}`

### Parameters
#### Path Parameters
- `$path` (string) - Required - API path relative to the base URL.

#### Request Body
- `$body` (array<string, mixed>|null) - Optional - JSON body; auth parameter is merged in.
- `$useSecret` (bool) - Optional - `true` → `api_secret`; `false` → `api_key`.

### Response
#### Success Response (200)
- Returns decoded JSON body as an array.

#### Error Responses
- `InvalidArgumentException` — when the credential required for `$useSecret` is not configured.
- `ConvertKitException` — on any non-2xx response.
```

--------------------------------

### Error handling for subscribe

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows how to catch ConvertKitException and InvalidArgumentException when subscribing. InvalidArgumentException is thrown before the HTTP call if api_key is not configured.

```php
use JeffersonGoncalves\ConvertKit\Exceptions\ConvertKitException;

try {
    ConvertKit::sequences()->subscribe(123, 'jane@example.com');
} catch (ConvertKitException $e) {
    logger()->error($e->getMessage(), $e->errorBody());
} catch (\InvalidArgumentException $e) {
    // convertkit.api_key not configured — thrown before the HTTP call
}
```

--------------------------------

### Set credentials in .env

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Environment variables for API credentials. CONVERTKIT_API_KEY is sufficient for public endpoints; CONVERTKIT_API_SECRET is required for subscribers, broadcasts, and tag removal.

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

--------------------------------

### subscribe() method signature

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Subscribes an email to a sequence via POST /sequences/{sequenceId}/subscribe. Accepts optional first name and custom fields. Null values are filtered out; fields are sent only when non-empty. Throws InvalidArgumentException and ConvertKitException.

```php
/**
 * @param array<string, mixed> $fields
 */
public function subscribe(int|string $sequenceId, string $email, ?string $firstName = null, array $fields = []): array
```

--------------------------------

### create()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Creates a broadcast by performing a POST request to /broadcasts with api_secret merged into the JSON body. The template parameter maps to ConvertKit's email_layout_template body key and is omitted when null.

```APIDOC
## [POST] /broadcasts

### Description
Creates a broadcast. Performs `POST /broadcasts` with `api_secret` merged into the JSON body. The `template` parameter maps to ConvertKit's `email_layout_template` body key; it is omitted when `null`.

### Method
POST

### Endpoint
/broadcasts

### Parameters
#### Request Body
- **subject** (string) - Required - Broadcast subject line, sent as `subject`.
- **content** (string) - Required - Broadcast body content (HTML is accepted per README examples), sent as `content`.
- **email_layout_template** (?string) - Optional - ConvertKit email layout template, e.g. `plain`, sent as `email_layout_template`; omitted when `null`.

### Response
#### Success Response (200)
- **broadcast** (object) - Typically contains the created broadcast.

### Request Example
```php
$broadcast = ConvertKit::broadcasts()->create(
    subject: 'Hello World',
    content: '<p>Hi there!</p>',
    template: 'plain',
);
```
```

--------------------------------

### subscribe()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Subscribes an email to a sequence by performing a POST request to /sequences/{sequenceId}/subscribe with api_key merged into the JSON body. Null values are filtered out and the fields array is sent only when non-empty.

```APIDOC
## POST /sequences/{sequenceId}/subscribe

### Description
Subscribes an email to a sequence. Performs `POST /sequences/{sequenceId}/subscribe` with `api_key` merged into the JSON body. `null` values are filtered out and the `fields` array is sent only when non-empty.

### Method
POST

### Endpoint
/sequences/{sequenceId}/subscribe

### Parameters
#### Path Parameters
- **sequenceId** (int|string) - Required - Sequence id to subscribe to, interpolated into the path.

#### Request Body
- **api_key** (string) - Required - The public key used for authentication.
- **email** (string) - Required - Email address to subscribe.
- **firstName** (string|null) - Optional - Subscriber's first name; omitted when null.
- **fields** (array<string, mixed>) - Optional - Custom field values keyed by field name; omitted when empty.

### Response
#### Success Response (200)
- **subscription** (object) - The subscription details (as returned by ConvertKit).

### Request Example
```php
// Subscribe with only the required parameters
ConvertKit::sequences()->subscribe(123, 'jane@example.com');

// Subscribe with custom fields
ConvertKit::sequences()->subscribe(
    sequenceId: 123,
    email: 'jane@example.com',
    firstName: 'Jane',
    fields: ['plan' => 'pro'],
);
```
```

--------------------------------

### Error handling for subscriber operations with ConvertKitException

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows how to catch ConvertKitException for API errors, where getCode() returns the HTTP status (e.g., 404) and errorBody() returns the API body. Also catches InvalidArgumentException, which is thrown before any HTTP call when convertkit.api_secret is empty.

```php
use JeffersonGoncalves\ConvertKit\Exceptions\ConvertKitException;

try {
    ConvertKit::subscribers()->get(999999);
} catch (ConvertKitException $e) {
    // $e->getCode() is the HTTP status (404); $e->errorBody() is the API body
    logger()->error($e->getMessage(), $e->errorBody());
} catch (\InvalidArgumentException $e) {
    // fired before any HTTP call when convertkit.api_secret is empty
}
```

--------------------------------

### ConvertKitException static factory: fromResponse()

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Builds an exception from an Illuminate\Http\Client\Response that already failed. Message resolution order: $body['message'], then $body['error_message'], then generic fallback. Exception code is the HTTP status.

```php
public static function fromResponse(Response $response): self
```

--------------------------------

### Error handling: missing credential and failing request

Source: https://github.com/jeffersongoncalves/laravel-convertkit

Shows how to handle InvalidArgumentException when the secret is not configured (thrown before any HTTP call) and ConvertKitException for a failing request (e.g., subscriber not found). Uses logger()->error() with the exception message and errorBody().

```php
use JeffersonGoncalves\ConvertKit\ConvertKitClient;
use JeffersonGoncalves\ConvertKit\Exceptions\ConvertKitException;

$client = new ConvertKitClient(null, null, 'https://api.convertkit.com/v3');

try {
    $client->get('/subscribers'); // throws InvalidArgumentException: secret not configured
} catch (\InvalidArgumentException $e) {
    // handle before any HTTP call
}

try {
    $client->get('/subscribers/999999');
} catch (ConvertKitException $e) {
    logger()->error($e->getMessage(), $e->errorBody());
}
```
Tokens:
Raw