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.

It is always necessary to keep in mind that business messages can only be sent to recipients from whom you have verified and verifiable consent (double-opt-in) or to existing customers.

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:

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

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>ID_user_list</int>
    </value>
   </param>
   <param>
    <value>
      <boolean>confirm</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>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>

Values

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

  • FALSE (default value) = 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

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.


If you want to delete a value in some of the fields (first name, last name, custom fields, ...), you need to send the value _null (Base 64 encoded) in the API call for that field.

* required value

Succesfull call response:

1) CONFIRM = TRUE (–> double opt-in email will be sent)

JSON 

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

XML 

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

Values

Sent subscribe email = double opt-in email has been sent

2) CONFIRM = FALSE (–> double opt-in email will not be sent)

JSON 

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

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>

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)

ID_email = ID of the recipient record (JSON)
data = ID of the recipient record (XML)

Unsuccessful call response:

JSON 

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

XML 

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

Values

Bad email syntax = invalid email address (status: 1)
Unknown domain = email address has unknown domain (status: 1)​
No such email = email address doesn't exist (status: 1)
Unable to validate email​​​​​​​ = email cannot be validated (status: 1)​​​​​​​
Invalid recipient details​​​​​​​ = invalid recipient details (status: 2)​​​​​​​​​​​​​​
Invalid ID_template = invalid template ID​​​​​​​ (status: 3)
Missing ID_mailing_list = missing mailing list ID (status: 3)​​​​​​​​​​​​​​
Invalid ID_mailing_list = invalid mailing list ID (status: 3)​​​​​​​​​​​​​​
Domain blocked​​​​​​​ = recipient's email address domain blocked (status: 4)​​​​​​​
Invalid sending email​​​​​​​ = invalid sending email (status: 5)​​​​​​​
Sending email not available​​​​​​​ = sending email is not available (status: 5)​​​​​​​​​​​​​​
Missing email = missing email address (status: 3)

Error statuses (JSON only)

1 – validation error​​​​​​​
2 – validation error​​​​​​​
3 – invalid parameters​​​​​​​
4 – recipient's domain is blocked​​​​​​​
5 – incorrect sending address setting

To prevent bot interactions, the following DOI email sending limits are set.
  • email address can have a maximum of 3 requests to send a DOI email per minute –> if the limit is exceeded, the API returns a response – "Too many DOI attempts for this email, try again later"
  • maximum of 15 requests to send a DOI e-mail can come from an IP address in 5 minutes –> if the limit is exceeded, the API returns a response - "Too many DOI attempts from this IP, try again later"