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>confirm</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
confirm * = 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"

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 (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

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)

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