Příklady použití Boldem API v praxi

Michal Krejčí Michal Krejčí
2. listopadu 2022

V tomto dokumentu najdete praktické příklady, které můžete využít při implementaci rozhraní API automatizovaného marketingového nástroje Boldem.

Kompletní dokumentaci všech koncových bodů najdete na https://api.boldem.cz/.

Autorizace do Boldem API

Postup autorizace (ověření) do Boldem API včetně příkladů najdete v samostatné kapitole.

Předpoklady použití Boldem API

Pro správnou funkčnost příkladů je zapotřebí splnit několik požadavků.

Dále předpokládáme, že nám v případě více účtů postačí pro každý účet jeden doménový směrovač a tedy jedno konkrétní ID doménového směrovače. V následujících příkladech proto budeme používat konkrétní dispatcherId = 44. V jiných případech si dispatcherId vyžádejte u zákaznické podpory.

V textu odpovědi (response body) na požadavky Create a Update obdržíte vždy kompletní objekt daného prostředku.

V případě úspěšného zpracovaní obdržíte některý z 2xx kódů (v závislosti na typu operace).

V případě problémů při zpracování požadavku je vrácen chybový kód a problém je popsán v textu odpovědi (response body).

U některých koncových bodů je důležitá správná kombinace některých hodnot, proto pro maximální zjednodušení uvádíme konkrétní příklady volání.

Vytvoření šablony pro hromadnou e-mailovou kampaň

Koncový bod

POST /v1/html-templates

Datová část

{
    "dispatcherId": null,
    "templateGroupId": null,
    "name": "Save the Date Template",
    "subject": "Subject of Save the Date Template",
    "preheader": "Preheader of Save the Date Template",
    "body": "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\"> <title></title> </head><body><h1>Header</h1> <p>Some content</p></body></html>",
    "bodyAlternative": "Header\r\nSomeContent",
    "isTransactional": false,
    "trackClicks": true,
    "trackOpens": true,
    "fromAddress": null,
    "fromDisplayName": null,
    "webTrackParam": null,
    "replyToAddress": null
}

Kód odpovědi v případě úspěchu

201

Poznámky

  • Parametr isTransactional je nutné nastavit na false. Říkáme tím, že se jedná o šablonu pro hromadnou rozesílku.
  • V případě úspěšného zpracování požadavku je šablona dostupná ke kontrole v rozhraní aplikace Boldem v sekci Šablony.
  • V parametru templateId je v textu odpovědi (response body) identifikátor nově vytvořené šablony pro další práci.

Vytvoření hromadné e-mailové kampaně s přidělením seznamů příjemců

Koncový bod

POST /v1/mass-email-campaigns

Datová část

{
    "templateId": 3033, // templateId z předchozího volání
    "dispatcherId": 44, // konkrétní dispatcherId
    "name": "Save the Date Campaign",
    "description": "Description of Save the Date Campaign",
    "webTrackParam": null,
    "fromAddress": "info@example.com",
    "fromDisplayName": "YOUR COMPANY NAME",
    "replyToAddress": null,
    "trackClicks": true,
    "trackOpens": true,
    "mailingListIds": [125] // konkrétní IDčka seznamů příjemců ze systému
}

Kód odpovědi v případě úspěchu

201

Poznámky

  • V případě úspěšného zpracování požadavku je šablona dostupná ke kontrole v rozhraní aplikace Boldem v sekci Kampaně.
  • V textu odpovědi (response body) je v parametru campaignId uložen identifikátor nově vytvořené šablony pro další práci.

Odhlášení příjemců z kampaně

Příklad volání níže vyřadí zvoleného příjemce z konkrétní kampaně.

Koncový bod

POST /v1/unsubscribes

Datová část

{
    "email": "user@example.com",
    "mailingListId": null,
    "campaignId": 1175, // campaignId z předchozího kroku (ID hromadné kampaně, kterou nechceme tomuto příjemci posílat
    "validFrom": null,
    "validTo": null
}

Kód odpovědi v případě úspěchu

201

Poznámky

  • V případě úspěšného zpracování lze pro daný e-mail a danou kampaň v rozhraní aplikace Boldem najít položku v sekci Seznamy příjemců > Odhlášení příjemci.
  • Pokud nechceme příjemce odhlásit plošně, ale jen z konkrétní kampaně, je nutné vyplnit parametr campaignId. Pokud zůstane parametr campaignId nulový (null), dojde k plošnému odhlášení příjemce ze všech rozesílek v daném účtu.

Realizace testovací rozesílky

Koncový bod

POST /v1/mass-email-campaign-tests

Datová část

{
    "email": "user@example.com",
    "campaignId": 1175
}

Kód stavu v případě úspěchu

202

Poznámky

  • Testovací rozesílka probíhá formou odeslání transakčního e-mailu s danou kampaní na daného příjemce. Jedná se o asynchronní operaci. V hlavičce odpovědi je v parametru Location uvedena adresa koncového bodu pro získání informace o stavu odeslání transakčního e-mailu (GET /v1/{{LocationHeaderContent}}).
  • V případě úspěšného zpracování lze najít pro daný transakční e-mail informace v rozhraní aplikace Boldem v sekci Transakční e-maily.

Realizace ostré hromadné rozesílky

Koncový bod

POST /v1/mass-email-campaign-executions

Datová část

{
    "campaignId": 1175
}

Kód stavu v případě úspěchu

202

Poznámky

  • Před samotným odeslání probíhá validace nastavení rozesílky. Pro úspěšné odeslání musí být nastavena odesílací doména a směrovač a v šabloně musí být odhlašovací odkaz.
  • Jedná se o asynchronní operaci. V hlavičce odpovědi je v parametru Location uvedena adresa koncového bodu pro získání informace o stavu odeslání hromadné rozesílky (GET /v1/{{LocationHeaderContent}}). Součástí adresy je také ID rozesílky (campaign-execution-states/{{campaignExecutionId}}).
  • V případě úspěšného zpracování lze v aplikaci Boldem najít v sekci Kampaně informace o stavu rozesílky dané kampaně a její statistiky.

Kontrola stavu hromadné rozesílky

Koncový bod

GET /v1/campaign-execution-states/{{campaignExecutionId}}

Kód stavu v případě úspěchu

200

Poznámky

Součástí textu odpovědi (response body) jsou informace o stavu a fázi rozesílky. Textové hodnoty jsou popsány v dokumentaci (CampaignExecutionStateApi, CampaignExecutionPhaseApi). Úspěšné odeslání kompletní rozesílky je reprezentováno kombinací state = 1 a phase = 4. Například: 

{
    "campaignId": 1175,
    "state": 1, // Active
    "phase": 4 // Finished
}

Statistiky hromadné rozesílky

Vygenerování statistik o hromadných rozesílkách ve formátu .csv.

Koncový bod

GET /v1/ mass-email-campaigns/{{campaignId}}

Kód stavu v případě úspěchu

200

V textu odpovědi (response body) najdete parametr stats, který obsahuje statistická data o rozesílkách dané kampaně.

Statistiky také můžete „zapnout“ u výpisu seznamu hromadných kampaní použitím parametru include.

Koncový bod

GET /v1/mass-email-campaigns?include=stats

Kód stavu v případě úspěchu

200

Oproti volání bez parametru include přibude do textu odpovědi ke každému objektu ve výpisu atribut stats, který obsahuje statistiky rozesílek dané kampaně.

Vytvoření kampaně pro transakční rozesílku

Koncový bod

POST /v1/html-templates

Datová část

{
    "dispatcherId": 44,
    "templateGroupId": null,
    "name": "Transactional Template",
    "subject": "Subject of Transactional Template",
    "preheader": "Preheader of Transactional Template",
    "body": "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\"> <title></title> </head><body><h1>Header</h1> <p>Some content</p></body></html>",
    "bodyAlternative": "Header\r\nSomeContent",
    "isTransactional": true,
    "trackClicks": true,
    "trackOpens": true,
    "fromAddress": "info@example.com",
    "fromDisplayName": "YOUR COMPANY NAME",
    "webTrackParam": null,
    "replyToAddress": null
}

Kód odpovědi v případě úspěchu

201

Poznámky

  • Parametr isTransactional je nutné nastavit na hodnotu true. Říkáme tím, že se jedná o šablonu pro transakční e-maily. Pro použití transakční šablony je nutné mít nastavené parametry dispatcherId, trackClicks, trackOpens, fromAddress a fromDisplayName.
  • V případě úspěšného zpracování požadavku je šablona dostupná ke kontrole v rozhraní aplikace Boldem v sekci Šablony.
  • V parametru templateId je v textu odpovědi (response body) uložen identifikátor nově vytvořené šablony pro další práci.

Odeslání transakčního e-mailu

Koncový bod

POST /v1/transactional-emails

Datová část

{
    "to": {
        "address": "user@example.com"
    },
    "templateId": 3035,
    "variables": {
        "surname": "Novák",
        "name": "Jan",
        "sex": true,
        "age": 30,
        "actionDate": "2021-08-13"
    }
}

Kód stavu v případě úspěchu

202

Poznámky

  • Odeslání transakčního e-mailu je možné jen s transakční šablonou (isTransactional = 1).
  • Jedná se o asynchronní operaci. V hlavičce odpovědi je v parametru Location uvedena adresa koncového bodu pro získání informace o stavu odeslání transakčního e-mailu (GET /v1/{{LocationHeaderContent}}).
  • V případě úspěšného zpracování lze najít pro daný transakční e-mail informace v rozhraní aplikace Boldem v sekci Transakční e-maily.