XML-RPC request must preserve the format displayed below.
NOTICE: Data must be encoded to Base 64 where indicated.
API call example:
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": "b3B0aW9uYWwgbWVzc2FnZSBib2R5",
"content": {
"var1": "dmFyaWFibGUgMQ==",
"other_name": "dmFyaWFibGUgMg=="
}
},
"recipient": {
"status": "dW5rbm93bg==",
"vocative": "dm9jYXRpdmU=",
"prefix": "cHJlZml4",
"last_name": "bGFzdCBuYW1l",
"first_name": "Zmlyc3QgbmFtZQ==",
"reply_to": "ZW1haWwyQHNhbXBsZS5jb20=",
"company": "Y29tcGFueQ=="
},
"contact": {
"nick_name": "bmlja25hbWU=",
"street": "YWRkcmVzcw==",
"city": "Y2l0eQ==",
"country": "Y291bnRyeQ==",
"state": "c3RhdGU=",
"zip": "emlwIGNvZGU=",
"mobile": "KzQ0MjIyNTU1ODg4",
"phone": "KzQ0MTExNDQ0Nzc3",
"fax": "KzQ0MzMzNjY2OTk5",
"gender": "bWFsZQ=="
},
"custom": {
"custom1": "Y3VzdG9tIGZpZWxkIG5vLjE=",
"custom25": "Y3VzdG9tIGZpZWxkIG5vLjI1"
},
"attachment": {
"url": "url of attachment",
"name": "name of attachment",
"data": "data of attachment in Base64"
}
}
}
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>b3B0aW9uYWwgbWVzc2FnZSBib2R5</string>
</value>
</member>
<member>
<name>content</name>
<value>
<struct>
<member>
<name>variable_1</name>
<value>
<string>dmFyaWFibGUgMQ==</string>
</value>
</member>
<member>
<name>other_name</name>
<value>
<string>dmFyaWFibGUgMg==</string>
</value>
</member>
</struct>
</value>
</member>
</struct>
</value>
</param>
-------main contact details-------
<param>
<value>
<struct>
<member>
<name>status</name>
<value>
<string>dW5rbm93bg==</string>
</value>
</member>
<member>
<name>vocative</name>
<value>
<string>dm9jYXRpdmU=</string>
</value>
</member>
<member>
<name>prefix</name>
<value>
<string>cHJlZml4</string>
</value>
</member>
<member>
<name>last_name</name>
<value>
<string>bGFzdCBuYW1l</string>
</value>
</member>
<member>
<name>first_name</name>
<value>
<string>Zmlyc3QgbmFtZQ==</string>
</value>
</member>
<member>
<name>reply_to</name>
<value>
<string>ZW1haWwyQHNhbXBsZS5jb20=</string>
</value>
</member>
<member>
<name>company</name>
<value>
<string>Y29tcGFueQ==</string>
</value>
</member>
</struct>
</value>
</param>
-------additional contact details-------
<param>
<value>
<struct>
<member>
<name>nick_name</name>
<value>
<string>bmlja25hbWU=</string>
</value>
</member>
<member>
<name>street</name>
<value>
<string>YWRkcmVzcw==</string>
</value>
</member>
<member>
<name>city</name>
<value>
<string>Y2l0eQ==</string>
</value>
</member>
<member>
<name>country</name>
<value>
<string>Y291bnRyeQ==</string>
</value>
</member>
<member>
<name>state</name>
<value>
<string>c3RhdGU=</string>
</value>
</member>
<member>
<name>zip</name>
<value>
<string>emlwIGNvZGU=</string>
</value>
</member>
<member>
<name>mobile</name>
<value>
<string>KzQ0MjIyNTU1ODg4</string>
</value>
</member>
<member>
<name>phone</name>
<value>
<string>KzQ0MTExNDQ0Nzc3</string>
</value>
</member>
<member>
<name>fax</name>
<value>
<string>KzQ0MzMzNjY2OTk5</string>
</value>
</member>
<member>
<name>gender</name>
<value>
<string>bWFsZQ==</string>
</value>
</member>
</struct>
</value>
</param>
-------custom fields-------
<param>
<value>
<struct>
<member>
<name>custom1</name>
<value>
<string>Y3VzdG9tIGZpZWxkIG5vLjE=</string>
</value>
</member>
<member>
<name>custom25</name>
<value>
<string>Y3VzdG9tIGZpZWxkIG5vLjI1</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>data (base64)</string>
</value>
</member>
</struct>
</value>
</param>
--------------
</params>
</methodCall>
API call example to send a message with 2 or more attachments
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": "b3B0aW9uYWwgbWVzc2FnZSBib2R5",
"content": {
"var1": "dmFyaWFibGUgMQ==",
"other_name": "dmFyaWFibGUgMg=="
}
},
"recipient": {
"status": "dW5rbm93bg==",
"vocative": "dm9jYXRpdmU=",
"prefix": "cHJlZml4",
"last_name": "bGFzdCBuYW1l",
"first_name": "Zmlyc3QgbmFtZQ==",
"reply_to": "ZW1haWwyQHNhbXBsZS5jb20=",
"company": "Y29tcGFueQ=="
},
"contact": {
"nick_name": "bmlja25hbWU=",
"street": "YWRkcmVzcw==",
"city": "Y2l0eQ==",
"country": "Y291bnRyeQ==",
"state": "c3RhdGU=",
"zip": "emlwIGNvZGU=",
"mobile": "KzQ0MjIyNTU1ODg4",
"phone": "KzQ0MTExNDQ0Nzc3",
"fax": "KzQ0MzMzNjY2OTk5",
"gender": "bWFsZQ=="
},
"custom": {
"custom1": "Y3VzdG9tIGZpZWxkIG5vLjE=",
"custom25": "Y3VzdG9tIGZpZWxkIG5vLjI1"
},
"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)"
}
]
}
}
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>b3B0aW9uYWwgbWVzc2FnZSBib2R5</string>
</value>
</member>
<member>
<name>content</name>
<value>
<struct>
<member>
<name>variable_1</name>
<value>
<string>dmFyaWFibGUgMQ==</string>
</value>
</member>
<member>
<name>other_name</name>
<value>
<string>dmFyaWFibGUgMg==</string>
</value>
</member>
</struct>
</value>
</member>
</struct>
</value>
</param>
-------main contact details-------
<param>
<value>
<struct>
<member>
<name>status</name>
<value>
<string>dW5rbm93bg==</string>
</value>
</member>
<member>
<name>vocative</name>
<value>
<string>dm9jYXRpdmU=</string>
</value>
</member>
<member>
<name>prefix</name>
<value>
<string>cHJlZml4</string>
</value>
</member>
<member>
<name>last_name</name>
<value>
<string>bGFzdCBuYW1l</string>
</value>
</member>
<member>
<name>first_name</name>
<value>
<string>Zmlyc3QgbmFtZQ==</string>
</value>
</member>
<member>
<name>reply_to</name>
<value>
<string>ZW1haWwyQHNhbXBsZS5jb20=</string>
</value>
</member>
<member>
<name>company</name>
<value>
<string>Y29tcGFueQ==</string>
</value>
</member>
</struct>
</value>
</param>
-------additional contact details-------
<param>
<value>
<struct>
<member>
<name>nick_name</name>
<value>
<string>bmlja25hbWU=</string>
</value>
</member>
<member>
<name>street</name>
<value>
<string>YWRkcmVzcw==</string>
</value>
</member>
<member>
<name>city</name>
<value>
<string>Y2l0eQ==</string>
</value>
</member>
<member>
<name>country</name>
<value>
<string>Y291bnRyeQ==</string>
</value>
</member>
<member>
<name>state</name>
<value>
<string>c3RhdGU=</string>
</value>
</member>
<member>
<name>zip</name>
<value>
<string>emlwIGNvZGU=</string>
</value>
</member>
<member>
<name>mobile</name>
<value>
<string>KzQ0MjIyNTU1ODg4</string>
</value>
</member>
<member>
<name>phone</name>
<value>
<string>KzQ0MTExNDQ0Nzc3</string>
</value>
</member>
<member>
<name>fax</name>
<value>
<string>KzQ0MzMzNjY2OTk5</string>
</value>
</member>
<member>
<name>gender</name>
<value>
<string>bWFsZQ==</string>
</value>
</member>
</struct>
</value>
</param>
-------custom fields-------
<param>
<value>
<struct>
<member>
<name>custom1</name>
<value>
<string>Y3VzdG9tIGZpZWxkIG5vLjE=</string>
</value>
</member>
<member>
<name>custom25</name>
<value>
<string>Y3VzdG9tIGZpZWxkIG5vLjI1</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 (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 (base64)</value>
</member>
</struct>
</value>
</data>
</array>
</value>
</param>
--------------
</params>
</methodCall>
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
reply_to (base64) = email address for replies
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 campaign attachment. There are two options how to add attachment(s) - referring to the url address where the attachment is located, or sending attachment data (base64 encoded). The attachment can only be attached to a transactional campaigns! If the attachment is used for a non-transactional message, the message will not be sent!
- url = attachment URL
- name = attachment filename
- data (base64) = attachment data
As mentioned above, you can send the attachment either by providing the URL where it is stored, eg on FTP, or you can base64 encode the attachment data and use it in the API call as the value for "data". However, you always need to use either "url" or "data". If you send values in both parameters ("url" and "data"), the value for "url" takes precedence and the value for "data" is ignored.
Attachment name (name):
- if you fill in "url", e.g. use the value - "https://path_to_file/attachment_2.pdf" - and do not fill in the value for "name", the attachment file in the e-mail will be named "attachment_2.pdf"
- if you fill in "url", e.g. use the value - "https://path_to_file/attachment_2.pdf" - and at the same time fill in the value for "name" - e.g. "Name sent via API", the attachment file in the email will be named "Name sent via API"
- if you fill in "data" (i.e. send base64 encoded attachment data) and at the same time fill in a value for "name" - eg "Name sent via API", the attachment file in the email will be named "Name sent via API"
- if you fill in "data" (ie send base64 encoded attachment data) and do not fill in a value for "name", the attachment file will be named "unnamed" in the email
* 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:
JSON
{
"data": "12345678",
"data2": "12345",
"data3": "12345678",
"status": "0"
}
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>
Values
data = ID of newly inserted or found e-mail
data2 = ID send
data3 = ID send message
status
- 0 = update (the message was sent and the recipient was updated in the list of recipients)
- 1 = insert (the message was sent and the recipient was successfully inserted into the recipient list)
- 2 = insert (the message was not sent (the recipient is unsubscribed) and the recipient was added to the recipient list)
- 3 = update (the message was not sent (the recipient is unsubscribed) and the recipient was updated in the recipient list)
- 4 = fault (the message was not sent because the email address was in the wrong format, the recipient was not added to the list of recipients)
- 6 = update (the message was not sent (the recipient has the status permanent/disabled) and the recipient was updated in the list of recipients)
- 7 = insert (the message was not sent (the recipient has permanent/disabled status) and the recipient was added to the list of recipients)
error_status
- 0 = succesfull request
- (1+ = unsuccesfull request)
Unsuccesfull call response:
JSON
{
"error": "Missing ID_mailing_list",
"error_status": 1
}
XML
<?xml version="1.0" encoding="utf-8"?>
<methodResponse>
<params>
<param>
<value>
<string>Missing send_to</string>
</value>
</param>
</params>
</methodResponse>
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
