mailkit.mailinglist.adduser

Funkce mailkit.mailinglist.adduser přidá nového příjemce do seznamu, nebo aktualizuje stávajícího.

Tato API funkce není určena k hromadnému plnění seznamu příjemců, ale jako nástroj pro okamžité přidání či aktualizaci jednoho příjemce. Pro synchronizaci s informačními systémy doporučujeme využívat datové zdroje, které umožňují jednodušší a flexibilnější implementaci, která je časově méně náročná na realizaci.

Vždy je potřeba myslet na to, že obchodní sdělení je možné posílat pouze příjemcům, od kterých máte ověřený a prokazatelný souhlas (tzv. double-opt-in) nebo existujícím zákazníkům.

API požadavek musí být zaslán v níže uvedené podobě. Příklad jak implementovat API volání v PERL zde.
UPOZORNĚNÍ: Formát zasílaných dat musí být v Base 64. Parametry jsou rozděleny do několika větví, jejichž pořadí a existenci je nutné dodržet.

Ukázka API volání:

JSON 

{
    "function": "mailkit.mailinglist.adduser",
    "id": "client_id",
    "md5": "client_md5",
    "parameters": {
        "ID_user_list": "12345",
        "confirm": "FALSE",
        "personal": {
            "email": "ZXhhbXBsZUBleGFtcGxlLmN6",
            "ID_template": "MTIzNDU2",
            "email_from": "ZXhhbXBsZUBleGFtcGxlLmN6",
            "name_from": "T2Rlc2lsYXRlbA==",
            "return_url": "aHR0cDovL3NvbWUud2hlcmU=",
            "first_name": "Sm3DqW5v",
            "last_name": "UMWZw61qbWVuw60=",
            "vocative": "T3Nsb3ZlbsOt",
            "prefix": "VGl0dWw=",
            "reply_to": "ZXhhbXBsZUBleGFtcGxlLmN6",
            "company": "U3BvbGXEjW5vc3Q="
        },
        "address": {
            "zip": "UFPEjA==",
            "mobile": "bW9iaWw=",
            "fax": "ZmF4",
            "nick_name": "UMWZZXpkw612a2E=",
            "country": "S3Jhag==",
            "street": "VWxpY2U=",
            "state": "WmVtxJs=",
            "city": "TcSbc3Rv",
            "phone": "VGVsZWZvbg==",
            "gender": "Rg=="
        },
        "custom": {
            "custom1": "dmxhc3Ruw60gxI0uMQ==",
            "custom25": "dmxhc3Ruw60gxI0uMjU="
        },
        "params": {
            "ip_src": "1.2.3.4",
            "form_url": "https://example.com/form"
        }
    }
}

XML 

<?xml version="1.0"?>
<methodCall>
  <methodName>mailkit.mailinglist.adduser</methodName>
  <params>
   <param>
    <value>
      <int>client_id</int>
    </value>
   </param>
   <param>
    <value>
      <string>client_md5</string>
    </value>
   </param>
   <param>
    <value>
      <int>ID_user_list</int>
    </value>
   </param>
   <param>
    <value>
      <boolean>confirm</boolean>
    </value>
   </param>
   <param>
    <value>
      <struct>
       <member>
        <name>ID_template</name>
        <value>
          <string>MTIzNDU2y</string></value>
       </member>
       <member>
        <name>email_from</name>
        <value>
          <string>ZXhhbXBsZUBleGFtcGxlLmN6</string></value>
       </member>
       <member>
        <name>name_from</name>
        <value>
          <string>T2Rlc2lsYXRlbA==</string></value>
       </member>
       <member>
        <name>return_url</name>
        <value>
          <string>aHR0cDovL3NvbWUud2hlcmU=</string></value>
       </member>
       <member>
        <name>vocative</name>
        <value>
          <string>T3Nsb3ZlbsOt</string>
        </value>
       </member>
       <member>
        <name>prefix</name>
        <value>
          <string>VGl0dWw=</string>
        </value>
       </member>
       <member>
        <name>first_name</name>
        <value>
          <string>Sm3DqW5v</string>
        </value>
       </member>
       <member>
        <name>last_name</name>
        <value>
          <string>UMWZw61qbWVuw60=</string>
        </value>
       </member>
       <member>
        <name>email</name>
        <value>
          <string>ZXhhbXBsZUBleGFtcGxlLmN6</string>
        </value>
       </member>
       <member>
        <name>reply_to</name>
        <value>
          <string>ZXhhbXBsZUBleGFtcGxlLmN6</string>
        </value>
       </member>
       <member>
        <name>company</name>
        <value>
          <string>U3BvbGXEjW5vc3Q=</string>
        </value>
       </member>
      </struct>
    </value>
   </param>
   <param>
    <value>
      <struct>
       <member>
        <name>nick_name</name>
        <value>
          <string>UMWZZXpkw612a2E=</string>
        </value>
       </member>
       <member>
        <name>country</name>
        <value>
          <string>S3Jhag==</string>
        </value>
       </member>
       <member>
        <name>street</name>
        <value>
          <string>c3RyZWV0IGVkaXQ0</string>
        </value>
       </member>
       <member>
        <name>state</name>
        <value>
          <string>WmVtxJs=</string>
        </value>
       </member>
       <member>
        <name>zip</name>
        <value>
          <string>UFPEjA==</string>
        </value>
       </member>
       <member>
        <name>city</name>
        <value>
          <string>TcSbc3Rv</string>
        </value>
       </member>
       <member>
        <name>mobile</name>
        <value>
          <string>bW9iaWw=</string>
        </value>
       </member>
       <member>
        <name>phone</name>
        <value>
          <string>VGVsZWZvbg==</string>
        </value>
       </member>
       <member>
        <name>fax</name>
        <value>
          <string>ZmF4</string>
        </value>
       </member>
       <member>
        <name>gender</name>
        <value>
          <string>Rg==</string>
        </value>
       </member>
      </struct>
    </value>
   </param>
   <param>
    <value>
      <struct>
       <member>
        <name>custom1</name>
        <value>
          <string>dmxhc3Ruw60gxI0uMQ==</string>
        </value>
       </member>
       <member>
        <name>custom25</name>
        <value>
          <string>dmxhc3Ruw60gxI0uMjU=</string>
        </value>
       </member>
      </struct>
    </value>
   </param>
   <param>
    <value>
      <struct>
       <member>
        <name>ip_src</name>
        <value>
          <string>1.1.1.1</string>
        </value>
       </member>
       <member>
        <name>form_url</name>
        <value>
          <string>http://www.form.cz</string>
        </value>
       </member>
      </struct>
    </value>
   </param>
  </params>
</methodCall>

Hodnoty

client_id * = API ID naleznete ve svém Mailkit účtu v menu Profil/Integrace.
client_md5 * = MD5 kód naleznete ve svém Mailkit účtu v menu Profil/Integrace.
ID_user_list * = ID seznamu příjemců
confirm* = odeslání potvrzovacího e-mailu o přidání do seznamu příjemců. Jsou přípustné 2 hodnoty: TRUE a FALSE

  • FALSE (defaultní hodnota)
    –> pokud společně s touto hodnotou bude zasláno i ip_src a form_url (viz níže větěv "params") potvrzovací e-mail se nepošle a příjemce bude vložen do seznamu příjemců okamžitě. Zaslané parametry ip_src a form_url budou k příjemci uloženy do databáze. Tímto vložením je možné také reaktivovat (znovu přihlásit) dříve odhlášeného příjemce.
    –> pokud společně s touto hodnotou ip_src a form_url zasláno nebude, tak se potvrzovací e-mail nepošle a příjemce bude uložen do seznamu příjemců jako typ single opt-in. Tímto vložením se nereaktivuje dříve odhlášený příjemce.
  • TRUE –> potvrzovací e-mail bude odeslán a příjemce bude vložen do seznamu příjemců až po té, co klikne v e-mailu na potvrzovací odkaz a potvrdí přihlášení. Hodnoty ip_src a form_url zasílané ve volání jsou důležité pro identifikaci reálného zdroje požadavku a pomáhají nám detekovat případné roboty.
    Přihlašovací e-mail se nezašle tomu příjemci, jež má již dříve potvrzený a zároveň nezrušený souhlas – v takovém případě příjemce bude rovnou vložen do seznamu příjemců.

Větev "personal"

email (v Base 64) * = e-mailová adresa příjemce
ID_template (v Base 64) = ID šablony s vlastním souborem přihlašovací stránky (povinně)/přihlašovacího e-mailu. Používá se v případě, kdy send opt-in confirmationmail = TRUE. Pokud se nepoužije, odešle se potvrzovaci e-mail ve standardním vzhledu.
email_from (v Base 64) = e-mailová adresa, ze které bude odeslán potvrzovací e-mail (nepovinný údaj, pokud je v účtu nastaven kontaktní e-mail. Pokud není vyplněna hodnota pro email_from a zároveň není v účtu nastaven kontaktní e-mail, API volání skončí chybou)
name_from (v Base 64) = jméno odesílací adresy potvrzovacího e-mailu
return_url (v Base 64) = návratová url adresa po potvrzení přihlášení
first_name (v Base 64) = jméno příjemce
last_name (v Base 64) = příjmení příjemce
company (v Base 64) = firma příjemce
prefix (v Base 64) = titul příjemce
vocative (v Base 64) = oslovení příjemce
reply_to (v Base 64) = e-mailová adresa pro odpověď příjemce

Větev "address"

nick_name (v Base 64) = přezdívka příjemce
gender (v Base 64) = pohlaví příjemce. Může nabývat hodnot male/female; m/f; muz/zena; M/F
phone (v Base 64) = telefon příjemce
mobile (v Base 64) = mobil příjemce
fax (v Base 64) = fax příjemce
street (v Base 64) = adresa (ulice) příjemce
city (v Base 64) = město příjemce
state (v Base 64) = země příjemce
country (v Base 64) = kraj příjemce
zip (v Base 64) = PSČ příjemce

Větev "custom"

custom1 (v Base 64) = vlastní pole příjemce č. 1. Celkový počet vlastních polí je 25.

Větev "params"

ip_src – IP adresa, ze které došlo k přihlášení (udělení souhlasu)
form_url – url adresa, kde je umístěn vlastní přihlašovací formulář, jehož prostřednictvím došlo k přihlášení


Pokud chcete smazat hodnotu v některém z polí (jméno, příjmení, vlastní pole, ...), je potřeba v API volání pro dané pole poslat hodnotu _null (v Base 64).

* povinný parametr

Po úspěšném volání se vrací:

1) CONFIRM = TRUE (–> je odeslán double opt-in e-mail)

JSON 

{
    "error": "Sent subscribe email",
    "error_status": 0
}

XML 

<?xml version="1.0" encoding="utf-8"?>
<methodResponse>
  <params>
    <param>
      <value>
        <string>Sent subscribe email</string>
      </value>
    </param>
  </params>
</methodResponse>

Hodnoty

Sent subscribe email = potvrzovací e-mail byl úspěšně odeslán

2) CONFIRM = FALSE (–> není odeslán double opt-in e-mail)

JSON 

{
    "ID_email": "1234567890",
    "status": "1",
    "error": "OK",
    "error_status": 0
}

XML 

<?xml version="1.0" encoding="utf-8"?>
<methodResponse>
<params>
 <param>
  <value>
   <struct>
    <member>
     <name>status</name>
     <value>
      <i4>1</i4>
     </value>
    </member>
    <member>
     <name>data</name>
     <value>
      <i4>1234567890</i4>
     </value>
    </member>
   </struct>
  </value>
 </param>
</params>
</methodResponse>

Hodnoty

status = potvrzení úspěšného vložení příjemce. Nabývá těchto hodnot:

  • 0 = update (příjemce má souhlas již zaevidovaný a byl aktualizován, v parametru "ID_email" API vrátí ID aktualizované e-mailové adresy)
  • 1 = insert (příjemce byl úspěšně vložen)
  • 2 = insert (příjemce byl vložen a má status odhlášený)
  • 3 = update (příjemce byl aktualizován a má status odhlášený)
  • 4 = fault (chybný / blokovaný e-mail, příjemce nebyl vložen)
  • 7 = update (příjemce byl aktualizován, má již dříve zaevidovaný souhlas (datum souhlasu nebylo voláním aktualizováno!), ale zároveň má odhlášeno některé z témat. Stav odhlášení příjemce lze zjistit pomocí volání mailkit.email.unsubscribe.getstatus.

ID_email = ID nově vloženého příjemce (JSON)
data = ID nově vloženého příjemce (XML)

Příklad neúspěšného volání:

JSON 

{
    "error": "Missing email",
    "error_status": 1
}

XML 

<?xml version="1.0" encoding="utf-8"?>
<methodResponse>
  <params>
    <param>
      <value>
        <string>Missing email</string>
      </value>
    </param>
  </params>
</methodResponse>

Hodnoty

Bad email syntax = e-mailová adresa má špatný formát (status: 1)
Unknown domain = e-mailová adresa má neznámou doménu (status: 1)​
No such email = e-mailová adresa neexistuje (status: 1)
Unable to validate email = e-mail nelze ověřit (status: 1)​​​​​​​
Invalid recipient details​​​​​​​ = neplatné údaje o příjemci (status: 2)​​​​​​​
Invalid ID_template = neplatné ID šablony​​​​​​​ (status: 3)​​​​​​​
Missing ID_mailing_list = chybí ID seznamu příjemců (status: 3)​​​​​​​
Invalid ID_mailing_list = neplatné ID seznamu příjemců (status: 3)​​​​​​​
Domain blocked​​​​​​​ = doména e-mailové adresy příjemce blokována (status: 4)​​​​​​​
Invalid sending email​​​​​​​ = neplatný odesílací e-mail (status: 5)​​​​​​​
Sending email not available​​​​​​​ = odesílací e-mail není k dispozici (status: 5)​​​​​​​
Missing email = chybí e-mailová adresa příjemce (status: 3)

Statusy chyb (pouze u JSON)

1 – chyba při validaci
2 – chyba při validaci
3 – neplatné parametry
4 – doména příjemce je blokována
5 – chybné nastavení odesílací adresy

Jako prevence před robotickými interakcemi jsou nastaveny následující limity pro odeslání DOI e-mailu.
  • e-mailová adresa může mít maximálně 3 žádosti na odeslání DOI e-mailu za minutu –> pokud je limit překročen, vrací API odpověď - "Too many DOI attempts for this email, try again later"
  • z IP adresy může přijít maximálně 15 požadavků na odeslání DOI e-mailu za 5 minut –> pokud je limit překročen, vrací API odpověď - "Too many DOI attempts from this IP, try again later"