BoltMail API

This page contains developer API documentation for BoltMail.

BoltMail is a SASS email marketing software platform available from www.boltmail.nz.

Help with using BoltMail can be found in our knowlegebase at https://www.christopherbolt.com/support/knowledgebase

Developer specific articles not related to the API can be found at
https://www.christopherbolt.com/support/knowledgebase/19/Web-and-email-developers

Some third party libraries and wrappers are available for this API, see below, however we recommend using the API directly. You can change the language of our code examples using the language menu at the top of this page.

3rd Party Laravel API Libraries

https://github.com/alexthekiwi/boltmail-laravel-sdk

3rd Party MailWizz API Libraries

BoltMail is compatible with the MailWizz Email Marketing API.

Note that the BoltMail API includes additional features not supported by the standard MailWizz API, to harness the full power of BoltMail you may need to roll your own implimentation. Our API documentation can help you to do that.

When using a third party SDK the API URL must be set to https://app.boltmail.nz/api and if the library expects a private key this should be left blank.

https://github.com/ems-api/php-client - PHP SDK

https://github.com/twisted1919/mailwizz-python-sdk - Python SDK.

https://github.com/twisted1919/mailwizz-ruby-sdk - Ruby SDK.

https://github.com/thangtx/mailwizzphpapi-wrap - A small rest app that acts as a proxy between mailwizz and any other software.

https://www.npmjs.com/package/node-mailwizz - Node.js implementations

Introduction

Our REST API interface is used to integrate BoltMail, the API is designed for developers and is accompanied with a detailed documentation.

The BoltMail API opens up a world of feasibility for integrating our platform with your favorite CMS, Framework, or other third party software

We are constantly working to improve this documentation. If you have questions, please contact the support at support@boltmail.nz

Base URL

https://app.boltmail.nz/api/

Acceptable Requests

All requests must be a valid HTTP 1.1 request including the host header as per the HTTP 1.1 specifications. Fortunatly common HTTP 1.1 compliant clients such as cURL will send these headers for you.

For POST or PUT methods data can be sent as either application/x-www-form-urlencoded or application/json. You must send the correct Content-Type header for your data format, either application/x-www-form-urlencoded or application/json. Failure to send in a supported data format with the correct Content-Type header will result in an error.

Authentication

BoltMail API uses HTTP Authentication through an API key.

You can choose to generate multiple keys as per your development needs.

You can generate API key's from API keys tab in your BoltMail panel.

We recommend setting an IP address whitelist for each key, this will restrict access to only the IP addresses listed.

To authenticate you will need to send one custom authentication header:

X-API-KEY: your API key

For example, if your API Key is: dc95f6772bd9c09e12dc88f8683144c665bf0c26 authentication header should look like:

X-API-KEY: dc95f6772bd9c09e12dc88f8683144c665bf0c26

cURL example:

cURL request example

curl -v GET \
  'https://app.boltmail.nz/api/' \
  -H 'X-API-KEY: {replace-it-with-your-public-key}'

Response

API response is JSON formatted. The response object will include a "status" attribute at the top level with a value of "success" for a successful request or "error" for a failed request.

Successful response

A successful response will include an attribute of "status" with a value of "success".

If the response includes data this will be contained within an object named "data".

Single record response

If the endpoint returns single record responses then this will be contained inside a sub-object named "record"

Example of a single record response:

{
    "status": "success",
    "data": {
        "record": {
            "subscriber_uid": "zz828zm50m3fb",
            "status": "unconfirmed",
            "source": "api",
            "ip_address": "127.0.0.1",
            "EMAIL": "john.doe@doe.com",
            "FNAME": "John",
            "LNAME": "Doe",
        }
    }
}

Multiple record response

If the endpoint returns multiple records then these will be contained inside a sub-object named "records".

Endpoints that return a large number of records, such as the subscribers endpoint, will be paged. If this is the case there will be additional paramaters named "count", "total_pages" and "current_page".

You can move between pages by added a page query paramater to the endpoint. e.g. ?page=4. You can also specify the length of a page using the per_page parameter, e.g. ?page=4&per_page=50. Note that a large per_page may result in poor performance. Each endpoint has a minimum per_page of 10, specifying a page length smaller than this will still return 10 per page. The maximum per_page varies between endpoints but is usually 1000, specifying a page length larger than the maximum will still return the endpoint's maximum per page. Most endpoints also support a sort_by parameter to sort by a specific field, the fields available for sorting varies between endpoints. There is also a sort_dir parameter that can be set to desc to sort descending or asc to sort ascending. By default endpoints are sorted newest first.

Example of a multiple record response with paging:

{
    "status": "success",
    "data": {
        "count": "2",
        "total_pages": 1,
        "current_page": 1,
        "next_page": null,
        "prev_page": null,
        "records": [
            {
                "subscriber_uid": "sm8665teg9aa9",
                "EMAIL": "john.doe@doe.com",
                "APITEST": "",
                "FNAME": "John",
                "LNAME": "Doe",
                "status": "confirmed",
                "source": "import",
                "ip_address": null,
                "date_added": "2019-06-11 20:50:48"
            },
            {
                "subscriber_uid": "3hf82237hfew",
                "EMAIL": "john.smith@smith.com",
                "APITEST": "",
                "FNAME": "John",
                "LNAME": "Smith",
                "status": "confirmed",
                "source": "import",
                "ip_address": null,
                "date_added": "2019-06-11 20:50:48"
            },
        ]
    }
}

Unsuccessful response

A failed response will include an attribute of "status" with a value of "error". It will also include an attribute of "error" containing explanations as to why the request failed. If there are multiple errors then this value may be a list.

Example failed response with a single error:

{
    "status": "error",
    "error": "The subscriber already exists in this list."
}

Example failed response with multiple errors:

{
    "status": "error",
    "error": {
        "name": "Campaign name cannot be blank.",
        "from_name": "From name cannot be blank.",
        "from_email": "From email cannot be blank.",
        "subject": "Subject cannot be blank.",
        "reply_to": "Reply to cannot be blank."
    }
}

HTTP Response codes

BoltMail uses standard HTTP response codes.