PodporaAPI dokumentace

mailkit.sendmail

Odeslání zprávy skrz existující e-mailovou kampaň s přiřazenou šablonou.

XML-RPC žádost musí být vydána ve formátu uvedeném níže.

UPOZORNĚNÍ: Formát zasílaných dat musí být v Base 64.

XML 

<?xml version="1.0"?>
<methodCall>
  <methodName>mailkit.sendmail</methodName>
  <params>
    <param>
      <value>
        <int>client_id</int>
      </value>
    </param>
    <param>
      <value>
        <string>client_md5</string>
      </value>
    </param>
    <param>
      <value>
        <int>mailinglist_id</int>
      </value>
    </param>
    <param>
      <value>
        <int>campaign_id</int>
      </value>
    </param>
    
-------příjemce, předmět a obsah-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>send_to</name>
            <value>
              <string>email@email.com</string>
            </value>
          </member>
          <member>
            <name>subject</name>
            <value>
              <string>volitelný předmět</string>
            </value>
          </member>
          <member>
            <name>message_data</name>
            <value>
              <string>tělo zprávy</string>
            </value>
          </member>
          <member>
            <name>content</name>
            <value>
              <struct>
                <member>
                  <name>var1</name>
                  <value>
                    <string>proměnná 1</string>
                  </value>
                </member>
                <member>
                  <name>jiny_nazev</name>
                  <value>
                    <string>proměnná 2</string>
                  </value>
                </member>
              </struct>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------oslovení, jméno, atp.-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>status</name>
            <value>
              <string>status</string>
            </value>
          </member>
          <member>
            <name>vocative</name>
            <value>
              <string>vocative</string>
            </value>
          </member>
          <member>
            <name>prefix</name>
            <value>
              <string>prefix</string>
            </value>
          </member>
          <member>
            <name>last_name</name>
            <value>
              <string>příjmení</string>
            </value>
          </member>
          <member>
            <name>first_name</name>
            <value>
              <string>jméno</string>
            </value>
          </member>
          <member>
            <name>reply_to</name>
            <value>
              <string>reply_to_email</string>
            </value>
          </member>
          <member>
            <name>company</name>
            <value>
              <string>company</string>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------přezdívka, adresa atp.-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>nick_name</name>
            <value>
              <string>přezdívka</string>
            </value>
          </member>
          <member>
            <name>street</name>
            <value>
              <string>adresa</string>
            </value>
          </member>
          <member>
            <name>city</name>
            <value>
              <string>město</string>
            </value>
          </member>
          <member>
            <name>country</name>
            <value>
              <string>země</string>
            </value>
          </member>
          <member>
            <name>state</name>
            <value>
              <string>kraj</string>
            </value>
          </member>
          <member>
            <name>zip</name>
            <value>
              <string>psč</string>
            </value>
          </member>
          <member>
            <name>mobile</name>
            <value>
              <string>mobil</string>
            </value>
          </member>
          <member>
            <name>phone</name>
            <value>
              <string>telefon</string>
            </value>
          </member>
          <member>
            <name>fax</name>
            <value>
              <string>fax</string>
            </value>
          </member>
          <member>
            <name>gender</name>
            <value>
              <string>pohlaví</string>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------vlastní pole-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>custom1</name>
            <value>
              <string>vlastní pole č. 1</string>
            </value>
          </member>
          <member>
            <name>custom25</name>
            <value>
              <string>vlastní pole č. 25</string>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------přílohy-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>name</name>
            <value>
              <string>nazev</string>
            </value>
          </member>
          <member>
            <name>data</name>
            <value>
              <string>base64 data</string>
            </value>
          </member>
        </struct>
      </value>
    </param>

--------------
 
  </params>
</methodCall>

JSON 

{
  "function": "mailkit.sendmail",
  "id": "api_id",
  "md5": "client_md5",
  "parameters": {
    "mailinglist_id": "Mailing list ID",
    "campaign_id": "Campaign ID",
    "main": {
      "send_to": "email@email.com",
      "subject": "optional subject",
      "message_data": "optional message body",
      "content": {
        "var1": "variable 1",
        "other_name": "variable 2"
      }
    },
    "recipient": {
      "status": "status",
      "vocative": "vocative",
      "prefix": "prefix",
      "last_name": "last_name",
      "first_name": "first_name",
      "reply_to": "reply_to_email",
      "company": "company"
    },
    "contact": {
      "nick_name": "nick_name",
      "street": "address",
      "city": "city",
      "country": "country",
      "state": "state",
      "zip": "zip code",
      "mobile": "mobile",
      "phone": "phone number",
      "fax": "fax",
      "gender": "gender"
    },
    "custom": {
      "custom1": "custom field no.1",
      "custom25": "custom field no. 25"
    },
    "attachment": {
      "name": "filename.csv",
      "data": "base64 data"
    }
  }
}

Hodnoty

client_id * = API ID naleznete ve svém Mailkit účtu v menu Profil / Integrace / Nastavení API
client_md5 * = MD5 kód naleznete ve svém Mailkit účtu v menu Profil / Integrace / Nastavení API
mailinglist_id * = ID seznamu příjemců do kterého bude příjemce kterému je zpráva zasílána přidán
campaign_id * = ID kampaně která se má odeslat
send_to * = e-mailová adresa příjemce
subject = volitelný předmět zprávy
message_data (v base64) = volitelné tělo zprávy
content (v base64) = proměnný obsah, který se uloží do struktur shared (pro pár název/hodnota), resp. data (pro komplexní struktury a pole). Hodnoty z těchto struktur lze následně použít v šabloně prostřednictvím tagů [% shared.NAZEV_VETVE -%], resp. [% data.NAZEV_STRUKTURY -%]. První úroveň struktur a názvy proměnných jsou do šablon předávány vždy velkými písmeny.

status (v base64) = stav příjemce. Stav může nabývat těchto hodnot:

  • enabled (stav aktivní)
  • disabled (stav neaktivní)
  • unknown (stav neznámý)
  • temporary (stav dočasně nedostupný)
  • permanent (stav trvale nedostupný)
  • unsubscribe (stav odhlášený)

vocative (v base64) = oslovení příjemce
prefix (v base64) = titul příjemce
last_name (v base64) = příjmení příjemce
first_name (v base64) = jméno příjemce
company (v base64) = název společnosti
nick_name (v base64) = přezdívka příjemce
street (v base64) = adresa příjemce
city (v base64) = město příjemce
country (v base64) = země příjemce
state (v base64) = kraj příjemce
zip (v base64) = psč příjemce
mobile (v base64) = mobil příjemce
phone (v base64) = telefon příjemce
fax (v base64) = fax příjemce
gender (v base64) = pohlaví příjemce. Může nabývat hodnot male/female
custom1...25 (v base64) = vlastní pole příjemce č. 1 - 25

Údaje o příjemci, ať už nově předané v rámci API volání, nebo již uložené v záznamu příjemce, jsou dostupné v rámci struktury recipient. Hodnoty z této struktury lze následně použít v šabloně např. [% recipient.EMAIL -%], pro e-mailovou adresu příjemce, nebo [% recipient.GENDER -%] pro pohlaví.

attachement = volitelné přílohy přípojené k e-mailu (Pouze pro transakční kampaně! Pokud se tento parametr použije u běžné kampaně, nedojde k jejímu odeslání!)

- name = název přílohy
- data (v base64) = data přílohy

* povinný parametr

V XML-RPC požadavku musí být vždy zachovány všechny větve struktury, tzn. v případě, že např. nedochází k předávání hlavních detailů příjemce ale pouze custom polí, tak musí být v požadavku prázdná větev hlavních detailů. Pokud tato větev chybí, budou custom pole ignorována neboť jsou mimo očekávanou strukturu.

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

XML 

<?xml version="1.0" encoding="utf-8"?>
<methodResponse>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>data</name>
            <value>
              <i4>12345678</i4>
            </value>
          </member>
          <member>
            <name>data2</name>
            <value>
              <i4>12345</i4>
            </value>
          </member>
          <member>
            <name>data3</name>
            <value>
              <i4>12345678</i4>
            </value>
          </member>
          <member>
            <name>status</name>
            <value>
              <i4>0</i4>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodResponse>

JSON 

{
    "data": "12345678",
    "data2": "12345",
    "data3": "12345678",
    "status": "0"
}

Hodnoty

data = ID nově vloženého nebo nalezeného e-mailu (e-mailové adresy příjemce)
data2 = ID rozesílky
data3 = ID zprávy
status

  • 0 = update (příjemce byl aktualizován)
  • 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 (e-mailová adresa měla špatný formát, příjemce nebyl založen, zpráva nebyla odeslána)
  • 6 = update (příjemce byl aktualizován, ale jeho stav je permanent nebo disabled a na příjemce s tímto stavem není odesíláno)
  • 7 = insert (příjemce byl vložen, ale jeho stav je permanent nebo disabled a na příjemce s tímto stavem není odesíláno)

error_status

  • 0 = volání proběhlo úspešně
  • (1+ = volání selhalo)

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

XML-RPC 

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

JSON 

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

Hodnoty

Invalid ID_mailing_list = neplatné ID seznamu příjemců
Missing ID_mailing_list = chybějící ID seznamu příjemců
Invalid ID_message = neplatné ID kampaně
Missing ID_message = chybějíci ID kampaně
Missing send_to = chybějící příjemce
Missing sender address =  chybějící odesílací adresa
Attachment is not allowed = přílohy jsou povolené pouze u transakčních kampaní
Campaign can not be sent at this moment due to validation process. Try it again after a few seconds = Kampaň nemůže být v tuto chvíli odeslána. Opakujte volání o chvíli později.
Invalid spf = chybné SPF nebo DKIM odesílací adresy
Subject length = příliš krátký předmět zprávy
Reply - reply_to = doména pro odpovědi se neshoduje s doménou odesílatele
Notify - unsubscribe_email = doména adresy pro zasílání notifikací o odhlášení se neshoduje s doménou odesílatele
Missing UL/delivery feed = chybí seznam příjemců/delivery feed
Disabled campaign topic = kampaň používá vypnuté téma
Spam score error = spam skóre kampaně je nad povolenou hranicí