Creamailerin API SDK PHP:lle

Creamailerista löytyy valmis SDK-kirjasto PHP:lle, joka nopeuttaa integraation rakentamista merkittävästi. Kirjaston avulla esimerkiksi yhteyden muodostaminen ja tilaajan lisäys Creamailerin postituslistalle onnistuu muutamassa minuutissa. Kirjaston GitHub-sivu.

Tämä ohje koskee kirjaston versiota 2.x, joka kommunikoi Creamailer API v2:n kanssa. Vanha 1.x toimii edelleen, jos kutsuit v1-rajapintaa. Jos pysyt v1:ssä, lukitse Composerissa "creamailer/creamailer-api-sdk": "^1.0". Päivitysohje 1.x → 2.x löytyy MIGRATION.md-tiedostosta.

Vaatimukset

• PHP 8.0+
• ext-curl, ext-json

Asentaminen

Kirjasto voidaan asentaa käyttäen Composeria.

composer require creamailer/creamailer-api-sdk:^2.0

Asennuksen jälkeen:

Jos projektissa ei ole valmiiksi käytössä autoloaderia, se tulee lisätä rivillä:

require("vendor/autoload.php");

Yhteyden muodostaminen

Yhteyden muodostamista varten tarvitaan CREAMAILER_ACCESS_TOKEN ja CREAMAILER_SHARED_SECRET -API-avaimet. Ne voidaan luoda Creamailerin ylläpidosta oman käyttäjätunnuksen alta kohdasta Asetukset → API.

Esimerkki:

use Creamailer\Client;

$creamailer = new Client(
    accessToken:  getenv('CREAMAILER_ACCESS_TOKEN'),
    sharedSecret: getenv('CREAMAILER_SHARED_SECRET'),
);

SDK hoitaa HMAC-SHA256-allekirjoituksen, aikaleimat ja TLS-tarkistuksen puolestasi — sinun tarvitsee toimittaa vain tunnukset.

Yhteyden testaus

Yhteys voidaan testata käyttämällä kirjastosta löytyvää ping-metodia. Vastaus on tavallinen PHP-array.

$result = $creamailer-ping();

print_r($result);
// ['message' = 'Connection successful.']

Mahdollinen virhe, kuten väärä tunnus tai allekirjoitus, heittää tyypitetyn poikkeuksen. Katso lisätiedot kohdasta Virheenkäsittely.

Postituslistat

// Kaikki listat
$creamailer-lists()-all();

// Yksi lista
$creamailer-lists()-get(1234);

// Luo lista
$creamailer-lists()-create([
    'name'          = 'Uutiskirjeen tilaajat',
    'language'      = 'fi',
    'auto_suppress' = true,
]);

// Päivitä
$creamailer-lists()-update(1234, ['name' = 'Uusi nimi']);

// Poista
$creamailer-lists()-delete(1234);

// Listan custom-kentät
$creamailer-lists()-fields(1234);

Tilaajat

$listId = 1234;

// Listan tilaajat (sivutettu)
$creamailer-subscribers()-all($listId, [
    'status'   = 'active',
    'pagesize' = 100,
    'page'     = 1,
]);

// Hae yksittäinen tilaaja sähköpostilla
$creamailer-subscribers()-find($listId, 'name@example.com');

// Lisää tilaaja
$creamailer-subscribers()-create($listId, [
    'email'                         = 'name@example.com',
    'name'                          = 'Firstname Lastname',
    'company'                       = 'Company Name',
    'title'                         = 'Toimitusjohtaja',
    'address'                       = 'Street 1',
    'city'                          = 'Helsinki',
    'zip_code'                      = '00100',
    'country'                       = 'Finland',
    'phone'                         = '040123456',
    'customer_number'               = '1234',
    'status'                        = 'active',
    'send_autoresponders'           = true,
    'send_autoresponders_if_exists' = true,
    'custom_fields'                 = [
        'some_custom_field' = 'some extra info',
    ],
]);

// Päivitä (vaihda sähköposti new_email-parametrilla)
$creamailer-subscribers()-update($listId, [
    'email'     = 'old@example.com',
    'new_email' = 'new@example.com',
    'name'      = 'Päivitetty nimi',
]);

// Poista (peru tilaus)
$creamailer-subscribers()-delete($listId, 'name@example.com');

Huom. Personoituja kenttiä (custom_fields) tulee käyttää vain, jos niitä on määritelty postituslistalle. Käytettävissä olevat kenttänimet saa endpointilla $creamailer-lists()-fields($listId).

Usean tilaajan tuonti (bulk import)

$creamailer-subscribers()-import($listId, [
    ['email' = 'a@example.com', 'name' = 'Anna'],
    ['email' = 'b@example.com', 'name' = 'Bertta', 'update_existing' = true],
    // ... enintään 500 riviä per kutsu
]);

Tilaajan viestihistoria (CRM-integraatio)

Hae tilaajan kaikki viestit kaikilta listoilta — kampanjat, avaukset, klikit, bounces, unsubscribed sekä julkinen web_version_url-linkki kuhunkin viestiin. Sopii erinomaisesti CRM-näkymään.

$activity = $creamailer-subscribers()-activity('name@example.com', pagesize: 20);

echo $activity['data']['summary']['total_messages'];

foreach ($activity['data']['messages']['data'] as $message) {
    echo $message['campaign_name'] . ' — ' . $message['web_version_url'] . PHP_EOL;
}

Estolista

// Hae estolista (sivutettu, max 1000 per sivu)
$creamailer-suppressions()-all(pagesize: 1000);

// Lisää osoite estolistalle
$creamailer-suppressions()-create('blocked@example.com');

// Poista osoite estolistalta
$creamailer-suppressions()-delete('blocked@example.com');

Virheenkäsittely

Epäonnistuneet kutsut heittävät tyypitetyn poikkeuksen HTTP-statuksen mukaan:

use Creamailer\Exceptions\ValidationException;
use Creamailer\Exceptions\RateLimitException;
use Creamailer\Exceptions\ApiException;

try {
    $creamailer-subscribers()-create($listId, ['email' = 'invalid']);
} catch (ValidationException $e) {
    foreach ($e-getErrors() as $field = $messages) {
        echo "$field: " . implode(', ', $messages) . PHP_EOL;
    }
} catch (RateLimitException $e) {
    sleep(60); // kvootti tyhjeni — odota ja yritä uudelleen
} catch (ApiException $e) {
    // mikä tahansa muu API-virhe
    echo $e-getMessage();
}

Lisää esimerkkejä Creamailerin API SDK -kirjaston käytöstä löytyy sen GitHub-sivulta ja README:stä.