API-rajapinnan esittely

Creamailerin REST API tarjoaa lähes rajattomat mahdollisuudet Creamailerin hyödyntämiseen. Sen avulla voit integroida Creamailerin suoraan mihin tahansa tietokantaan tai järjestelmään, kuten esimerkiksi CMS:ään, CRM:ään, verkkokauppaan tai blogiin.

API:n käyttö edellyttää ohjelmointitaitoja, joten API:in liittyvä ohjeistus on suunnattu ainoastaan ohjelmoijille. API:n avulla voit:

• hakea, lisätä, muokata ja poistaa postituslistoja
• hallita postituslistojen tilaajia
• hallita estolistaa
• ajaa bulk-importteja
• hakea tilaajan koko viestihistorian esimerkiksi CRM-integraatioita varten

Tämä sivu sisältää tietoa API:n käyttämiseen liittyvistä rajoituksista ja vastuista, joten suosittelemme sen huolellista lukemista. Tiedotamme API:iin liittyvistä muutoksista ja päivityksistä uutiskirjeellä.

API-versiot

Creamailerin API:sta on käytössä useampi versio. Nykyinen versio on v2, jolla uudet integraatiot tulee toteuttaa. Aiempi versio on v1. Se toimii edelleen vanhojen integraatioiden tueksi.

v2-versio sisältää muun muassa seuraavat parannukset:

• HMAC-SHA256-allekirjoitus
• tyypitetyt virhevastaukset
• bulk-import
• tilaajan viestihistorian haku
• custom-kenttien skeeman nouto

Dokumentaatio

Päivittyvät muuttujat on merkitty dokumentaatiossa hakasulkeilla.

Esimerkiksi:

• {ACCESS_TOKEN} vastaa ylläpidosta löytyvää asiakastunnusta
• {SHARED_SECRET} vastaa yhteistä tunnistetta

API:n rakenne

Creamailer pidättää kaikki oikeudet muokata API:n rakennetta, käyttöoikeuksia ja käyttöehtoja ilman ennakkovaroitusta.

Toimintoja voidaan esimerkiksi poistaa väliaikaisesti käytöstä, jos ne vaikuttavat tuleviin ominaisuuksiin. Mahdollisista muutoksista tiedotetaan ylläpidosta löytyvissä tiedotteissa.

API:n rakenne pyritään pitämään ennallaan jokaisessa versiossa. Suuremmat rakenteelliset muutokset toteutetaan pääsääntöisesti uuden API-version kautta. Uuteen versioon siirtyminen tapahtuu päivittämällä versionumero API-osoitteessa.

Käytön rajoitukset

Creamailer sallii 100 API-kutsua tunnissa per API-avain. Kun raja ylittyy, API palauttaa virheilmoituksen: 429 Too Many Requests

Suosittelemme huomioimaan tämän integraation toteutuksessa esimerkiksi:

• jonotuksella
• exponential back-off -logiikalla

Tietoturva

API:ta voidaan käyttää ainoastaan salatun HTTPS-yhteyden kautta.

Jokaisen kutsun yhteydessä lähetetään Yhteisen tunnisteen avulla laskettu HMAC-SHA256-tarkistussumma. Tämä varmistaa kutsun eheyden ja estää kolmansia osapuolia muokkaamasta kutsua.

API:iin liittyviä asiakastunnuksia voidaan lisätä rajattomasti Creamailerin ylläpidosta. Tunnuksille voidaan määrittää:

• lukuoikeus
• kirjoitusoikeus

Tunnukset voidaan myös poistaa suoraan ylläpidosta.

Ongelmatilanteet

Creamailer API pyrkii palauttamaan virhetilanteissa mahdollisimman kuvaavan virheilmoituksen. Virheilmoitus on hyvä ottaa talteen ja ilmoittaa tukeen (tuki@creamailer.fi) yhteyttä otettaessa.