Support

API Documentation

Mail Blaze API Documentation

The REST API allows you to integrate your applications with your Mail Blaze account by providing an interface to send and retrieve data between them.


Create Your API Key

The first step is to create an API key.

  1. Log into your Mail Blaze account
  2. Click on your account name > API Keys
  3. On the API KEYS page, click the GENERATE NEW button. A new API key should appear.
  4. Click on the API key
  5. Copy the Public key. This is the key you'll use to connect to the API


Using the API Tool

Mail Blaze provides an interactive tool to test your HTTP requests. To use this, please click the following link: https://chi.mailblaze.com/api/docs

Please note that this is obviously production data and should be treated with caution.

Click the 'Authorize' button (top right corner) and enter the Public key into the field provided. Once you have been authorized you will be able to make API calls.

To make API calls using the tool, click on the request type button (GET, POST, PUT, DELETE) in the relevant section:

/lists
/subscribers
/templates
/campaigns
/transactional


Click the Try it out button in the top right corner of the section.

Enter the required parameters, marked with a red asterisk. Enter the optional parameters to refine your query.

Click the Execute button to make the query.

Your response should be displayed below the query form.

A corresponding CURL request will be displayed about the request. This can be used to indicate the structure of the request that will need to be sent from within your application.

UIDs (Unique IDs) are generated strings that are available by querying existing data which return the UID inside the JSON response:

Another option is by viewing the URL of a content type in your account (i.e. List, Subscriber etc.) if you need it on an individual basis. For example:

Lists, Subscribers, Templates, Campaigns and Transactional email UIDs all follow this format.


Using the API in Your Applications

The base endpoint URL for API requests is as follows:

https://chi.mailblaze.com/api


When used in your applications, the Public Key and the Content Type will need to be passed along as Custom Headers in your HTTP requests. To do so please include them as follows:

"authorization": "YOUR_PUBLIC_KEY",
"Content-Type": "application/x-www-form-urlencoded"


Parameters are passed along in the HTTP Body in key-value pairs. Keys are required in uppercase unless otherwise shown.

 

Example Request

As a demonstration, let’s create a new subscriber by making a POST request to the subscribers endpoint:

Please note the {LIST_UID} parameter. To retrieve one, please get it from the URL on your list page or make a GET request to the /lists endpoint.

Endpoint:

https://chi.mailblaze.com/api/{LIST_UID}/subscribers


Headers:

"authorization": "YOUR_PUBLIC_KEY",
"Content-Type": "application/x-www-form-urlencoded"

Body:

"EMAIL": john@email.com,
"FNAME": "John",
"LNAME": "Smith",

You should receive a JSON response as illustrated below:

Responses:

Code Description
201 Created
400 Wrong Method
409 Conflict
422 Unprocessable Entity

 

API Endpoints

Base Endpoint:

https://chi.mailblaze.com/api

Lists:

/lists
/lists/{list_uid}
/lists/{list_uid}/segments
/lists/{list_uid}/fields

Subscribers

/lists/{list_uid}/subscribers
/lists/{list_uid}/subscribers/{subscriber_uid}
/lists/{list_uid}/subscribers/{subscriber_uid}/unsubscribe
/lists{list_uid}/subscribers/search-by-email
/lists/subscribers/blacklist

Templates

/templates
/templates/{template_uid}

Campaigns

/campaigns
/campaigns/{campaign_uid}

Transactional Emails

/transactional
/transactional/{email_uid}

 

Lists

Base Endpoint:

https://chi.mailblaze.com/api

 

Create a new list

Endpoint: /lists
Method: POST

Parameters:

All parameters in the table are required.
All parameters are string values.
Parameters are sent in the body of the request.

Key Value
"general[name]" List Name (i.e Weekly Newsletter)
"general[description]" List Description  (i.e. Newsletter sign ups)
"defaults[from_name]" From Name (i.e. Company Name)
"defaults[from_email]" From Email (i.e. info@company.com)
"company[name]" Company Name
"company[country_id]" Country ID (South Africa: 193)
*Please see the Country ID table below
"company[address_1]" Company Physical Address - Line 1
"company[city]" City the company is located in
"company[zip_code]" Company Area Code

Responses:

Code Description
201 Created
400 Wrong Method
409 Conflict
422 Unprocessable Entity

 

Get all list data

Endpoint: /lists
Method: GET


Parameters:

The following parameters are not required, but are useful to refine your query
All parameters are string values.

Code Description
page Result set page number
per_page Number of results per page

 

Responses:

Code Description
200 OK
404 Not Found

 

Get data for a specific list

Endpoint: /lists/{list_uid}
Method: GET

 

Provide the LIST_UID of the list you want to add the subscriber to in the URL. Query the /lists endpoint to get list data.

Responses

Code Description
200 OK
404 Not Found

Update data for a specific list

Endpoint: /lists/{list_uid}
Method: PUT

Parameters:
All parameters are string values.
Parameters are sent in the body of the request.
Enter the values that you would like to update. You do not need to provide all the list data; only the data that you'd like to modify.

Key Value
"general[name]" List Name
"general[description]" List Description
"defaults[from_name]" From Name (i.e. Company Name)
"defaults[from_email]" From Email
"company[name]" Company Name
"company[country_id]" Country ID (South Africa: 193)
*Please see the Country ID table below
"company[address_1]" Company Physical Address - Line 1
"company[city]" City the company is located in
"company[zip_code]" Company Area Code

Responses:

Code Description
201 Created
400 Wrong Method
409 Conflict
422 Unprocessable Entity

 

Delete a specific list

Endpoint: /lists/{list_uid}
Method: DELETE

Provide the LIST_UID in the URL.

Important:
Deleting a list is permanent. This cannot be undone.
When you delete a list, it will also delete all campaigns that were sent to that list!

Responses

Code Description
200 OK
400 Wrong Method
404 Not Found

 

Get all segments of a specific list

Provide the LIST_UID in the URL

Endpoint: /lists/{list_uid}/segments
Method: GET

Responses

Code Description
200 OK
404 Not Found

 

Get all fields of a specific list

Provide the LIST_UID in the URL

Endpoint: /lists/{list_uid}/fields
Method: GET

Responses

Code Description
200 OK
404 Not Found

 

Code Country Code Country Code Country
1 Afghanistan 81 Germany 161 Oman
2 Albania 82 Ghana 162 Pakistan
3 Algeria 83 Gibraltar 163 Palau
4 American Samoa 84 Greece 164 Panama
5 Andorra 85 Greenland 165 Papua New Guinea
6 Angola 86 Grenada 166 Paraguay
7 Anguilla 87 Guadeloupe 167 Peru
8 Antarctica 88 Guam 168 Philippines
9 Antigua and Barbuda 89 Guatemala 169 Pitcairn
10 Argentina 90 Guinea 170 Poland
11 Armenia 91 Guinea-bissau 171 Portugal
12 Aruba 92 Guyana 172 Puerto Rico
13 Australia 93 Haiti 173 Qatar
14 Austria 94 Heard and Mc Donald Islands 174 Reunion
15 Azerbaijan 95 Honduras 175 Romania
16 Bahamas 96 Hong Kong 176 Russian Federation
17 Bahrain 97 Hungary 177 Rwanda
18 Bangladesh 98 Iceland 178 Saint Kitts and Nevis
19 Barbados 99 India 179 Saint Lucia
20 Belarus 100 Indonesia 180 Saint Vincent and the Grenadines
21 Belgium 101 Iran (Islamic Republic of) 181 Samoa
22 Belize 102 Iraq 182 San Marino
23 Benin 103 Ireland 183 Sao Tome and Principe
24 Bermuda 104 Israel 184 Saudi Arabia
25 Bhutan 105 Italy 185 Senegal
26 Bolivia 106 Jamaica 186 Seychelles
27 Bosnia and Herzegowina 107 Japan 187 Sierra Leone
28 Botswana 108 Jordan 188 Singapore
29 Bouvet Island 109 Kazakhstan 189 Slovak Republic
30 Brazil 110 Kenya 190 Slovenia
31 British Indian Ocean Territory 111 Kiribati 191 Solomon Islands
32 Brunei Darussalam 112 North Korea 192 Somalia
33 Bulgaria 113 Korea, Republic of 193 South Africa
34 Burkina Faso 114 Kuwait 194 South Georgia & South Sandwich Islands
35 Burundi 115 Kyrgyzstan 195 Spain
36 Cambodia 116 Lao People's Democratic Republic 196 Sri Lanka
37 Cameroon 117 Latvia 197 St. Helena
38 Canada 118 Lebanon 198 St. Pierre and Miquelon
39 Cape Verde 119 Lesotho 199 Sudan
40 Cayman Islands 120 Liberia 200 Suriname
41 Central African Republic 121 Libyan Arab Jamahiriya 201 Svalbard and Jan Mayen Islands
42 Chad 122 Liechtenstein 202 Swaziland
43 Chile 123 Lithuania 203 Sweden
44 China 124 Luxembourg 204 Switzerland
45 Christmas Island 125 Macau 205 Syrian Arab Republic
46 Cocos (Keeling) Islands 126 FYROM 206 Taiwan
47 Colombia 127 Madagascar 207 Tajikistan
48 Comoros 128 Malawi 208 Tanzania, United Republic of
49 Congo 129 Malaysia 209 Thailand
50 Cook Islands 130 Maldives 210 Togo
51 Costa Rica 131 Mali 211 Tokelau
52 Cote D'Ivoire 132 Malta 212 Tonga
53 Croatia 133 Marshall Islands 213 Trinidad and Tobago
54 Cuba 134 Martinique 214 Tunisia
55 Cyprus 135 Mauritania 215 Turkey
56 Czech Republic 136 Mauritius 216 Turkmenistan
57 Denmark 137 Mayotte 217 Turks and Caicos Islands
58 Djibouti 138 Mexico 218 Tuvalu
59 Dominica 139 Micronesia, Federated States of 219 Uganda
60 Dominican Republic 140 Moldova, Republic of 220 Ukraine
61 East Timor 141 Monaco 221 United Arab Emirates
62 Ecuador 142 Mongolia 222 United Kingdom
63 Egypt 143 Montserrat 223 United States
64 El Salvador 144 Morocco 224 United States Minor Outlying Islands
65 Equatorial Guinea 145 Mozambique 225 Uruguay
66 Eritrea 146 Myanmar 226 Uzbekistan
67 Estonia 147 Namibia 227 Vanuatu
68 Ethiopia 148 Nauru 228 Vatican City State (Holy See)
69 Falkland Islands (Malvinas) 149 Nepal 229 Venezuela
70 Faroe Islands 150 Netherlands 230 Viet Nam
71 Fiji 151 Netherlands Antilles 231 Virgin Islands (British)
72 Finland 152 New Caledonia 232 Virgin Islands (U.S.)
73 France 153 New Zealand 233 Wallis and Futuna Islands
74 France, Metropolitan 154 Nicaragua 234 Western Sahara
75 French Guiana 155 Niger 235 Yemen
76 French Polynesia 156 Nigeria 236 Yugoslavia
77 French Southern Territories 157 Niue 237 Democratic Republic of Congo
78 Gabon 158 Norfolk Island 238 Zambia
79 Gambia 159 Northern Mariana Islands 239 Zimbabwe
80 Georgia 160 Norway    

 

SUBSCRIBERS

Base Endpoint:

https://chi.mailblaze.com/api

 

Add a subscriber to a list

Endpoint: /lists/{list_uid}/subscribers
Method: POST

Provide the LIST_UID of the list you want to add the subscriber to in the URL. Query the /lists endpoint to get list data.

Parameters:

All parameters in the table are required.
All parameters are string values.
Parameters are sent in the body of the request.

Key Value Required
"EMAIL" Email Address Yes
"FNAME" First Name  
"LNAME" Last Name  
"CUSTOM_TAG_NAME" Custom data*  

*Please see the Custom Fields section for more information on how to set this up. The CUSTOM_TAG_NAME will need to match the name of the custom field for the list.

Responses

Code Description
201 Created
400 Wrong Method
409 Conflict
422 Unprocessable Entity

 

Custom Fields

You are also able to send custom information in your request body as key-value pairs, but please ensure that you have the custom fields set up in your list first. To do so:
- Log in to your account
- Create the list
- Click on the list
- In the sidebar menu, click SETTINGS > Custom Fields
- Click ADD NEW FIELD > Select the field type you need
-  Enter a Label* and Tag* (Please note tags need to be in uppercase)
- Save Changes

Once the custom field is set up, you can add the data to your list via the API. Please ensure the custom field keys are in uppercase (following the EMAIL / FNAME / LNAME format).

 

Get all subscribers for a specific list

Endpoint: /lists/{list_uid}/subscribers
Method: GET

Results are returned in sets of 10. Append the /page={number} at the end of the URL to return the next result set. For example:

/campaigns?page=2

Provide the LIST_UID of list you want to add the subscriber to in the URL. Query the /lists endpoint to get list data.

Responses

Code Description
200 OK
404 Not Found

 

Update a subscriber’s data for a specific list

Endpoint: /lists/{list_uid}/subscribers/{subscriber_uid}
Method: PUT

Provide the LIST_UID of list you want to add the subscriber to in the URL. Query the /lists endpoint to get list data.

Provide the SUBSCRIBER_UID at the end of the URL. Query the /lists/{list_uid}/subscribers endpoint to get subscriber data. Alternatively, you could query the /lists/{list_uid}/subscribers/search-by-email endpoint if you know their email address.

Parameters:
All parameters are string values.
Enter the values that you would like to update. You do not need to provide all the data; only the values that you’d like to modify.

Key Value Required
"EMAIL" Email Address Yes
"FNAME" First Name  
"LNAME" Last Name  
"CUSTOM_TAG_NAME" Custom data*  

*Please see the Custom Fields section above for more information on how to set this up. The CUSTOM_TAG_NAME will need to match the name of the custom field for the list.

Responses

Code Description
201 Created
400 Wrong Method
409 Conflict
422 Unprocessable Entity

 

Delete a subscriber

Endpoint: /lists/{list_uid}/subscribers/{subscriber_uid}
Method: DELETE

Provide the LIST_UID of list you want to add the subscriber to in the URL. Query the /lists endpoint to get list data.

Provide the SUBSCRIBER_UID at the end of the URL. Query the /lists/{list_uid}/subscribers endpoint to get subscriber data. Alternatively, you could query the /lists/{list_uid}/subscribers/search-by-email endpoint if you know their email address.

Important:
Deleting a subscriber is permanent. This cannot be undone.
When you delete a subscriber, it will also alter any campaign data that is associated with the subscriber.

Code Description
200 OK
400 Wrong Method
404 Not Found

 

Unsubscribe a subscriber from a list

Provide the LIST_UID in the URL

Endpoint: /lists/{list_uid}/subscribers/{subscriber_uid}/unsubscribe
Method: PUT

Update a user’s status to “unsubscribed”.

If the Add subscriber to blacklist in the “ACTIONS WHEN UNSUBSCRIBE” section is set to “Yes”, then when a subscriber is unsubscribed they will be added to the local blacklist. This is to ensure that should their email address appear on multiple lists, they are not sent any future emails.

This setting is “Yes” by default. If you update it to “No”, the subscriber will only be unsubscribed from that specific list. If they appear on other lists, then they will receive future emails sent to those lists.

You can update it by clicking the “gear” icon > UPDATE on the link below. The setting is under the ADVANCED SETTINGS section. After login, navigate to
https://chi.mailblaze.com/customer/index.php/lists/index

Responses

Code Description
200 OK
404 Not Found

 

Search a list for a subscriber based on their email address

Provide the LIST_ID in the URL. Provide the subscriber’s email address in the body of the request.

Endpoint: /lists/{list_uid}/subscribers/search-by-email
Method: GET

Responses

Code Description
200 OK
404 Not Found
422 Unprocessable Entity

 

Add a subscriber to the local blacklist

If a subscriber complains about receiving emails, it's a good idea to add them to the account blacklist. This will ensure that they are never sent emails again.

Provide the subscriber’s email address in the body of the request.

Endpoint: /lists/subscribers/blacklist
Method: POST

Parameters

Key Value Required
"EMAIL" Email Address Yes

Responses

Code Description
200 OK
422 Unprocessable Entity

 

TEMPLATES

Base endpoint: https://chi.mailblaze.com/api

Create a template

Endpoint: /templates
Method: POST

Parameters:

All parameters in the table are required.
All parameters are string values.
Parameters are sent in the body of the request.

Key Value Required
"template[name]" Template Name Yes
"template[content]" *Content (base64 encoded) Yes

*Please ensure that your template code is base64 encoded before sending the request. If it isn’t, the content of the email will display unknown characters as well as break the layout.

Please also add an unsubscribe tag. Campaign emails need them in order to send. An unsubscribe link should follow the format below:

<a href="[UNSUBSCRIBE_URL]">Unsubscribe</a>

Responses

Code Description
201 Created
400 Wrong Method
422 Unprocessable Entity

 

Get all templates

Endpoint: /templates
Method: GET

Results are returned in sets of 10. Append the /page={number} at the end of the URL to return the next result set. For example:

/templates?page=2
Code Description
200 OK

 

Get a specific template

Endpoint: /template/{template_uid}
Method: GET

Provide the campaign UID at the end of the URL. This can be obtained by querying the /campaigns endpoint as illustrated above.

Code Description
200 OK
404 Not Found

 

Update a template

Endpoint: /templates/{template_uid}
Method: PUT

Parameters:


All parameters are string values.
Parameters are sent in the body of the request.

Key Value Required
"template[name]" Template Name  
"template[content]" *Content (base64 encoded) Yes

*Please ensure that your template code is base64 encoded before sending the request. If it isn’t, the content of the email will display unknown characters as well as break the layout.

Please also add an unsubscribe tag. Campaign emails need them in order to send. An unsubscribe link should follow the format below:

<a href="[UNSUBSCRIBE_URL]">Unsubscribe</a>

Responses

Code Description
201 Created
400 Wrong Method
404 Not Found
422 Unprocessable Entity

 

Delete a specific template

Endpoint: /template/{template_uid}
Method: DELETE

Provide the campaign UID at the end of the URL. This can be obtained by querying the /campaigns endpoint as illustrated above.

Code Description
200 OK
404 Not Found

 

CAMPAIGNS

Base endpoint: https://chi.mailblaze.com/api

Create a campaign

Endpoint: /campaigns
Method: POST

Parameters:

All parameters in the table are required.
All parameters are string values.
Parameters are sent in the body of the request.

Key Value Required
"campaign[name]" Campaign Name Yes
"campaign[from_name]" Name of Sender Yes
"campaign[from_email]" Email of Sender Yes
"campaign[reply_to]" Reply to Email Address Yes
"campaign[subject]" Subject Line Yes
"campaign[list_uid]" List Uid of List to Send to Yes
"campaign[segment_uid]" Segment Uid No
"campaign[template][template_uid]" Template Uid Yes

 

Responses

Code Description
201 Created
400 Wrong Method
404 Not Found
422 Unprocessable Entity

 

Get all campaigns

Endpoint: /campaigns/{campaign_uid}
Method: GET

Results are returned in sets of 10. Append the /page={number} at the end of the URL to return the next result set. For example:

/campaigns?page=2

Responses

Code Description
200 OK

 

Get a specific campaign

Endpoint: /campaigns/{campaign_uid}
Method: GET

Provide the campaign UID at the end of the URL. This can be obtained by querying the /campaigns endpoint as illustrated above.

 

Responses

Code Description
200 OK
404 Not Found

 

Update a campaign

Endpoint: /campaigns/{campaign_uid}
Method: PUT

Campaigns in “draft” mode can be updated by sending the relevant values in the body of the request.

Parameters:

All parameters are string values.
Enter the values that you would like to update. You do not need to provide all the data; only the values that you’d like to modify.

Key Value Required
"campaign[name]" Campaign Name Yes
"campaign[from_name]" Name of Sender Yes
"campaign[from_email]" Email of Sender Yes
"campaign[reply_to]" Reply to Email Address Yes
"campaign[subject]" Subject Line Yes
"campaign[list_uid]" List Uid of List to Send to Yes
"campaign[segment_uid]" Segment Uid No
"campaign[template][template_uid]" Template Uid Yes

Responses

Code Description
201 Created
400 Wrong Method
404 Not Found
422 Unprocessable Entity

 

Delete a specific campaign

Endpoint: /campaigns/{campaign_uid}
Method: DELETE

Provide the campaign UID at the end of the URL. This can be obtained by querying the /campaigns endpoint as illustrated above.

 

Code Description
200 OK
400 Wrong Method
404 Not Found

 

Transactional Mails

Base endpoint: https://chi.mailblaze.com/api

 

There are 2 ways to send transactional emails: using form data or by sending a JSON object. If you wish to send attachments with your transaction emails, then you'll need to send a JSON object to the endpoint, otherwise you may use either approach.

 

Create a transactional email with form data (No attachments)

Endpoint: /transactional
Method: POST

Parameters:

All parameters in the table are required.
All parameters are string values.
Parameters are sent in the body of the request.

Key Value Required
"to_email" Recipient's email Yes
"to_name" Name of Recipient Yes
"from_email" Email of Sender Yes
"from_name" Name of Sender Yes
"reply_to_email" Reply to Email Address  
"reply_to_name" Reply to Name  
"subject" Subject Line Yes
"body" *Email Content (base64 encoded) Yes
"plain_text" Plain Text Version  
"send_at" Scheduled time (leave blank to send immediately)  

*Please ensure that your template code is base64 encoded before sending the request. If it isn’t, the content of the email will display unknown characters as well as break the layout.

Responses

Code Description
201 Created
400 Wrong Method
404 Not Found
422 Unprocessable Entity

 

Create a transactional email as JSON (with an attachment)

Endpoint: /transactional
Method: POST

Should you wish to send your data as JSON instead of form data as illustrated above you can do so by following the example below. Omit the attachment data from your request if you do not wish to send an attachment.

Please see below for the JSON object structure.

Supported attachment formats are: PDF, 

File sizes are restricted to 1MB.

Please note that base64 encoding is required for the email body, plain text and attachment file data.

{
  "to_email": "recipient@domain.com",
  "to_name": "recipient",
  "from_email": "sender@domain.com",
  "from_name": "sender",
  "reply_to_email": "no-reply@domain.com",
  "reply_to_name": "no-reply",
  "subject": "subject",
  "body": "base64 encoded html",
  "plain_text": "base64 encoded text",
  "send_at": "01-01-2019 08:00:00",
  "attachments": [
    {
      "name": "Filename.pdf",
      "data": "base64 encoded file data"
    }
  ]
}

Responses

Code Description
201 Created
400 Wrong Method
404 Not Found
422 Unprocessable Entity

 

Get all transactional emails

Endpoint: /transactional
Method: GET

Results are returned in sets of 10. Append ?page={number} at the end of the URL to return the next result set. For example:

/transactional?page=2

Responses

Code Description
200 OK

 

View a transactional email sent to a customer

Endpoint: /transactional/{email_uid}
Method: GET

Provide the campaign UID at the end of the URL. This can be obtained by querying the /transactional endpoint as illustrated above.

Responses

Code Description
200 OK
404 Not Found

 


Back to the support centre

Contact us for help

Fill out the form and we will get back to you.