XML-RPC request must preserve the format displayed below.
NOTICE: Data must be encoded to Base 64 where indicated.
API call example:
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>
-------recipient, subject and content-------
<param>
<value>
<struct>
<member>
<name>send_to</name>
<value>
<string>email@sample.com</string>
</value>
</member>
<member>
<name>subject</name>
<value>
<string>optional subject</string>
</value>
</member>
<member>
<name>message_data</name>
<value>
<string>optional message body</string>
</value>
</member>
<member>
<name>content</name>
<value>
<struct>
<member>
<name>var1</name>
<value>
<string>variable 1</string>
</value>
</member>
<member>
<name>other_name</name>
<value>
<string>variable 2</string>
</value>
</member>
</struct>
</value>
</member>
</struct>
</value>
</param>
-------main contact details-------
<param>
<value>
<struct>
<member>
<name>status</name>
<value>
<string>status</string>
</value>
</member>
<member>
<name>vocative</name>
<value>
<string>vocative</string>
</value>
</member>
<member>
<name>prefix</name>
<value>
<string>prefix</string>
</value>
</member>
<member>
<name>last_name</name>
<value>
<string>last name</string>
</value>
</member>
<member>
<name>first_name</name>
<value>
<string>first name</string>
</value>
</member>
<member>
<name>reply_to</name>
<value>
<string>reply_to_email</string>
</value>
</member>
<member>
<name>company</name>
<value>
<string>company</string>
</value>
</member>
</struct>
</value>
</param>
-------additional contact details-------
<param>
<value>
<struct>
<member>
<name>nick_name</name>
<value>
<string>nickname</string>
</value>
</member>
<member>
<name>street</name>
<value>
<string>adresa</string>
</value>
</member>
<member>
<name>city</name>
<value>
<string>city</string>
</value>
</member>
<member>
<name>country</name>
<value>
<string>country</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>mobile</name>
<value>
<string>mobile</string>
</value>
</member>
<member>
<name>phone</name>
<value>
<string>phone number</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>
-------custom fields-------
<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>
-------attachment-------
<param>
<value>
<struct>
<member>
<name>url</name>
<value>
<string>url of attachment</string>
</value>
</member>
<member>
<name>name</name>
<value>
<string>filename</string>
</value>
</member>
<member>
<name>data</name>
<value>
<string>base64 data</string>
</value>
</member>
</struct>
</value>
</param>
--------------
</params>
</methodCall>
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": "optional subject",
"message_data": "optional message body",
"content": {
"var1": "variable 1",
"other_name": "variable 2"
}
},
"recipient": {
"status": "status",
"vocative": "vocative",
"prefix": "prefix",
"last_name": "last_name",
"first_name": "first_name",
"reply_to": "reply_to_email",
"company": "company"
},
"contact": {
"nick_name": "nick_name",
"street": "address",
"city": "city",
"country": "country",
"state": "state",
"zip": "zip code",
"mobile": "mobile",
"phone": "phone number",
"fax": "fax",
"gender": "gender"
},
"custom": {
"custom1": "custom field no.1",
"custom25": "custom field no. 25"
},
"attachment": {
"url": "url of attachment",
"name": "name of attachment",
"data": "data of attachment in Base64"
}
}
}
API call example to send a message with 2 or more attachments
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>
-------recipient, subject and content-------
<param>
<value>
<struct>
<member>
<name>send_to</name>
<value>
<string>email@sample.com</string>
</value>
</member>
<member>
<name>subject</name>
<value>
<string>optional subject</string>
</value>
</member>
<member>
<name>message_data</name>
<value>
<string>optional message body</string>
</value>
</member>
<member>
<name>content</name>
<value>
<struct>
<member>
<name>var1</name>
<value>
<string>variable 1</string>
</value>
</member>
<member>
<name>other_name</name>
<value>
<string>variable 2</string>
</value>
</member>
</struct>
</value>
</member>
</struct>
</value>
</param>
-------main contact details-------
<param>
<value>
<struct>
<member>
<name>status</name>
<value>
<string>status</string>
</value>
</member>
<member>
<name>vocative</name>
<value>
<string>vocative</string>
</value>
</member>
<member>
<name>prefix</name>
<value>
<string>prefix</string>
</value>
</member>
<member>
<name>last_name</name>
<value>
<string>last name</string>
</value>
</member>
<member>
<name>first_name</name>
<value>
<string>first name</string>
</value>
</member>
<member>
<name>reply_to</name>
<value>
<string>reply_to_email</string>
</value>
</member>
<member>
<name>company</name>
<value>
<string>company</string>
</value>
</member>
</struct>
</value>
</param>
-------additional contact details-------
<param>
<value>
<struct>
<member>
<name>nick_name</name>
<value>
<string>nickname</string>
</value>
</member>
<member>
<name>street</name>
<value>
<string>adresa</string>
</value>
</member>
<member>
<name>city</name>
<value>
<string>city</string>
</value>
</member>
<member>
<name>country</name>
<value>
<string>country</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>mobile</name>
<value>
<string>mobile</string>
</value>
</member>
<member>
<name>phone</name>
<value>
<string>phone number</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>
-------custom fields-------
<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>
-------attachments-------
<param>
<value>
<array>
<data>
<value>
<struct>
<member>
<name>url</name>
<value>
<string>url of attachment nr. 1</string>
</value>
</member>
<member>
<name>name</name>
<value>
<string>name of attachment nr. 1</string>
</value>
</member>
<member>
<name>data</name>
<value>data of attachment nr. 1 in Base64</value>
</member>
</struct>
</value>
<value>
<struct>
<member>
<name>url</name>
<value>
<string>url of attachment nr. 2</string>
</value>
</member>
<member>
<name>name</name>
<value>
<string>name of attachment nr. 2</string>
</value>
</member>
<member>
<name>data</name>
<value>data of attachment nr. 2 in Base64</value>
</member>
</struct>
</value>
</data>
</array>
</value>
</param>
--------------
</params>
</methodCall>
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": "optional subject",
"message_data": "optional message body",
"content": {
"var1": "variable 1",
"other_name": "variable 2"
}
},
"recipient": {
"status": "status",
"vocative": "vocative",
"prefix": "prefix",
"last_name": "last_name",
"first_name": "first_name",
"reply_to": "reply_to_email",
"company": "company"
},
"contact": {
"nick_name": "nick_name",
"street": "address",
"city": "city",
"country": "country",
"state": "state",
"zip": "zip code",
"mobile": "mobile",
"phone": "phone number",
"fax": "fax",
"gender": "gender"
},
"custom": {
"custom1": "custom field no.1",
"custom25": "custom field no. 25"
},
"attachment": [
{
"url": "URL of attachment nr. 1",
"name": "name of attachment nr. 1",
"data": "data of attachment nr. 1 (base64)"
},
{
"url": "URL of attachment nr. 2",
"name": "name of attachment nr. 2",
"data": "data of attachment nr. 2 (base64)"
}
]
}
}
Values
client_id * = client 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, where will be the recipient added
campaign_id * = ID of campaign
send_to * = e-mail address of recipient
subject = optional message subject
message_data (base64) = optional message body
content (base64) = variable content that gets stored in structures named shared (for key/value pairs), resp. data (for complex structures and arrays). Data from these structures can later be used in template using tags [% shared.VARIABLE_NAME -%], resp. [% data.STRUCTURE_NAME -%]. The first level of structure names and variable names are always passed to templates in uppercase.
status (base64) = status of recipient. Possible values:
- enabled
- disabled
- unknown
- temporary
- permanent
- unsubscribe
vocative (base64) = recipient's vocative
prefix (base64) = recipient's title
last_name (base64) = recipient's last name
first_name (base64) = recipient's first name
company (base64) = recipient's company name
nick_name (base64) = recipient's nickname
street (base64) = recipient's street
city (base64) = recipient's city
country (base64) = recipient's country
state (base64) = recipient's state
zip (base64) = recipient's ZIP code
mobile (base64) = recipient's mobile phone (international format required for SMS delivery)
phone (base64) = recipient's telephone
fax (base64) = recipient's fax
gender (base64) = recipient's gender (values - male/female)
custom1...25 (base64) = recipient's custom fields 1 - 25
Recipient data, whether newly passed within the API call or already stored in the recipient record, is available within the recipient structure. Values from this structure can then be used in a template such as [% recipient.EMAIL -%], for the recipient's email address, or [% recipient.GENDER -%] for gender...
attachment = optional attachment of the message (for transactional campaigns only! If this parameter is used for a standard campaign, it will not be sent!):
- url = attachment URL
- name = attachment filename
- data (base64) = attachment data
* required parameter
The structure of the XML request must preserve all branches. For example if the recipient additional details branch is missing but the custom fields branch is present it will be ingored as it is out of order.
Successful call response:
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>
JSON
{
"data": "12345678",
"data2": "12345",
"data3": "12345678",
"status": "0"
}
Values
data = ID of newly inserted or found e-mail
data2 = ID send
data3 = ID send message
status
- 0 = update (recipient data updated)
- 1 = insert (recipient added)
- 2 = insert (recipient is unsubscribed with status unsubscribed)
- 3 = update (recipient is unsubscribed with status unsubscribed)
- 4 = fault (invalid e-mail address format, recipient has been added but message not sent)
- 6 = update (recipient updated but status is permanently undelivarable or disabled and message was not sent)
- 7 = insert (recipient added but status is permanently undeliverable or disabled and message was not sent)
error_status
- 0 = succesfull request
- (1+ = unsuccesfull request)
Unsuccesfull call response:
XML
<?xml version="1.0" encoding="utf-8"?>
<methodResponse>
<params>
<param>
<value>
<string>Missing send_to</string>
</value>
</param>
</params>
</methodResponse>
JSON
{
"error": "Missing ID_mailing_list",
"error_status": 1
}
Values
Invalid ID_mailing_list = invalid mailing list ID
Missing ID_mailing_list = missing mailing list ID
Invalid ID_message = invalid campaign ID
Missing ID_message = missing campaign ID
Missing send_to = missing recipient
Missing sender address = sender address is not assigned to the campaign
Attachment is not allowed = attachments are allowed for transactional campaigns only
Campaign can not be sent at this moment due to validation process. Try it again after a few seconds = Campaign delivery could not be queued. Retry request later.
Invalid spf = invalid SPF od DKIM settings of the sender address
Subject length = Message subject too short
Reply - reply_to = reply-to domain doesn't match the sender domain
Notify - unsubscribe_email = unsubscribe notification domain doesn't match the sender domain
Missing UL/delivery feed = missing mailing list/delivery feed
Disabled campaign topic = campaign uses disabled topic
Spam score error = spam score exceeded
