README

PHP wrapper for the ActiveCampaign API v3. Returns typed models, retries on rate limits, and handles pagination.

This is an unofficial SDK. Built and maintained by relyz AG.

Note: This SDK targets ActiveCampaign API v3 exclusively. The API version prefix (/api/3/) is not configurable.

Requirements

• PHP 8.1+
• Guzzle 7.0+

Installation

composer require relyz/active-campaign-sdk

Usage

$ac = new ActiveCampaign\Client(
    url: 'https://youraccountname.api-us1.com',
    apiKey: 'your-api-key',
);

Or set the ACTIVE_CAMPAIGN_API_URL and ACTIVE_CAMPAIGN_API_KEY environment variables (via .env, Docker, export, etc.) and omit the arguments:

$ac = new ActiveCampaign\Client();

Create a contact

$contact = $ac->contacts()->create(
    email: 'jane@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
);

// $contact is a typed Contact model
echo $contact->id;

For most methods there are simplified versions (like the one above) that should cover most use cases. In case some parameters are missing from the simplified version, there is always a *Raw method available, to which you can just pass an array with all the parameters that the API endpoints accepts.

$contact = $ac->contacts()->createRaw([
    'email' => 'jane@example.com',
    'firstName' => 'Jane',
    'lastName' => 'Doe',
]);

Error Handling

The SDK throws typed exceptions for different HTTP error scenarios:

use ActiveCampaign\Exceptions\AuthenticationException;
use ActiveCampaign\Exceptions\NotFoundException;
use ActiveCampaign\Exceptions\ValidationException;
use ActiveCampaign\Exceptions\RateLimitException;
use ActiveCampaign\Exceptions\ActiveCampaignException;

try {
    $contact = $ac->contacts()->get(999);
} catch (NotFoundException $e) {
    // 404 — resource not found
    echo $e->getMessage();
    print_r($e->getResponseBody()); // parsed JSON from API
} catch (ValidationException $e) {
    // 422 — validation failed
    print_r($e->getResponseBody()['errors'] ?? []);
} catch (AuthenticationException $e) {
    // 401/403 — invalid or missing API key
} catch (RateLimitException $e) {
    // 429 — rate limit exceeded (after retries exhausted)
} catch (ActiveCampaignException $e) {
    // All other API errors (5xx, etc.)
}

All exceptions extend ActiveCampaignException, which extends RuntimeException. Every exception provides getResponseBody() returning the parsed API response as an array.

Pagination

Basic Listing

$result = $ac->contacts()->list(['limit' => 50, 'offset' => 0]);

foreach ($result->data as $contact) {
    echo $contact->email;
}

echo $result->meta->total;  // Total records available

Lazy Pagination

Use paginate() for automatic lazy-loading across all pages:

foreach ($ac->contacts()->paginate(limit: 100) as $contact) {
    echo $contact->email; // Fetches next page automatically
}

Rate Limiting

The SDK automatically retries requests that receive a 429 Too Many Requests response, respecting the Retry-After header. By default, it retries up to 3 times using sleep().

To customize retry behavior (e.g., for non-blocking strategies or logging):

$ac = new Client(
    maxRetries: 5,
);

For advanced control, provide a custom retry callback via the HTTP client:

use ActiveCampaign\Http\Client as HttpClient;

$httpClient = new HttpClient(
    retryDelay: function (int $retryAfter, int $attempt): void {
        usleep($retryAfter * 1_000_000);
    },
);

Custom HTTP Client

The SDK accepts any PSR-18 compatible HTTP client:

use ActiveCampaign\Client;

$ac = new Client(
    httpClient: $yourPsr18Client,
);

By default, the SDK uses Guzzle 7.

Environment Variables

The SDK reads these environment variables as fallbacks when constructor arguments are not provided:

// Uses environment variables automatically
$ac = new Client();

Available Resources

Each resource is a method on the client object.

Core: contacts(), deals(), tags(), lists(), accounts(), automations(), campaigns(), webhooks(), customFields(), notes(), forms(), segments(), users(), addresses()

Deals: pipelines(), dealStages(), dealCustomFields(), dealCustomFieldValues(), dealRoles(), dealTasks(), dealTaskTypes(), dealTaskOutcomes()

Accounts: accountContacts(), accountCustomFields(), accountCustomFieldValues()

Contact fields: fieldValues(), fieldOptions()

Communication: messages(), scores()

Admin: groups(), calendarFeeds(), brandings(), savedResponses(), templates(), settings()

E-Commerce: connections(), ecomCustomers(), ecomOrders(), ecomOrderProducts()

Tracking: eventTracking(), siteTracking()

Custom Objects: customObjectSchemas(), customObjectRecords($schemaId)

Bugs

Report issues at GitHub Issues.

License

MIT