ResourcesAPI documentation

mailkit.mailinglist.adduser

Function mailkit.mailinglist.adduser is used to add the new recipient to the mailing list, or to update existing recipient in the list.

This API funcion is not suitable for batch import of recipients but for an immediate single recipient record insert or update. To synchronize data with 3rd party systems we recommend using data sources that allow for simpler, more flexible and less time consuming implementation.

API request must be sent in the format displayed below. See the example API call in PERL. Data must be Base 64 encoded. Parameters are split into multiple branches order of which MUST be preserved.

API call example:

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>mailinglist_id</int>
    </value>
   </param>
   <param>
    <value>
      <boolean>double opt-in</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>status</name>
        <value>
          <string>ZW5hYmxlZA==</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>

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=",
            "status": "ZW5hYmxlZA==",
            "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"
        }
    }
}

Values

client_id * = API ID can be found in your Mailkit account's menu Profile / Integration / API settings.
client_md5 * = MD5 code can be found in your Mailkit account's menu Profile / Integration / API settings.
mailinglist_id * = ID of mailing list
confirm * = send opt-in confirmation mail. Following values are allowed:

FALSE = no confirmation mail sent (recipient will be added immediately to the list) if ip_src & form_url (see params branch) are passed. The IP and URL information will be stored in our consent database and if the recipient was previously unsubscribed the address will be reactivated. If ip_src & form_url params are not passed the recipient will be added to the list but without consent as if a single opt-in method was used. Previously unsubscribed address will not be reactivated.
TRUE = confirmation mail will be sent (recipient will be added once he confirms by clicking the link in the mail). Any IP_src & form_url values will be ignored. Confirmation email will not be sent to a recipient with an existing valid consent - in such case the recipient will be immediately added to the list.

Branch "personal"

email ^{(Base 64 encoded)} * = recipients e-mail address
ID_template ^{(Base 64 encoded)} = ID of the template with custom subscribe email / subscribe page. Used when double opt-in is TRUE. If template ID is not passed the default templates are being used.
email_from ^{(Base 64 encoded)} = e-mail address used as a sender of the confirmation email
name_from ^{(Base 64 encoded)} = name of the sender of the confirmation email
return_url ^{(Base 64 encoded)} = return url after confirmation is completed
first_name ^{(Base 64 encoded)} = first name of recipient
last_name ^{(Base 64 encoded)} = last name of recipient
company ^{(Base 64 encoded)} = company of recipient
prefix ^{(Base 64 encoded)} = title of recipient
vocative ^{(Base 64 encoded)} = salutation of recipient
reply_to ^{(Base 64 encoded)} = e-mail address of recipient for reply to
status ^{(Base 64 encoded)} = status of recipient. Possible values:

enabled
disabled
unknown
temporary
permanent
unsubscribe

Branch "address"

nick_name ^{(Base 64 encoded)} = nick of recipient
gender ^{(Base 64 encoded)} = gender of recipient. Possible values: male/female; m/f; muz/zena; M/F
phone ^{(Base 64 encoded)} = phone of recipient
mobile ^{(Base 64 encoded)} = mobile of recipient
fax ^{(Base 64 encoded)} = fax of recipient
street ^{(Base 64 encoded)} = address of recipient
city ^{(Base 64 encoded)} = city of recipient
state ^{(Base 64 encoded)} = state of recipient
country ^{(Base 64 encoded)} = country of recipient
zip ^{(Base 64 encoded)} = ZIP of recipient

Branch "custom"

custom1 ^{(Base 64 encoded)} = custom field of recipient n. 1 Total nuber of custom fields is 25.

Branch "params"

ip_src - IP address of the subscriber (subscription confirmation)
form_url - url address of the form used for submission of subscription data

Please note, that requests with confirm FALSE and no ip_src and form_url will be treated by the system as recipients without consent. If an unsubscribed recipient is requested to be added with confirm set to FALSE and no consent data provided, it will result in an consent confirmation email to be sent as a proof of consent is required.

* required value

Succesfull call response:

XML

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

JSON

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

Values

Sent subscribe email = confirmation e-mail has been sent

or for calls with parameter confirm set to FALSE:

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>

JSON

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

Values

status = status of recipient record insert/update. Possible values:

0 = update (recipient updated)
1 = insert (recipient inserted)
2 = insert (recipient inserted but unsubscribed)
3 = update (recipient updated but unsubscribed)
4 = fault (invalid / blocked e-mail, record not insered)

data = ID of the recipient record

Unsuccessful call response:

XML

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

JSON

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

Values

Missing ID_mailing_list = missing mailing list ID
Invalid ID_mailing_list = invalid mailing list ID
Missing email = missing email address
Bad email syntax = invalid email address
Invalid ID_template = invalid template ID