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.

Ukázka API volání

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": "volitelný předmět",
      "message_data": "volitelné tělo zprávy (v base64)",
      "content": {
        "variable1": "cHJvbcSbbm7DoSAx",
        "jiny_nazev": "cHJvbcSbbm7DoSAy"
      }
    },
    "recipient": {
      "status": "dW5rbm93bg==",
      "vocative": "b3Nsb3ZlbsOt",
      "prefix": "dGl0dWw=",
      "last_name": "cMWZw61qbWVuw60=",
      "first_name": "am3DqW5v",
      "reply_to": "ZW1haWwyQGVtYWlsLmNvbQ==",
      "company": "c3BvbGXEjW5vc3Q="
    },
    "contact": {
      "nick_name": "cMWZZXpkw612a2E=",
      "street": "YWRyZXNh",
      "city": "bcSbc3Rv",
      "country": "emVtxJs=",
      "state": "a3Jhag==",
      "zip": "MTExNTA=",
      "mobile": "KzQyMDEyMzQ1Njc4OQ==",
      "phone": "KzQyMDExMjIzMzQ0NQ==",
      "fax": "KzQyMDk4NzY1NDMyMQ==",
      "gender": "bWFsZQ=="
    },
    "custom": {
      "custom1": "dmxhc3Ruw60gcG9sZSBwxZnDrWplbWNlIMSNLiAx",
      "custom25": "dmxhc3Ruw60gcG9sZSBwxZnDrWplbWNlIMSNLiAyNQ=="
    },
    "attachment": {
      "url": "url přílohy",
      "name": "název přílohy",
      "data": "data přílohy (v base64)"
    }
  }
}

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 (v Base64)</string>
            </value>
          </member>
          <member>
            <name>content</name>
            <value>
              <struct>
                <member>
                  <name>var1</name>
                  <value>
                    <string>cHJvbcSbbm7DoSAx</string>
                  </value>
                </member>
                <member>
                  <name>jiny_nazev</name>
                  <value>
                    <string>cHJvbcSbbm7DoSAy</string>
                  </value>
                </member>
              </struct>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------oslovení, jméno, atp.-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>status</name>
            <value>
              <string>dW5rbm93bg==</string>
            </value>
          </member>
          <member>
            <name>vocative</name>
            <value>
              <string>b3Nsb3ZlbsOt</string>
            </value>
          </member>
          <member>
            <name>prefix</name>
            <value>
              <string>dGl0dWw=</string>
            </value>
          </member>
          <member>
            <name>last_name</name>
            <value>
              <string>cMWZw61qbWVuw60=</string>
            </value>
          </member>
          <member>
            <name>first_name</name>
            <value>
              <string>am3DqW5v</string>
            </value>
          </member>
          <member>
            <name>reply_to</name>
            <value>
              <string>ZW1haWwyQGVtYWlsLmNvbQ==</string>
            </value>
          </member>
          <member>
            <name>company</name>
            <value>
              <string>c3BvbGXEjW5vc3Q=</string>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------přezdívka, adresa atp.-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>nick_name</name>
            <value>
              <string>cMWZZXpkw612a2E=</string>
            </value>
          </member>
          <member>
            <name>street</name>
            <value>
              <string>YWRyZXNh</string>
            </value>
          </member>
          <member>
            <name>city</name>
            <value>
              <string>bcSbc3Rv</string>
            </value>
          </member>
          <member>
            <name>country</name>
            <value>
              <string>emVtxJs=</string>
            </value>
          </member>
          <member>
            <name>state</name>
            <value>
              <string>a3Jhag==</string>
            </value>
          </member>
          <member>
            <name>zip</name>
            <value>
              <string>MTExNTA=</string>
            </value>
          </member>
          <member>
            <name>mobile</name>
            <value>
              <string>KzQyMDEyMzQ1Njc4OQ==</string>
            </value>
          </member>
          <member>
            <name>phone</name>
            <value>
              <string>KzQyMDExMjIzMzQ0NQ==</string>
            </value>
          </member>
          <member>
            <name>fax</name>
            <value>
              <string>KzQyMDk4NzY1NDMyMQ==</string>
            </value>
          </member>
          <member>
            <name>gender</name>
            <value>
              <string>bWFsZQ==</string>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------vlastní pole-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>custom1</name>
            <value>
              <string>dmxhc3Ruw60gcG9sZSBwxZnDrWplbWNlIMSNLiAx</string>
            </value>
          </member>
          <member>
            <name>custom25</name>
            <value>
              <string>dmxhc3Ruw60gcG9sZSBwxZnDrWplbWNlIMSNLiAyNQ==</string>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------příloha-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>url</name>
            <value>
              <string>url přílohy</string>
            </value>
          </member>
          <member>
            <name>name</name>
            <value>
              <string>nazev</string>
            </value>
          </member>
          <member>
            <name>data</name>
            <value>
              <string>data přílohy (v base64)</string>
            </value>
          </member>
        </struct>
      </value>
    </param>

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

Zápis volání pro odeslání zprávy se 2 a více přílohami

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": "volitelný předmět",
      "message_data": "volitelné tělo zprávy (v base64)",
      "content": {
        "variable1": "cHJvbcSbbm7DoSAx",
        "jiny_nazev": "cHJvbcSbbm7DoSAy"
      }
    },
    "recipient": {
      "status": "dW5rbm93bg==",
      "vocative": "b3Nsb3ZlbsOt",
      "prefix": "dGl0dWw=",
      "last_name": "cMWZw61qbWVuw60=",
      "first_name": "am3DqW5v",
      "reply_to": "ZW1haWwyQGVtYWlsLmNvbQ==",
      "company": "c3BvbGXEjW5vc3Q="
    },
    "contact": {
      "nick_name": "cMWZZXpkw612a2E=",
      "street": "YWRyZXNh",
      "city": "bcSbc3Rv",
      "country": "emVtxJs=",
      "state": "a3Jhag==",
      "zip": "MTExNTA=",
      "mobile": "KzQyMDEyMzQ1Njc4OQ==",
      "phone": "KzQyMDExMjIzMzQ0NQ==",
      "fax": "KzQyMDk4NzY1NDMyMQ==",
      "gender": "bWFsZQ=="
    },
    "custom": {
      "custom1": "dmxhc3Ruw60gcG9sZSBwxZnDrWplbWNlIMSNLiAx",
      "custom25": "dmxhc3Ruw60gcG9sZSBwxZnDrWplbWNlIMSNLiAyNQ=="
    },
    "attachment": [
    {
      "url": "url přílohy č. 1",
      "name": "název přílohy č. 1",
      "data": "data přílohy č. 1 (v base64)"
    },
    {
      "url": "url přílohy č. 2",
      "name": "název přílohy č. 2",
      "data": "data přílohy č. 2 (v base64)"
    }
    ]
  }
}

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 (v base64)</string>
            </value>
          </member>
          <member>
            <name>content</name>
            <value>
              <struct>
                <member>
                  <name>var1</name>
                  <value>
                    <string>cHJvbcSbbm7DoSAx</string>
                  </value>
                </member>
                <member>
                  <name>jiny_nazev</name>
                  <value>
                    <string>cHJvbcSbbm7DoSAy</string>
                  </value>
                </member>
              </struct>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------oslovení, jméno, atp.-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>status</name>
            <value>
              <string>dW5rbm93bg==</string>
            </value>
          </member>
          <member>
            <name>vocative</name>
            <value>
              <string>b3Nsb3ZlbsOt</string>
            </value>
          </member>
          <member>
            <name>prefix</name>
            <value>
              <string>dGl0dWw=</string>
            </value>
          </member>
          <member>
            <name>last_name</name>
            <value>
              <string>cMWZw61qbWVuw60=</string>
            </value>
          </member>
          <member>
            <name>first_name</name>
            <value>
              <string>am3DqW5v</string>
            </value>
          </member>
          <member>
            <name>reply_to</name>
            <value>
              <string>ZW1haWwyQGVtYWlsLmNvbQ==</string>
            </value>
          </member>
          <member>
            <name>company</name>
            <value>
              <string>c3BvbGXEjW5vc3Q=</string>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------přezdívka, adresa atp.-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>nick_name</name>
            <value>
              <string>cMWZZXpkw612a2E=</string>
            </value>
          </member>
          <member>
            <name>street</name>
            <value>
              <string>YWRyZXNh</string>
            </value>
          </member>
          <member>
            <name>city</name>
            <value>
              <string>bcSbc3Rv</string>
            </value>
          </member>
          <member>
            <name>country</name>
            <value>
              <string>emVtxJs=</string>
            </value>
          </member>
          <member>
            <name>state</name>
            <value>
              <string>a3Jhag==</string>
            </value>
          </member>
          <member>
            <name>zip</name>
            <value>
              <string>MTExNTA=</string>
            </value>
          </member>
          <member>
            <name>mobile</name>
            <value>
              <string>KzQyMDEyMzQ1Njc4OQ==</string>
            </value>
          </member>
          <member>
            <name>phone</name>
            <value>
              <string>KzQyMDExMjIzMzQ0NQ==</string>
            </value>
          </member>
          <member>
            <name>fax</name>
            <value>
              <string>KzQyMDk4NzY1NDMyMQ==</string>
            </value>
          </member>
          <member>
            <name>gender</name>
            <value>
              <string>bWFsZQ==</string>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------vlastní pole-------
    
    <param>
      <value>
        <struct>
          <member>
            <name>custom1</name>
            <value>
              <string>dmxhc3Ruw60gcG9sZSBwxZnDrWplbWNlIMSNLiAx</string>
            </value>
          </member>
          <member>
            <name>custom25</name>
            <value>
              <string>dmxhc3Ruw60gcG9sZSBwxZnDrWplbWNlIMSNLiAyNQ==</string>
            </value>
          </member>
        </struct>
      </value>
    </param>
    
-------přílohy-------
    
    <param>
      <value>
         <array>
             <data>
                 <value>
                     <struct>
                         <member>
                             <name>url</name>
                             <value>
                                 <string>url přílohy č. 1</string>
                             </value>
                         </member>
                         <member>
                             <name>name</name>
                             <value>
                                 <string>název přílohy č. 1</string>
                             </value>
                         </member>
                         <member>
                             <name>data</name>
                             <value>data přílohy č. 1 (v base64)</value>
                         </member>
                     </struct>
                 </value>
                 <value>
                     <struct>
                         <member>
                             <name>url</name>
                             <value>
                                 <string>url přílohy č. 2</string>
                             </value>
                         </member>
                         <member>
                             <name>name</name>
                             <value>
                                 <string>název přílohy č. 2</string>
                             </value>
                         </member>
                         <member>
                             <name>data</name>
                             <value>data přílohy č. 2 (v base64)</value>
                         </member>
                     </struct>
                 </value>
             </data>
         </array>
      </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
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
reply_to (v base64) = e-mailová adresa pro odpovědi
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í.

attachment = volitelná příloha kampaně. Je dvojí možnost vložení - odkázání na url adresu, kde je příloha umístěna, nebo zaslání dat přílohy. Přílohu je možné přiložit pouze u transakční kampaně! Pokud bude příloha použita u netransakční zprávy, nedojde k odeslání zprávy!

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

Jak je uvedeno výše, přílohu můžete odeslat buď tak, že uvedete URL, kde je uložena, typicky např. někde na FTP, nebo můžete data přílohy base64 enkódovat a použít v API volání jako hodnotu pro "data". Vždy je však potřeba použít buď "url", nebo "data". Pokud pošlete hodnoty v obou parametrech ("url" i "data"), má přednost hodnota pro "url" a hodnota pro "data" bude ignorována.

Název přílohy (name):

  • pokud vyplníte "url", např. použijete hodnotu - "https://cesta_k_souboru/priloha_2.pdf" - a nevyplníte hodnotu pro "name", bude soubor přílohy v e-mailu pojmenován "priloha_2.pdf"
  • pokud vyplníte "url", např. použijete hodnotu - "https://cesta_k_souboru/priloha_2.pdf" - a zároveň vyplníte hodnotu pro "name" - např. "Název poslaný přes API", bude soubor přílohy v e-mailu pojmenován "Název poslaný přes API"
  • pokud vyplníte "data" (tzn. pošlete base64 enkódovaná data přílohy) a zároveň vyplníte hodnotu pro "name" - např. "Název poslaný přes API", bude soubor přílohy v e-mailu pojmenován "Název poslaný přes API"
  • pokud vyplníte "data" (tzn. pošlete base64 enkódovaná data přílohy) a zároveň nevyplníte hodnotu pro "name", bude soubor přílohy v e-mailu pojmenován "unnamed"

* povinný parametr

 

POZOR! 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í:

JSON 

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

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>

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 (zpráva byla odeslána a příjemce byl v seznamu příjemců aktualizován)
  • 1 = insert (zpráva byla odeslána a příjemce byl úspěšně vložen do seznamu příjemců)
  • 2 = insert (zpráva nebyla odeslána (příjemce je odhlášený) a příjemce byl vložen do seznamu příjemců)
  • 3 = update (zpráva nebyla odeslána (příjemce je odhlášený) a příjemce byl v seznamu příjemců aktualizován)
  • 4 = fault ( zpráva nebyla odeslána, protože e-mailová adresa měla špatný formát, příjemce nebyl vložen do seznamu příjemců)
  • 6 = update (zpráva nebyla odeslána (příjemce má stav permanent/disabled) a příjemce byl v seznamu příjemců aktualizován)
  • 7 = insert (zpráva nebyla odeslána (příjemce má stav permanent/disabled) a příjemce byl vložen do seznamu příjemců)

error_status

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

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

JSON 

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

XML 

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

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í