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>Template ID</string></value>
       </member>
       <member>
        <name>return_url</name>
        <value>
          <string>http://www....</string></value>
       </member>
       <member>
        <name>vocative</name>
        <value>
          <string>vocative</string>
        </value>
       </member>
       <member>
        <name>prefix</name>
        <value>
          <string>titul</string>
        </value>
       </member>
       <member>
        <name>first_name</name>
        <value>
          <string>First name</string>
        </value>
       </member>
       <member>
        <name>last_name</name>
        <value>
          <string>Last name</string>
        </value>
       </member>
       <member>
        <name>status</name>
        <value>
          <string>enabled</string>
        </value>
       </member>
       <member>
        <name>email</name>
        <value>
          <string>example@example.com</string>
        </value>
       </member>
       <member>
        <name>reply_to</name>
        <value>
          <string>reply-to</string>
        </value>
       </member>
       <member>
        <name>company</name>
        <value>
          <string>company</string>
        </value>
       </member>
      </struct>
    </value>
   </param>
   <param>
    <value>
      <struct>
       <member>
        <name>nick_name</name>
        <value>
          <string>nick name</string>
        </value>
       </member>
       <member>
        <name>country</name>
        <value>
          <string>country</string>
        </value>
       </member>
       <member>
        <name>adresa</name>
        <value>
          <string>street</string>
        </value>
       </member>
       <member>
        <name>state</name>
        <value>
          <string>state</string>
        </value>
       </member>
       <member>
        <name>zip</name>
        <value>
          <string>zip code</string>
        </value>
       </member>
       <member>
        <name>city</name>
        <value>
          <string>city</string>
        </value>
       </member>
       <member>
        <name>mobile</name>
        <value>
          <string>mobile</string>
        </value>
       </member>
       <member>
        <name>phone</name>
        <value>
          <string>phone</string>
        </value>
       </member>
       <member>
        <name>fax</name>
        <value>
          <string>fax</string>
        </value>
       </member>
       <member>
        <name>gender</name>
        <value>
          <string>gender</string>
        </value>
       </member>
      </struct>
    </value>
   </param>
   <param>
    <value>
      <struct>
       <member>
        <name>custom1</name>
        <value>
          <string>custom field no. 1</string>
        </value>
       </member>
       <member>
        <name>custom25</name>
        <value>
          <string>custom field no. 25</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
double opt-in * = send opt-in confirmation mail. Following values are allowed:

  • FALSE = no confirmation mail sent (recipient will be added immediately to the list)
  • TRUE = confirmation mail will be sent (recipient will be added once he confirms by clicking the link in the mail)

Branch "personal"

first_name (v Base 64) = first name of recipient
last_name (v Base 64) = last name of recipient
company (v Base 64) = company of recipient
prefix (v Base 64) = title of recipient
vocative (v Base 64) = salutation of recipient
reply_to (v Base 64) = e-mail address of recipient for reply to
status (v Base 64) = status of recipient. Possible values:

  • enabled
  • disabled
  • unknown
  • temporary
  • permanent
  • unsubscribe

Branch "address"

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

Branch "custom"

custom1 (v Base 64) = custom field of recipient n. 1 Total nuber of custom fields is 25.

Branch "params"

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

* 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

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
}

Hodnoty

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)

For the values 2 and 3 you can call mailkit.email.revalidate to request a revalidation of recipient consent to receive emails.

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