NAV
php ruby python

Introduction

This is the documentation for MailWizz 2.x API.

For MailWizz 1.x API documentation, please see this link.

In order to integrate MailWizz with 3rd-party apps or any custom apps, you can use its powerful API.

The API is providing the basic operations needed for your implementation.

This document will drive you through the MailWizz available SDKs .

Available implementations:

The PHP SDK

Compatible implementations:

The Python SDK.

The Ruby SDK.

A small rest app that acts as a proxy between MailWizz and any other software.

Node.js implementations.

HTTP Methods used

We follow the REST standards for MailWizz's API interaction, which means that we use following HTTP methods during communication:

You will have to make sure your server supports all these methods.

If you are doing API calls and get HTTP Forbidden errors, when updating or deleting items, it means your server does not support PUT/DELETE and you must change it's configuration to allow these methods.

Getting started

First you need to install the SDK. See each supported language for its way of installing

PHP

You can either download the latest version of the code, or you can install it via composer as follows:

composer require ems-api/php-client

Then follow the instructions from examples/setup.php file.

Python

You can either download the latest version of the code, or you can install it via pip as follows:

pip install mailwizz-python-sdk

Then follow the instructions from examples/setup_api.py file.

Ruby

You can download or clone the latest version of the code.

git clone https://github.com/twisted1919/mailwizz-ruby-sdk.git

You will need to have Ruby installed:

https://www.ruby-lang.org/en/documentation/installation/

The following gem is required: excon

sudo gem install excon

Then, follow the instructions from examples/setup_api.rb file.

Setup

Please make sure to replace API-URL PUBLIC-KEY, with their proper values:

//Require the autoloader class if you haven't used composer to install the package
require_once __DIR__ . '/../vendor/autoload.php';

//Configuration object (Get your API info from: https://kb.mailwizz.com/articles/find-api-info/) :
$config = new \EmsApi\Config([
    'apiUrl'    => 'API-URL',
    'apiKey'    => 'PUBLIC-KEY',

    // components
    'components' => [
        'cache' => [
            'class'     => \EmsApi\Cache\File::class,
            'filesPath' => __DIR__ . '/data/cache', // make sure it is writable by webserver
        ]
    ],
]);
//Now inject the configuration and we are ready to make api calls
\EmsApi\Base::setConfig($config);

//Start UTC
date_default_timezone_set('UTC');
require '../mailwizz/mailwizz'

include Mailwizz
include Endpoint

# noinspection SpellCheckingInspection
config = Config.new({
                        'api_url': 'API-URL',
                        'public_key': 'PUBLIC-KEY',
                        'charset': 'utf-8'
                    })

# now inject the configuration and we are ready to make api calls
Base.config = config
from mailwizz.base import Base
from mailwizz.config import Config

def setup():

    # configuration object
    config = Config({
        'api_url': 'API-URL',
        'public_key': 'PUBLIC-KEY',
        'charset': 'utf-8'
    })

    # now inject the configuration and we are ready to make api calls
    Base.set_config(config)

See each language tab for the setup instructions.

Notes

Lists

Lists endpoint

/ CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\Lists();
# CREATE THE ENDPOINT
endpoint = Lists.new
from mailwizz.endpoint.lists import Lists

"""
CREATE THE ENDPOINT
"""
endpoint = Lists()

Get all lists

// GET ALL ITEMS
$response = $endpoint->getLists($pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# GET ALL ITEMS
response = endpoint.get_lists(page = 1, per_page = 10)

# DISPLAY RESPONSE
puts response.body
"""
GET ALL ITEMS
"""
response = endpointLists.get_lists(page=1, per_page=10)

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "12",
    "total_pages": 2,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "records": [
      {
        "general": {
          "list_uid": "tz601yx7aa61b",
          "name": "Testing list #4",
          "display_name": "Testing list",
          "description": "Testing list"
        },
        "defaults": {
          "from_name": "Test user",
          "reply_to": "user@example.com",
          "subject": ""
        },
        "notifications": {
          "subscribe": "no",
          "unsubscribe": "no",
          "subscribe_to": "",
          "unsubscribe_to": ""
        },
        "company": {
          "name": "Support",
          "address_1": "Test",
          "address_2": "",
          "zone_name": "Constanta",
          "city": "Constanta",
          "zip_code": "1234x",
          "phone": "",
          "address_format": "[COMPANY_NAME]\n[COMPANY_ADDRESS_1] [COMPANY_ADDRESS_2]\n[COMPANY_CITY] [COMPANY_ZONE] [COMPANY_ZIP]\n[COMPANY_COUNTRY]\n[COMPANY_WEBSITE]",
          "country": {
            "country_id": "1",
            "name": "Afghanistan",
            "code": "AF"
          }
        }
      },
      {
        "general": {
          "list_uid": "zh103m6twfcd2",
          "name": "Testing list #5",
          "display_name": "Testing list",
          "description": "Testing list"
        },
        "defaults": {
          "from_name": "Test user",
          "reply_to": "user@example.com",
          "subject": ""
        },
        "notifications": {
          "subscribe": "no",
          "unsubscribe": "no",
          "subscribe_to": "",
          "unsubscribe_to": ""
        },
        "company": {
          "name": "Support",
          "address_1": "Test",
          "address_2": "",
          "zone_name": "Constanta",
          "city": "Constanta",
          "zip_code": "1234x",
          "phone": "",
          "address_format": "[COMPANY_NAME]\n[COMPANY_ADDRESS_1] [COMPANY_ADDRESS_2]\n[COMPANY_CITY] [COMPANY_ZONE] [COMPANY_ZIP]\n[COMPANY_COUNTRY]\n[COMPANY_WEBSITE]",
          "country": {
            "country_id": "1",
            "name": "Afghanistan",
            "code": "AF"
          }
        }
      }
    ]
  }
}

This endpoint retrieves all the lists.

HTTP Request

GET API-URL/lists

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.

Get one list

// get a single list
$response = $endpoint->getList('LIST-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# GET ONE ITEM
response = endpoint.get_list('LIST-UNIQUE-ID')

# DISPLAY RESPONSE
puts response.body
"""
GET ONE ITEM
"""
response = endpointLists.get_list('LIST-UNIQUE-ID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "record": {
      "general": {
        "list_uid": "cn417nrhmv922",
        "name": "Testing list #4",
        "display_name": "Testing list",
        "description": "Testing list"
      },
      "defaults": {
        "from_name": "User Test",
        "reply_to": "user@example.com",
        "subject": ""
      },
      "notifications": {
        "subscribe": "no",
        "unsubscribe": "no",
        "subscribe_to": "",
        "unsubscribe_to": ""
      },
      "company": {
        "name": "Support",
        "address_1": "Test",
        "address_2": "",
        "zone_name": "Constanta",
        "city": "Constanta",
        "zip_code": "1234x",
        "phone": "",
        "address_format": "[COMPANY_NAME]\n[COMPANY_ADDRESS_1] [COMPANY_ADDRESS_2]\n[COMPANY_CITY] [COMPANY_ZONE] [COMPANY_ZIP]\n[COMPANY_COUNTRY]\n[COMPANY_WEBSITE]",
        "country": {
          "country_id": "1",
          "name": "Afghanistan",
          "code": "AF"
        }
      }
    }
  }
}

This endpoint retrieves the list with the given LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID

Query Parameters

Parameter Required Description
LIST-UNIQUE-ID yes List unique id which to retrieve.

Create a list

// create a new list
// please see countries.php example file for a list of allowed countries/zones for list company
$response = $endpoint->create([
    // required
    'general' => [
        'name'          => 'My list created from the API', // required
        'description'   => 'This is a test list, created from the API.', // required
    ],
    // required
    'defaults' => [
        'from_name' => 'John Doe', // required
        'from_email'=> 'johndoe@doe.com', // required
        'reply_to'  => 'johndoe@doe.com', // required
        'subject'   => 'Hello!',
    ],
    // optional
    'notifications' => [
        // notification when new subscriber added
        'subscribe'         => 'yes', // yes|no
        // notification when subscriber unsubscribes
        'unsubscribe'       => 'yes', // yes|no
        // where to send the notifications.
        'subscribe_to'      => 'johndoe@doe.com',
        'unsubscribe_to'    => 'johndoe@doe.com',
    ],
    // optional, if not set customer company data will be used
    'company' => [
        'name'      => 'John Doe INC', // required
        'country'   => 'United States', // required
        'zone'      => 'New York', // required
        'address_1' => 'Some street address', // required
        'address_2' => '',
        'zone_name' => '', // when country doesn't have required zone.
        'city'      => 'New York City',
        'zip_code'  => '10019',
    ],
]);

// and get the response
echo '<pre>';
print_r($response->body);
echo '</pre>';
# CREATE ONE LIST
response = endpoint.create({
     # required
     'general': {
         'name': 'My list created from the API', # required
         'description': 'This is a test list, created from the API.', # required
     },
     'defaults': {
         'from_name': 'John Doe', # required
         'from_email': 'johndoe@doe.com', # required
         'reply_to': 'johndoe@doe.com', # required
         'subject': 'Hello!',
     }
 })

# DISPLAY RESPONSE
puts response.body
"""
CREATE ONE LIST
"""
response = endpointLists.create({
    # required
    'general': {
        'name': 'My list created from the API',  # required
        'description': 'This is a test list, created from the API.',  # required
    },
    'defaults': {
        'from_name': 'John Doe',  # required
        'from_email': 'johndoe@doe.com',  # required
        'reply_to': 'johndoe@doe.com',  # required
        'subject': 'Hello!',
    }
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success",
  "list_uid": "hv4163y076d84"
}

This endpoint creates a list.

The $data param can contain following indexed arrays:

-> general - required

-> defaults - required

-> notifications - optional

-> company - optional, if not set customer company data will be used

Please see countries.php example file for a list of allowed countries/zones for list company

HTTP Request

POST API-URL/lists/create

POST Parameters

Parameter Type Required Description
data array yes Array with the list details. The following indexed arrays are accepted: general, defaults, notifications, company

General block - required

Parameter Type Required Description
name string yes List name
description string yes List description

Defaults block - required

Parameter Type Required Description
from_name string yes From name
from_email string yes From email
reply_to string yes Reply to email
subject string no List subject

Notifications block - optional

Parameter Type Required Description
subscribe Yes/No no Notification when new subscriber added
unsubscribe Yes/No no Notification when new subscriber unsubscribe
subscribe_to string no Where to send the notifications on subscribe
unsubscribe_to string no Where to send the notifications on unsubscribe

Company block - optional - if not set customer company data will be used

Parameter Type Required Description
name string yes Company name
country string yes Company country
zone string yes Company zone
address_1 string yes Company address
address_2 string no Company address 2
zone_name string no Company address - when country doesn't have required zone.
city string no Company city
zipcode string no Company zipcode

Update a list

// update list
// please see countries.php example file for a list of allowed countries/zones for list company
$response = $endpoint->update('LIST-UNIQUE-ID', [
    // required
    'general' => [
        'name'          => 'My list created from the API - now updated!', // required
        'description'   => 'This is a test list, created from the API.', // required
    ],
    // required
    'defaults' => [
        'from_name' => 'John Doe', // required
        'from_email'=> 'johndoe@doe.com', // required
        'reply_to'  => 'johndoe@doe.com', // required
        'subject'   => 'Hello!',
    ],
    // optional
    'notifications' => [
        // notification when new subscriber added
        'subscribe'         => 'yes', // yes|no
        // notification when subscriber unsubscribes
        'unsubscribe'       => 'yes', // yes|no
        // where to send the notifications.
        'subscribe_to'      => 'johndoe@doe.com',
        'unsubscribe_to'    => 'johndoe@doe.com',
    ],
    // optional, if not set customer company data will be used
    'company' => [
        'name'      => 'John Doe INC', // required
        'country'   => 'United States', // required
        'zone'      => 'New York', // required
        'address_1' => 'Some street address', // required
        'address_2' => '',
        'zone_name' => '',
        'city'      => 'New York City',
        'zip_code'  => '10019',
    ],
]);

// and get the response
echo '<pre>';
print_r($response->body);
echo '</pre>';
# UPDATE ONE LIST
response = endpoint.update('LIST-UNIQUE-ID', {
    # required
    'general': {
        'name': 'My list created from the API and now updated', # required
        'description': 'This is a test list, created from the API.', # required
    },
    'defaults': {
        'from_name': 'John Doe', # required
        'from_email': 'johndoe@doe.com', # required
        'reply_to': 'johndoe@doe.com', # required
        'subject': 'Hello!',
    }
})

# DISPLAY RESPONSE
puts response.body
"""
UPDATE ONE LIST
"""
response = endpointLists.update('LIST-UNIQUE-ID', {
    # required
    'general': {
        'name': 'My list created from the API and now updated',  # required
        'description': 'This is a test list, created from the API.',  # required
    },
    'defaults': {
        'from_name': 'John Doe',  # required
        'from_email': 'johndoe@doe.com',  # required
        'reply_to': 'johndoe@doe.com',  # required
        'subject': 'Hello!',
    }
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success"
}

This endpoint updates a list.

HTTP Request

PUT API-URL/lists/update/LIST-UNIQUE-ID

POST Parameters

Parameter Type Required Description
LIST-UNIQUE-ID string yes List unique identifier
data array yes Array with the list details. The following indexed arrays are accepted: general, defaults, notifications, company. See the create section for details

Copy a list

// copy a list
$response = $endpoint->copy('LIST-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# COPY A LIST
response = endpoint.copy('LIST-UNIQUE-ID')

# DISPLAY RESPONSE
puts response.body
"""
COPY A LIST
"""
response = endpointLists.copy('LIST-UNIQUE-ID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success",
  "list_uid": "hv4163y076d84"
}

This endpoint copy the list with the given LIST-UNIQUE-ID.

HTTP Request

POST API-URL/lists/LIST-UNIQUE-ID/copy

Query Parameters

Parameter Required Description
LIST-UNIQUE-ID yes List unique id to copy.

Delete a list

// delete a list
$response = $endpoint->delete('LIST-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# DELETE A LIST
response = endpoint.delete('LIST-UNIQUE-ID')

# DISPLAY RESPONSE
puts response.body
"""
DELETE A LIST
"""
response = endpointLists.delete('LIST-UNIQUE-ID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success"
}

This endpoint will delete the list with the given LIST-UNIQUE-ID.

HTTP Request

DELETE API-URL/lists/LIST-UNIQUE-ID

Query Parameters

Parameter Required Description
LIST-UNIQUE-ID yes List unique id to delete.

Fields

List fields endpoint

// CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\ListFields();
# CREATE THE ENDPOINT
endpoint = ListFields.new
from mailwizz.endpoint.list_fields import ListFields

"""
CREATE THE ENDPOINT
"""
endpoint = ListFields()

Get all list fields

// GET ALL ITEMS
$response = $endpoint->getFields('LIST-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# GET ALL FIELDS OF A LIST
response = endpoint.get_fields('LIST_UID')

# DISPLAY RESPONSE
puts response.body
"""
GET ALL FIELDS OF A LIST
"""
response = endpoint.get_fields(list_uid='LIST_UID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "records": [
      {
        "tag": "EMAIL",
        "label": "Email",
        "required": "yes",
        "help_text": null,
        "type": {
          "name": "Text",
          "identifier": "text",
          "description": "Text"
        }
      },
      {
        "tag": "FNAME",
        "label": "First name",
        "required": "no",
        "help_text": null,
        "type": {
          "name": "Text",
          "identifier": "text",
          "description": "Text"
        }
      },
      {
        "tag": "LNAME",
        "label": "Last name",
        "required": "no",
        "help_text": null,
        "type": {
          "name": "Text",
          "identifier": "text",
          "description": "Text"
        }
      }
    ]
  }
}

This endpoint retrieves all the fields of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/fields

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.
LIST-UNIQUE-ID The list unique identifier

Segments

List segments endpoint

// CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\ListSegments();
# CREATE THE ENDPOINT
endpoint = ListSegments.new
from mailwizz.endpoint.list_segments import ListSegments

"""
CREATE THE ENDPOINT
"""
endpoint = ListSegments()

Get all list segments

// GET ALL ITEMS
$response = $endpoint->getSegments('LIST-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# GET ALL SEGMENTS OF A LIST
response = endpoint.get_segments('LIST_UID')

# DISPLAY RESPONSE
puts response.body
"""
GET ALL SEGMENTS OF A LIST
"""
response = endpoint.get_segments(list_uid='LIST_UID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "1",
    "total_pages": 1,
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "records": [
      {
        "segment_uid": "yx536w32xt946",
        "name": "test",
        "subscribers_count": 289
      }
    ]
  }
}

This endpoint retrieves all the segments of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/segments

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.
LIST-UNIQUE-ID The list unique identifier

Subscribers

Subscribers endpoint

/ CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\ListSubscribers();
# CREATE THE ENDPOINT
endpoint = ListSubscribers.new
from mailwizz.endpoint.list_subscribers import ListSubscribers

"""
CREATE THE ENDPOINT
"""
endpoint = ListSubscribers()

Get all subscribers

// GET ALL ITEMS
$response = $endpoint->getSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# GET ALL SUBSCRIBERS OF A LIST
response = endpoint.get_subscribers(list_uid = 'LIST-UNIQUE-ID', page = 1, per_page = 10)

# DISPLAY RESPONSE
puts response.body
"""
GET ALL SUBSCRIBERS OF A LIST
"""
response = endpoint.get_subscribers(list_uid='LIST-UNIQUE-ID', page=1, per_page=10)

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "13",
    "total_pages": 2,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "records": [
      {
        "subscriber_uid": "ll381bxshm01e",
        "EMAIL": "dmacmeartyd@jugem.jp",
        "FNAME": "",
        "LNAME": "",
        "status": "unsubscribed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:18"
      },
      {
        "subscriber_uid": "tl269bw0ol42e",
        "EMAIL": "gsteblesc@hp.com",
        "FNAME": "",
        "LNAME": "",
        "status": "unsubscribed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:18"
      },
      {
        "subscriber_uid": "gs870cmwgve71",
        "EMAIL": "lruterb@prlog.org",
        "FNAME": "",
        "LNAME": "",
        "status": "unsubscribed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:17"
      },
      {
        "subscriber_uid": "nz753vyrm0f86",
        "EMAIL": "kwheildona@tmall.com",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:17"
      },
      {
        "subscriber_uid": "sf449a4k7n193",
        "EMAIL": "dshorrock9@hp.com",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:16"
      },
      {
        "subscriber_uid": "op6219zx1s149",
        "EMAIL": "slorenz8@drupal.org",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:16"
      },
      {
        "subscriber_uid": "zz449poqsr2af",
        "EMAIL": "mhanlon7@wikispaces.com",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:16"
      },
      {
        "subscriber_uid": "jl349100yda86",
        "EMAIL": "elacroutz6@youku.com",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:15"
      },
      {
        "subscriber_uid": "kw647a5n8l516",
        "EMAIL": "mstephenson5@trellian.com",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:15"
      },
      {
        "subscriber_uid": "vo155s4b0d0ad",
        "EMAIL": "ldefew4@dailymail.co.uk",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:14"
      }
    ]
  }
}

This endpoint retrieves all the subscribers of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.
LIST-UNIQUE-ID The list unique identifier for which we retrieve the subscribers

Get one subscriber

// GET ONE ITEM
$response = $endpoint->getSubscriber('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# GET ONE SUBSCRIBER FROM A LIST
response = endpoint.get_subscriber(list_uid = 'LIST-UNIQUE-ID', subscriber_uid = 'SUBSCRIBER-UNIQUE_ID')

# DISPLAY RESPONSE
puts response.body
"""
GET ONE SUBSCRIBER FROM A LIST
"""
response = endpoint.get_subscriber(list_uid='LIST-UNIQUE-ID', subscriber_uid='SUBSCRIBER-UNIQUE_ID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "subscriber_uid": "ll381bxshm01e",
    "EMAIL": "dmacmeartyd@jugem.jp",
    "FNAME": "",
    "LNAME": "",
    "status": "unsubscribed",
    "source": "import",
    "ip_address": "",
    "date_added": "2021-02-20 17:26:18"
  }
}

This endpoint retrieves the subscriber with the given SUBSCRIBER-UNIQUE-ID from the given LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID

Query Parameters

Parameter Required Description
LIST-UNIQUE-ID yes List unique id to which the subscriber to retrieve belongs.
SUBSCRIBER-UNIQUE-ID yes Subscriber unique id to retrieve.

Search by email

// SEARCH BY EMAIL
$response = $endpoint->emailSearch('LIST-UNIQUE-ID', 'john.doe@doe.com');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# SEARCH BY EMAIL
response = endpoint.email_search(list_uid = 'LIST-UNIQUE-ID', email_address = 'john.doe@example.com')

# DISPLAY RESPONSE
puts response.body
"""
SEARCH BY EMAIL
"""
response = endpoint.email_search(list_uid='LIST-UNIQUE-ID', email_address='john.doe@example.com')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "subscriber_uid": "sf449a4k7n193",
    "status": "confirmed",
    "date_added": "2021-02-20 17:26:16"
  }
}

This endpoint searches a subscriber by his email within the list having the LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email

Query Parameters

Parameter Required Description
LIST-UNIQUE-ID yes List unique id to which the subscriber to retrieve belongs.
email yes Subscriber email to retrieve.

Search by email in all lists

// SEARCH BY EMAIL IN ALL LISTS
$response = $endpoint->emailSearchAllLists('john.doe@doe.com');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# SEARCH BY EMAIL IN ALL LISTS
response = endpoint.email_search_all_lists(email_address = 'john.doe@example.com')

# DISPLAY RESPONSE
puts response.body
"""
SEARCH BY EMAIL IN ALL LISTS
"""
response = endpoint.email_search_all_lists(email_address='john.doe@example.com')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "records": [
      {
        "subscriber_uid": "sf449a4k7n193",
        "email": "dshorrock9@hp.com",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "list": {
          "list_uid": "cn417nrhmv922",
          "display_name": "Testing list",
          "name": "Testing list #4"
        },
        "date_added": "2021-02-20 17:26:16"
      }
    ],
    "count": 1,
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}

This endpoint searches a subscriber by his email within the all lists.

HTTP Request

GET API-URL/lists/subscribers/search-by-email-in-all-lists

Query Parameters

Parameter Required Description
email yes Subscriber email to retrieve.

Search by custom fields in a list

// SEARCH BY CUSTOM FIELDS IN A LIST
$response = $endpoint->searchByCustomFields('LIST-UNIQUE-ID', [
    'EMAIL' => 'john.doe@doe.com'
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# SEARCH BY CUSTOM FIELDS IN A LIST
response = endpoint.search_by_custom_fields(list_uid = 'LIST-UNIQUE-ID', fields = {
    'EMAIL': 'john.doe@example.com'
}, page = 1, per_page = 10)
"""
SEARCH BY CUSTOM FIELDS IN A LIST
"""
response = endpoint.search_by_custom_fields(list_uid='LIST-UNIQUE-ID', fields={
    'EMAIL': 'john.doe@example.com'
}, page=1, per_page=10)

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "subscriber_uid": "ll381bxshm01e",
    "EMAIL": "dmacmeartyd@jugem.jp",
    "FNAME": "",
    "LNAME": "",
    "status": "unsubscribed",
    "source": "import",
    "ip_address": "",
    "date_added": "2021-02-20 17:26:18"
  }
}

This endpoint searches a subscriber by his custom fields values within a list given by LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-custom-fields

Query Parameters

Parameter Required Description
LIST-UNIQUE-ID yes List to search in.
array yes Array of custom fields {'CUSTOM_FIELD' => 'VALUE'}
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.

Search by status

// SEARCH BY STATUS
$response = $endpoint->searchByStatus('LIST-UNIQUE-ID', 'active', $pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# TODO - Implement
"""
TODO - implement
"""

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "subscriber_uid": "ll381bxshm01e",
    "EMAIL": "dmacmeartyd@jugem.jp",
    "FNAME": "",
    "LNAME": "",
    "status": "unsubscribed",
    "source": "import",
    "ip_address": "",
    "date_added": "2021-02-20 17:26:18"
  }
}

This endpoint search for the subscribers having a certain status within the list having the LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers

Query Parameters

Parameter Required Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.
LIST-UNIQUE-ID The list unique identifier for which we retrieve the subscribers
status yes Subscribers status to retrieve.

Get confirmed subscribers

// GET ALL ITEMS
$response = $endpoint->getConfirmedSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# TODO - Implement
"""
TODO - Implement
"""

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "3",
    "total_pages": 1,
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "records": [
      {
        "subscriber_uid": "jl349100yda86",
        "EMAIL": "elacroutz6@youku.com",
        "FNAME": "",
        "LNAME": "",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:15"
      },
      {
        "subscriber_uid": "kw647a5n8l516",
        "EMAIL": "mstephenson5@trellian.com",
        "FNAME": "",
        "LNAME": "",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:15"
      },
      {
        "subscriber_uid": "vo155s4b0d0ad",
        "EMAIL": "ldefew4@dailymail.co.uk",
        "FNAME": "",
        "LNAME": "",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:14"
      }
    ]
  }
}

This endpoint retrieves all the confirmed subscribers of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.
LIST-UNIQUE-ID The list unique identifier for which we retrieve the subscribers

Get unconfirmed subscribers

// GET ALL ITEMS
$response = $endpoint->getUnconfirmedSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# TODO - Implement
"""
TODO - Implement
"""

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "3",
    "total_pages": 1,
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "records": [
      {
        "subscriber_uid": "jl349100yda86",
        "EMAIL": "elacroutz6@youku.com",
        "FNAME": "",
        "LNAME": "",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:15"
      },
      {
        "subscriber_uid": "kw647a5n8l516",
        "EMAIL": "mstephenson5@trellian.com",
        "FNAME": "",
        "LNAME": "",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:15"
      },
      {
        "subscriber_uid": "vo155s4b0d0ad",
        "EMAIL": "ldefew4@dailymail.co.uk",
        "FNAME": "",
        "LNAME": "",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:14"
      }
    ]
  }
}

This endpoint retrieves all the unconfirmed subscribers of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.
LIST-UNIQUE-ID The list unique identifier for which we retrieve the subscribers

Get unsubscribed subscribers

// GET ALL ITEMS
$response = $endpoint->getUnsubscribedSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# TODO - Implement
"""
TODO - Implement
"""

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "3",
    "total_pages": 1,
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "records": [
      {
        "subscriber_uid": "jl349100yda86",
        "EMAIL": "elacroutz6@youku.com",
        "FNAME": "",
        "LNAME": "",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:15"
      },
      {
        "subscriber_uid": "kw647a5n8l516",
        "EMAIL": "mstephenson5@trellian.com",
        "FNAME": "",
        "LNAME": "",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:15"
      },
      {
        "subscriber_uid": "vo155s4b0d0ad",
        "EMAIL": "ldefew4@dailymail.co.uk",
        "FNAME": "",
        "LNAME": "",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:14"
      }
    ]
  }
}

This endpoint retrieves all the unsubscribed subscribers of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.
LIST-UNIQUE-ID The list unique identifier for which we retrieve the subscribers

Create a subscriber

// ADD SUBSCRIBER
$response = $endpoint->create('LIST-UNIQUE-ID', [
    'EMAIL'    => 'john.doe@doe.com', // the confirmation email will be sent!!! Use valid email address
    'FNAME'    => 'John',
    'LNAME'    => 'Doe'
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# ADD SUBSCRIBER
response = endpoint.create(list_uid = 'LIST-UNIQUE-ID', data = {
    'EMAIL': 'john.doe@example.com', # the confirmation email will be sent!!! Use valid email address
    'FNAME': 'John',
    'LNAME': 'Doe'
})
"""
ADD SUBSCRIBER
"""
response = endpoint.create(list_uid='LIST-UNIQUE-ID', data={
    'EMAIL': 'john.doe@example.com',  # the confirmation email will be sent!!! Use valid email address
    'FNAME': 'John',
    'LNAME': 'Doe'
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success",
  "data": {
    "record": {
      "subscriber_uid": "bm421c3lwe043",
      "email": "john.doe@doe.com",
      "ip_address": "5.13.134.200",
      "source": "api",
      "date_added": {
        "expression": "NOW()",
        "params": {}
      }
    }
  }
}

This endpoint creates a subscriber

HTTP Request

POST API-URL/lists/LIST-UNIQUE-ID/subscribers/create

POST Parameters

Parameter Type Required Description
LIST-UNIQUE-ID string yes List unique identifier
data array yes Array with the custom fields {name => value}. The EMAIL key is required.

Create subscribers in bulk

// ADD SUBSCRIBERS IN BULK (since MailWizz 1.8.1)
$response = $endpoint->createBulk('LIST-UNIQUE-ID', [
    [
        'EMAIL'    => 'john.doe-1@doe.com',
        'FNAME'    => 'John',
        'LNAME'    => 'Doe'
    ],
    [
        'EMAIL'    => 'john.doe-2@doe.com',
        'FNAME'    => 'John',
        'LNAME'    => 'Doe'
    ],
    [
        'EMAIL'    => 'john.doe-3@doe.com',
        'FNAME'    => 'John',
        'LNAME'    => 'Doe'
    ]
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# ADD SUBSCRIBERS IN BULK (since MailWizz 1.8.1)
response = endpoint.create_bulk(list_uid = 'LIST-UNIQUE-ID', data = [
    {
        'EMAIL': 'john.doe1111@example.com', # the confirmation email will be sent!!! Use valid email address
        'FNAME': 'John111',
        'LNAME': 'Doe111'
    },
    {
        'EMAIL': 'john.doe2222@example.com', # the confirmation email will be sent!!! Use valid email address
        'FNAME': 'John222',
        'LNAME': 'Doe222'
    },
    {
        'EMAIL': 'john.doe3333@example.com', # the confirmation email will be sent!!! Use valid email address
        'FNAME': 'John333',
        'LNAME': 'Doe333'
    },
])
"""
ADD SUBSCRIBERS IN BULK (since MailWizz 1.8.1)
"""
response = endpoint.create_bulk(list_uid='LIST-UNIQUE-ID', data=[
    {
        'EMAIL': 'john.doe1@example.com',  # the confirmation email will be sent!!! Use valid email address
        'FNAME': 'John1',
        'LNAME': 'Doe1'
    },
    {
        'EMAIL': 'john.doe2@example.com',  # the confirmation email will be sent!!! Use valid email address
        'FNAME': 'John2',
        'LNAME': 'Doe2'
    },
    {
        'EMAIL': 'john.doe3@example.com',  # the confirmation email will be sent!!! Use valid email address
        'FNAME': 'John3',
        'LNAME': 'Doe3'
    },
])

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success",
  "data": {
    "records": [
      {
        "data": {
          "subscriber_uid": "kw647a5n8l516",
          "EMAIL": "john.doe1@example.com",
          "FNAME": "John1",
          "LNAME": "Doe1",
          "status": "confirmed",
          "source": "import",
          "ip_address": "",
          "date_added": "2021-02-20 17:26:14"
        }
      },
      {
        "data": {
          "subscriber_uid": "fy287b32cs054",
          "EMAIL": "john.doe1@example.com",
          "FNAME": "John2",
          "LNAME": "Doe2",
          "status": "confirmed",
          "source": "import",
          "ip_address": "",
          "date_added": "2021-02-20 17:26:14"
        }
      },
      {
        "data": {
          "subscriber_uid": "vo155s4b0d0ad",
          "EMAIL": "john.doe3@example.com",
          "FNAME": "John3",
          "LNAME": "Doe3",
          "status": "confirmed",
          "source": "import",
          "ip_address": "",
          "date_added": "2021-02-20 17:26:14"
        }
      }
    ]
  }
}

This endpoint creates subscribers in bulk

HTTP Request

POST API-URL/lists/LIST-UNIQUE-ID/subscribers/bulk

POST Parameters

Parameter Type Required Description
LIST-UNIQUE-ID string yes List unique identifier
array string yes Array of arrays with the custom fields {name => value}. The EMAIL key is required.

Update a subscriber

// UPDATE EXISTING SUBSCRIBER
$response = $endpoint->update('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', [
    'EMAIL'    => 'john.doe@doe.com',
    'FNAME'    => 'John',
    'LNAME'    => 'Doe Updated'
]);

// DISPLAY RESPONSE
echo '<hr />';
echo '<pre>';
print_r($response->body);
echo '</pre>';
# UPDATE EXISTING SUBSCRIBER
response = endpoint.update(list_uid = 'LIST-UNIQUE-ID', subscriber_uid = 'SUBSCRIBER-UNIQUE_ID', data = {
    'EMAIL': 'john.doe.updated@example.com', # the confirmation email will be sent!!! Use valid email address
    'FNAME': 'John Updated',
    'LNAME': 'Doe Updated'
})

# DISPLAY RESPONSE
puts response.body
"""
UPDATE EXISTING SUBSCRIBER
"""
response = endpoint.update(list_uid='LIST-UNIQUE-ID', subscriber_uid='SUBSCRIBER-UNIQUE_ID', data={
    'EMAIL': 'john.doe.updated@example.com',  # the confirmation email will be sent!!! Use valid email address
    'FNAME': 'John Updated',
    'LNAME': 'Doe Updated'
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "record": {
      "subscriber_uid": "kw647a5n8l516",
      "email": "john.doe.updated@example.com",
      "ip_address": "10.10.10.10",
      "source": "api",
      "date_added": "2021-02-20 17:26:14"
    }
  }
}

This endpoint update the subscriber with the given SUBSCRIBER-UNIQUE-ID from the given list LIST-UNIQUE-ID.

HTTP Request

PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/update/SUBSCRIBER-UNIQUE-ID

POST Parameters

Parameter Type Required Description
LIST-UNIQUE-ID string yes List unique identifier
SUBSCRIBER-UNIQUE-ID string yes Subscriber unique identifier
data array yes Array with the custom fields {name => value} to be updated.

Update a subscriber by email

// UPDATE EXISTING SUBSCRIBER BY EMAIL
$response = $endpoint->updateByEmail('LIST-UNIQUE-ID', 'john@doe.com', [
    'EMAIL'    => 'john.doe@doe.com',
    'FNAME'    => 'John',
    'LNAME'    => 'Doe Updated'
]);

// DISPLAY RESPONSE
echo '<hr />';
echo '<pre>';
print_r($response->body);
echo '</pre>';
# TODO - to be implemented
"""
TODO - to be implemented
"""

The above command returns an object structured like this JSON:

{
  "status":"success",
  "data": {
    "record": {
      "subscriber_uid": "kw647a5n8l516",
      "email": "john.doe@doe.com",
      "ip_address": "10.10.10.10",
      "source": "api",
      "date_added": "2021-02-20 17:26:14"
    }
  }
}

This endpoint update the subscriber with the given EMAIL from the given list LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email

POST API-URL/lists/LIST-UNIQUE-ID/subscribers/update/SUBSCRIBER-UNIQUE-ID

GET/POST Parameters

Parameter Type Required Description
LIST-UNIQUE-ID string yes List unique identifier
EMAIL string yes Email to be searched
data array yes Array with the custom fields {name => value} to be updated.

Create/Update a subscriber

// CREATE / UPDATE EXISTING SUBSCRIBER
$response = $endpoint->createUpdate('LIST-UNIQUE-ID', [
    'EMAIL'    => 'john.doe@doe.com',
    'FNAME'    => 'John',
    'LNAME'    => 'Doe Updated Second time'
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# CREATE / UPDATE EXISTING SUBSCRIBER
response = endpoint.create_update(list_uid = 'LIST-UNIQUE-ID', data = {
    'EMAIL': 'john.doe@doe.com', # the confirmation email will be sent!!! Use valid email address
    'FNAME': 'John Updated ah',
    'LNAME': 'Doe Updated'
})


# DISPLAY RESPONSE
puts response.body
"""
CREATE / UPDATE EXISTING SUBSCRIBER
"""
response = endpoint.create_update(list_uid='LIST-UNIQUE-ID', data={
    'EMAIL': 'john.doe@doe.com',  # the confirmation email will be sent!!! Use valid email address
    'FNAME': 'John Updated',
    'LNAME': 'Doe Updated'
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success",
  "data": {
    "record": {
      "subscriber_uid": "kw647a5n8l516",
      "email": "john.doe@doe.com",
      "ip_address": "10.10.10.10",
      "source": "api",
      "date_added": "2021-02-20 17:26:14"
    }
  }
}

This endpoint update the subscriber if exists and created it otherwise, from the given list LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email

POST API-URL/lists/LIST-UNIQUE-ID/subscribers/update/SUBSCRIBER-UNIQUE-ID

POST API-URL/lists/LIST-UNIQUE-ID/subscribers/create

GET/POST Parameters

Parameter Type Required Description
LIST-UNIQUE-ID string yes List unique identifier
data array yes Array with the custom fields {name => value} to be updated.

Unsubscribe a subscriber

// UNSUBSCRIBE existing subscriber, no email is sent, unsubscribe is silent
$response = $endpoint->unsubscribe('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';

# UNSUBSCRIBE existing subscriber, no email is sent, unsubscribe is silent
response = endpoint.unsubscribe(list_uid = 'LIST-UNIQUE-ID', subscriber_uid = 'SUBSCRIBER-UNIQUE-ID')

# DISPLAY RESPONSE
puts response.body
"""
UNSUBSCRIBE existing subscriber, no email is sent, unsubscribe is silent
"""
response = endpoint.unsubscribe(list_uid='LIST-UNIQUE-ID', subscriber_uid='SUBSCRIBER-UNIQUE-ID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success"
}

This endpoint unsubscribes the subscriber with the given SUBSCRIBER-UNIQUE-ID from the given LIST-UNIQUE-ID.

HTTP Request

PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID/unsubscribe

Query Parameters

Parameter Required Description
LIST-UNIQUE-ID yes List unique id to which the subscriber belongs.
SUBSCRIBER-UNIQUE-ID yes Subscriber unique id to unsubscribe.

Unsubscribe a subscriber by email address

// UNSUBSCRIBE existing subscriber by email address, no email is sent, unsubscribe is silent
$response = $endpoint->unsubscribeByEmail('LIST-UNIQUE-ID', 'john@doe.com');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# UNSUBSCRIBE existing subscriber by email address, no email is sent, unsubscribe is silent
response = endpoint.unsubscribe_by_email(list_uid = 'LIST-UNIQUE-ID', email_address = 'john.doe@example.com')

# DISPLAY RESPONSE
puts response.body
"""
UNSUBSCRIBE existing subscriber by email address, no email is sent, unsubscribe is silent
"""
response = endpoint.unsubscribe_by_email(list_uid='LIST-UNIQUE-ID', email_address='john.doe@example.com')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success"
}

This endpoint unsubscribes the subscriber with the given EMAIL from the given LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email

PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID/unsubscribe

Query Parameters

Parameter Required Description
LIST-UNIQUE-ID yes List unique id to which the subscriber belongs.
EMAIL yes Subscriber email to unsubscribe.

Unsubscribe a subscriber by email address from all the lists

// UNSUBSCRIBE existing subscriber from all lists, no email is sent, unsubscribe is silent
$response = $endpoint->unsubscribeByEmailFromAllLists('john@doe.com');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# UNSUBSCRIBE existing subscriber by email address from all lists, no email is sent, unsubscribe is silent
response = endpoint.unsubscribe_by_email_from_all_lists(email_address = 'john.doe@example.com')

# DISPLAY RESPONSE
puts response.body
"""
UNSUBSCRIBE existing subscriber by email address from all lists, no email is sent, unsubscribe is silent
"""
response = endpoint.unsubscribe_by_email_from_all_lists(email_address='john.doe@example.com')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success"
}

This endpoint unsubscribes the subscriber with the given EMAIL from all the lists.

HTTP Request

PUT API-URL/lists/subscribers/unsubscribe-by-email-from-all-lists

Query Parameters

Parameter Required Description
EMAIL yes Subscriber email to unsubscribe.

Delete one subscriber

// DELETE SUBSCRIBER, no email is sent, delete is silent
$response = $endpoint->delete('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# DELETE SUBSCRIBER, no email is sent, delete is silent
response = endpoint.delete(list_uid = 'LIST-UNIQUE-ID', subscriber_uid = 'SUBSCRIBER-UNIQUE-ID')

# DISPLAY RESPONSE
puts response.body
"""
DELETE SUBSCRIBER, no email is sent, delete is silent
"""
response = endpoint.delete(list_uid='LIST-UNIQUE-ID', subscriber_uid='SUBSCRIBER-UNIQUE-ID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success"
}

This endpoint deletes the subscriber with the given SUBSCRIBER-UNIQUE-ID from the given LIST-UNIQUE-ID.

HTTP Request

DELETE API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID

Query Parameters

Parameter Required Description
LIST-UNIQUE-ID yes List unique id to which the subscriber belongs.
SUBSCRIBER-UNIQUE-ID yes Subscriber unique id to delete.

Delete by email

// DELETE SUBSCRIBER by email address, no email is sent, delete is silent
$response = $endpoint->deleteByEmail('LIST-UNIQUE-ID', 'john@doe.com');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# DELETE SUBSCRIBER by email address, no email is sent, delete is silent
response = endpoint.delete_by_email(list_uid = 'LIST-UNIQUE-ID', email_address = 'john.doe@example.com')

# DISPLAY RESPONSE
puts response.body
"""
DELETE SUBSCRIBER by email address, no email is sent, delete is silent
"""
response = endpoint.delete_by_email(list_uid='LIST-UNIQUE-ID', email_address='john.doe@example.com')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success"
}

This endpoint deletes a subscriber by his email within the list having the LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email

DELETE API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID

Query Parameters

Parameter Required Description
LIST-UNIQUE-ID yes List unique id to which the subscriber to retrieve belongs.
email yes Subscriber email to retrieve.

Campaigns

Campaigns endpoint

// CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\Campaigns();
# CREATE THE ENDPOINT
endpoint = Campaigns.new 
from datetime import datetime, timedelta
from mailwizz.endpoint.campaigns import Campaigns

"""
CREATE THE ENDPOINT
"""
endpoint = Campaigns()

Get all campaigns

// GET ALL ITEMS
$response = $endpoint->getCampaigns($pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo "<pre>";
print_r($response->body);
echo "</pre>";
# GET ALL ITEMS
response = endpoint.get_campaigns(page = 1, per_page = 10)

# DISPLAY RESPONSE
puts response.body
"""
GET ALL ITEMS
"""
response = endpoint.get_campaigns(page=1, per_page=10)

"""
DISPLAY RESPONSE
"""
print(response.content) 

The above command returns an object structured like this JSON:

[
  {
    "status": "success",
    "data": {
      "count": "12",
      "total_pages": 2,
      "current_page": 1,
      "next_page": 2,
      "prev_page": null,
      "records": [
        {
          "campaign_uid": "og943e5q6e158",
          "name": "My API Campaign UPDATED #3",
          "status": "sent",
          "group": []
        },
        {
          "campaign_uid": "gp5420ve90f3e",
          "name": "My API Campaign UPDATED #2",
          "status": "sent",
          "group": []
        },
        {
          "campaign_uid": "hv4163y076d84",
          "name": "My API Campaign UPDATED #1",
          "status": "sent",
          "group": []
        },
        {
          "campaign_uid": "xk906nd8fn506",
          "name": "My API Campaign UPDATED",
          "status": "sent",
          "group": []
        },
        {
          "campaign_uid": "eh477yfos0258",
          "name": "API campaing #1",
          "status": "draft",
          "group": []
        },
        {
          "campaign_uid": "db516xtc45237",
          "name": "API campaing #2",
          "status": "draft",
          "group": []
        },
        {
          "campaign_uid": "ld526wjke1ff4",
          "name": "API campaing #1",
          "status": "draft",
          "group": []
        },
        {
          "campaign_uid": "bx831rctawf92",
          "name": "API campaing",
          "status": "paused",
          "group": []
        },
        {
          "campaign_uid": "tk459h475l8ef",
          "name": "Test #1",
          "status": "sent",
          "group": []
        },
        {
          "campaign_uid": "go896lnslz8ae",
          "name": "Test",
          "status": "sent",
          "group": []
        }
      ]
    }
  }
]

This endpoint retrieves all the campaigns.

HTTP Request

GET API-URL/campaigns

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.

Get one campaign

// GET ONE ITEM
$response = $endpoint->getCampaign('CAMPAIGN-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# GET ONE ITEM
response = endpoint.get_campaign('CAMPAIGN_UID')

# DISPLAY RESPONSE
puts response.body 
"""
GET ONE ITEM
"""
response = endpoint.get_campaign('CAMPAIGN_UID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "record": {
      "campaign_uid": "og943e5q6e158",
      "name": "My API Campaign UPDATED #3",
      "type": "regular",
      "from_name": "John Doe",
      "from_email": "john.doe@doe.com",
      "to_name": "[EMAIL]",
      "reply_to": "john.doe@doe.com",
      "subject": "Hey, i am testing the campaigns via API",
      "status": "sent",
      "date_added": "2\/24\/21, 11:38 PM",
      "send_at": "2\/24\/21, 11:39 PM",
      "list": {
        "list_uid": "ra5026psrjeb5",
        "name": "Testing list",
        "subscribers_count": 0
      },
      "segment": [],
      "group": []
    }
  }
}

This endpoint retrieves the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

GET API-URL/campaigns

Query Parameters

Parameter Required Description
CAMPAIGN-UNIQUE-ID yes Campaign unique id to retrieve.

Create a campaign

// CREATE CAMPAIGN
$response = $endpoint->create([
    'name'          => 'My API Campaign', // required
    'type'          => 'regular', // optional: regular or autoresponder
    'from_name'     => 'John Doe', // required
    'from_email'    => 'john.doe@doe.com', // required
    'subject'       => 'Hey, i am testing the campaigns via API', // required
    'reply_to'      => 'john.doe@doe.com', // required
    'send_at'       => date('Y-m-d H:i:s', strtotime('+10 hours')), // required, this will use the timezone which customer selected
    'list_uid'      => 'LIST-UNIQUE-ID', // required
    'segment_uid'   => 'SEGMENT-UNIQUE-ID',// optional, only to narrow down

    // optional block, defaults are shown
    'options' => [
        'url_tracking'      => 'no', // yes | no
        'json_feed'         => 'no', // yes | no
        'xml_feed'          => 'no', // yes | no
        'plain_text_email'  => 'yes',// yes | no
        'email_stats'       => null, // a valid email address where we should send the stats after campaign done

        // - if autoresponder uncomment bellow:
        //'autoresponder_event'            => 'AFTER-SUBSCRIBE', // AFTER-SUBSCRIBE or AFTER-CAMPAIGN-OPEN
        //'autoresponder_time_unit'        => 'hour', // minute, hour, day, week, month, year
        //'autoresponder_time_value'       => 1, // 1 hour after event
        //'autoresponder_open_campaign_id' => 1, // INT id of campaign, only if event is AFTER-CAMPAIGN-OPEN,

        // - if this campaign is advanced recurring, you can set a cron job style frequency.
        // - please note that this applies only for regular campaigns.
        //'cronjob'         => '0 0 * * *', // once a day
        //'cronjob_enabled' => 1, // 1 or 0
    ],

    // required block, archive or template_uid or content => required.
    'template' => [
        //'archive'         => file_get_contents(__DIR__ . '/template-example.zip'),
        //'template_uid'    => 'TEMPLATE-UNIQUE-ID',
        'content'           => file_get_contents(__DIR__ . '/template-example.html'),
        'inline_css'        => 'no', // yes | no
        'plain_text'        => null, // leave empty to auto generate
        'auto_plain_text'   => 'yes', // yes | no
    ],
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# CREATE ONE CAMPAIGN
response = endpoint.create({
    'name': 'My API Campaign', # required
    'type': 'regular', # optional: regular or autoresponder
    'from_name': 'John Doe', # required
    'from_email': 'john.doe@doe.com', # required
    'subject': 'Hey, i am testing the campaigns via API', # required
    'reply_to': 'john.doe@doe.com', # required
    #required, this will use the timezone which customer selected
    'send_at': Time.now.strftime('%Y-%m-%d %H:%M:%S'),
    'list_uid': 'LIST_UID', # required
    #'segment_uid'   : 'SEGMENT-UNIQUE-ID',# optional, only to narrow down

    #optional block, defaults are shown
    'options': {
       'url_tracking': 'no', # yes | no
       'json_feed': 'no', # yes | no
       'xml_feed': 'no', # yes | no
       'plain_text_email': 'yes', # yes | no
       'email_stats': nil, # a valid email address where we should send the stats after campaign done

       # - if autoresponder uncomment bellow:
       # 'autoresponder_event'            : 'AFTER-SUBSCRIBE', # AFTER-SUBSCRIBE or AFTER-CAMPAIGN-OPEN
       # 'autoresponder_time_unit'        : 'hour', # minute, hour, day, week, month, year
       # 'autoresponder_time_value'       : 1, # 1 hour after event
       # 'autoresponder_open_campaign_id' : 1, # INT id of campaign, only if event is AFTER-CAMPAIGN-OPEN,

       # - if this campaign is advanced recurring, you can set a cron job style frequency.
       # - please note that this applies only for regular campaigns.
       # 'cronjob'         : '0 0 * * *', # once a day
       # 'cronjob_enabled' : 1, # 1 or 0
    },

    # required block, archive or template_uid or content : required.
    # the templates examples can be found here: Examples
    'template': {
       # 'archive': File.read('template-example.zip'),
       # # 'template_uid': 'template_uid',
       'content': File.read('template-example.html'),
       'inline_css': 'no', # yes | no
       # 'plain_text': nil, # leave empty to auto generate
       'auto_plain_text': 'yes', # yes | no
    },
    })
# DISPLAY RESPONSE
puts response.body
"""
CREATE ONE CAMPAIGN
"""
response = endpoint.create({
    'name': 'My API Campaign',  # required
    'type': 'regular',  # optional: regular or autoresponder
    'from_name': 'John Doe',  # required
    'from_email': 'john.doe@doe.com',  # required
    'subject': 'Hey, i am testing the campaigns via API',  # required
    'reply_to': 'john.doe@doe.com',  # required
    'send_at': (datetime.now() + timedelta(hours=10)).strftime('%Y-%m-%d %H:%M:%S'),
    # required, this will use the timezone which customer selected
    'list_uid': 'LIST_UID',  # required
    # 'segment_uid'   : 'SEGMENT-UNIQUE-ID',# optional, only to narrow down

    # optional block, defaults are shown
    'options': {
        'url_tracking': 'no',  # yes | no
        'json_feed': 'no',  # yes | no
        'xml_feed': 'no',  # yes | no
        'plain_text_email': 'yes',  # yes | no
        'email_stats': None,  # a valid email address where we should send the stats after campaign done

        # - if autoresponder uncomment bellow:
        # 'autoresponder_event'            : 'AFTER-SUBSCRIBE', # AFTER-SUBSCRIBE or AFTER-CAMPAIGN-OPEN
        # 'autoresponder_time_unit'        : 'hour', # minute, hour, day, week, month, year
        # 'autoresponder_time_value'       : 1, # 1 hour after event
        # 'autoresponder_open_campaign_id' : 1, # INT id of campaign, only if event is AFTER-CAMPAIGN-OPEN,

        # - if this campaign is advanced recurring, you can set a cron job style frequency.
        # - please note that this applies only for regular campaigns.
        # 'cronjob'         : '0 0 * * *', # once a day
        # 'cronjob_enabled' : 1, # 1 or 0
    },

    # required block, archive or template_uid or content : required.
    # the templates examples can be found here: Examples
    'template': {
        # 'archive'        : open('template-example.zip', 'r').read(),
        'template_uid': 'TEMPLATE_UID',
        # 'content'         : open('template-example.html', 'rb').read(),
        'inline_css': 'no',  # yes | no
        # 'plain_text'      : None, # leave empty to auto generate
        'auto_plain_text': 'yes',  # yes | no
    },
})

"""
DISPLAY RESPONSE
"""
print(response.content) 

The above command returns an object structured like this JSON:

{
  "status":"success",
  "campaign_uid": "hv4163y076d84"
}

This endpoint creates a campaign

HTTP Request

POST API-URL/campaigns

POST Parameters

Parameter Type Required Description
name string yes Campaign name.
type string no Campaign type: regular or autoresponder. Default is regular.
from_name string yes The campaign from name
from_email string yes The campaign from email address
subject string yes The campaign subject
from_name string yes The subscriber for which we record the bounce
reply_to string yes The campaign reply to email address
send_at datetime (Y-m-d H:i:s) yes This will use the timezone which customer selected
list_uid string yes The list uid to which this campaign will be sent
segment_uid string no Narrow down the campaign recipients
template array yes The campaign template object block. Archive or template_uid or content => required
options array no The campaign optional block, defaults are shown

Template block

Parameter Type Required Description
archive filePath yes Template file zip location
template_uid string yes Template unique id from MailWizz
content string yes Template content
inline_css yes/no yes Accept inline css
plain_text null/string no Send null to autogenerate as default
auto_plain_text yes/no yes Generate plain text template

Options block

Parameter Type Required Description
url_tracking yes/no no Enable/Disable url tracking
json_feed yes/no no Enable/Disable json feed
xml_feed yes/no no Enable/Disable xml feed
plain_text_email yes/no no Enable/Disable the plain text email
email_stats string/null no A valid email address where the stats will be sent
autoresponder_event string no Possible values: AFTER-SUBSCRIBE or AFTER-CAMPAIGN-OPEN
autoresponder_event string no Possible values: AFTER-SUBSCRIBE or AFTER-CAMPAIGN-OPEN
autoresponder_time_unit string no Possible values: minute, hour, day, week, month, year
autoresponder_time_value integer no The unit time value
autoresponder_time_value integer no The unit time value
autoresponder_open_campaign_id integer no Id of the campaign, only if event is AFTER-CAMPAIGN-OPEN
cronjob string no If this campaign is advanced recurring, you can set a cron job style frequency
cronjob_enabled integer no Possible values 1 or 0

Update a campaign

// UPDATE CAMPAIGN
$response = $endpoint->update('CAMPAIGN-UNIQUE-ID', [
    'name'          => 'My API Campaign UPDATED', // optional at update
    'from_name'     => 'John Doe', // optional at update
    'from_email'    => 'john.doe@doe.com', // optional at update
    'subject'       => 'Hey, i am testing the campaigns via API', // optional at update
    'reply_to'      => 'john.doe@doe.com', // optional at update
    'send_at'       => date('Y-m-d H:i:s', strtotime('+1 hour')), //optional at update, this will use the timezone which customer selected
    'list_uid'      => 'LIST-UNIQUE-ID', // optional at update
    'segment_uid'   => 'SEGMENT-UNIQUE-ID',// optional, only to narrow down

    // optional block, defaults are shown
    'options' => [
        'url_tracking'      => 'no', // yes | no
        'json_feed'         => 'no', // yes | no
        'xml_feed'          => 'no', // yes | no
        'plain_text_email'  => 'yes',// yes | no
        'email_stats'       => null, // a valid email address where we should send the stats after campaign done
    ],

    // optional block at update, archive or template_uid or content => required.
    'template' => [
        //'archive'         => file_get_contents(__DIR__ . '/template-example.zip'),
        //'template_uid'    => 'TEMPLATE-UNIQUE-ID',
        'content'           => file_get_contents(__DIR__ . '/template-example.html'),
        'inline_css'        => 'no', // yes | no
        'plain_text'        => null, // leave empty to auto generate
        'auto_plain_text'   => 'yes', // yes | no
    ],
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# UPDATE ONE CAMPAIGN
response = endpoint.update('CAMPAIGN_UID', {
    'name': 'My API Campaign - UPDATED', # required
    'from_name': 'John Doe', # required
    'from_email': 'john.doe@doe.com', # required
    'subject': 'Hey, i am testing the campaigns via API', # required
    'reply_to': 'john.doe@doe.com', # required
    'send_at': Time.now.strftime('%Y-%m-%d %H:%M:%S'),
    # required, this will use the timezone which customer selected
    'list_uid': 'LIST_UID', # required
    # 'segment_uid'   : 'SEGMENT-UNIQUE-ID',# optional, only to narrow down

    # optional block, defaults are shown
    'options': {
        'url_tracking': 'no', # yes | no
        'json_feed': 'no', # yes | no
        'xml_feed': 'no', # yes | no
        'plain_text_email': 'yes', # yes | no
        'email_stats': nil, # a valid email address where we should send the stats after campaign done

        # - if autoresponder uncomment bellow:
        # 'autoresponder_event'            : 'AFTER-SUBSCRIBE', # AFTER-SUBSCRIBE or AFTER-CAMPAIGN-OPEN
        # 'autoresponder_time_unit'        : 'hour', # minute, hour, day, week, month, year
        # 'autoresponder_time_value'       : 1, # 1 hour after event
        # 'autoresponder_open_campaign_id' : 1, # INT id of campaign, only if event is AFTER-CAMPAIGN-OPEN,

        # - if this campaign is advanced recurring, you can set a cron job style frequency.
        # - please note that this applies only for regular campaigns.
        # 'cronjob'         : '0 0 * * *', # once a day
        # 'cronjob_enabled' : 1, # 1 or 0
    },

    # required block, archive or template_uid or content : required.
    # the templates examples can be found here: Examples
    'template': {
        # 'archive': File.read('template-example.zip'),
        'template_uid': 'TEMPLATE_UID',
        # 'content': File.read('template-example.html'),
        'inline_css': 'no', # yes | no
        # 'plain_text': nil, # leave empty to auto generate
        'auto_plain_text': 'yes', # yes | no
    },
})

# DISPLAY RESPONSE
puts response.body
"""
UPDATE ONE CAMPAIGN
"""
response = endpoint.update('CAMPAIGN_UID', {
    'name': 'My API Campaign - UPDATED',  # required
    'from_name': 'John Doe',  # required
    'from_email': 'john.doe@doe.com',  # required
    'subject': 'Hey, i am testing the campaigns via API',  # required
    'reply_to': 'john.doe@doe.com',  # required
    'send_at': (datetime.now() + timedelta(hours=10)).strftime('%Y-%m-%d %H:%M:%S'),
    # required, this will use the timezone which customer selected
    'list_uid': 'LIST_UID',  # required
    # 'segment_uid'   : 'SEGMENT-UNIQUE-ID',# optional, only to narrow down

    # optional block, defaults are shown
    'options': {
        'url_tracking': 'no',  # yes | no
        'json_feed': 'no',  # yes | no
        'xml_feed': 'no',  # yes | no
        'plain_text_email': 'yes',  # yes | no
        'email_stats': None,  # a valid email address where we should send the stats after campaign done

        # - if autoresponder uncomment bellow:
        # 'autoresponder_event'            : 'AFTER-SUBSCRIBE', # AFTER-SUBSCRIBE or AFTER-CAMPAIGN-OPEN
        # 'autoresponder_time_unit'        : 'hour', # minute, hour, day, week, month, year
        # 'autoresponder_time_value'       : 1, # 1 hour after event
        # 'autoresponder_open_campaign_id' : 1, # INT id of campaign, only if event is AFTER-CAMPAIGN-OPEN,

        # - if this campaign is advanced recurring, you can set a cron job style frequency.
        # - please note that this applies only for regular campaigns.
        # 'cronjob'         : '0 0 * * *', # once a day
        # 'cronjob_enabled' : 1, # 1 or 0
    },

    # required block, archive or template_uid or content : required.
    # the templates examples can be found here: Examples
    'template': {
        # 'archive'        : open('template-example.zip', 'r').read(),
        'template_uid': 'TEMPLATE_UID',
        # 'content'         : open('template-example.html', 'rb').read(),
        'inline_css': 'no',  # yes | no
        # 'plain_text'      : None, # leave empty to auto generate
        'auto_plain_text': 'yes',  # yes | no
    },
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success"
}

This endpoint update the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

PUT API-URL/campaigns/CAMPAIGN-UNIQUE-ID

Query Parameters

Parameter Required Description
CAMPAIGN-UNIQUE-ID yes Campaign unique id to update.

Copy a campaign

// Copy CAMPAIGN
$response = $endpoint->copy('CAMPAIGN-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# COPY ONE CAMPAIGN
response = endpoint.copy('CAMPAIGN_UID')

# DISPLAY RESPONSE
puts response.body
"""
COPY ONE CAMPAIGN
"""
response = endpoint.copy('CAMPAIGN_UID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success",
  "campaign_uid": "hv4163y076d84"
}

This endpoint copy the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

POST API-URL/campaigns/CAMPAIGN-UNIQUE-ID/copy

Query Parameters

Parameter Required Description
CAMPAIGN-UNIQUE-ID yes Campaign unique id to copy.

Pause/Unpause a campaign

// Pause/Unpause CAMPAIGN
$response = $endpoint->pauseUnpause('CAMPAIGN-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# PAUSE/UNPAUSE ONE CAMPAIGN
response = endpoint.pause_unpause('CAMPAIGN_UID')

# DISPLAY RESPONSE
puts response.body
"""
PAUSE/UNPAUSE ONE CAMPAIGN
"""
response = endpoint.pause_unpause('CAMPAIGN_UID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "campaign": {
    "status": "sending"
  }
}

This endpoint pause/unpause the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

PUT API-URL/campaigns/CAMPAIGN-UNIQUE-ID/pause-unpause

Query Parameters

Parameter Required Description
CAMPAIGN-UNIQUE-ID yes Campaign unique id to pause/unpause.

Mark a campaign as SENT

// Mark CAMPAIGN as sent
$response = $endpoint->markSent('CAMPAIGN-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# MARK ONE CAMPAIGN AS SENT
response = endpoint.mark_sent('CAMPAIGN_UID')

# DISPLAY RESPONSE
puts response.body
"""
MARK ONE CAMPAIGN AS SENT
"""
response = endpoint.mark_sent('CAMPAIGN_UID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "campaign": {
    "status": "sent"
  }
}

This endpoint mark as SENT the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

PUT API-URL/campaigns/CAMPAIGN-UNIQUE-ID/mark-sent

Query Parameters

Parameter Required Description
CAMPAIGN-UNIQUE-ID yes Campaign unique id to mark as sent.

Delete a campaign

// Delete CAMPAIGN
$response = $endpoint->delete('CAMPAIGN-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# DELETE ONE CAMPAIGN
response = endpoint.delete('CAMPAIGN_UID')

# DISPLAY RESPONSE
puts response.body
"""
DELETE ONE CAMPAIGN
"""
response = endpoint.delete('CAMPAIGN_UID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status":"success"
}

This endpoint will delete the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

DELETE API-URL/campaigns/CAMPAIGN-UNIQUE-ID

Query Parameters

Parameter Required Description
CAMPAIGN-UNIQUE-ID yes Campaign unique id to delete.

Get stats of a campaign

// GET STATS
$response = $endpoint->getStats('CAMPAIGN-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# TODO - Implement
"""
TODO - Implement
"""

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "campaign_status": "sent",
    "subscribers_count": 0,
    "processed_count": 0,
    "delivery_success_count": 0,
    "delivery_success_rate": 0,
    "delivery_error_count": 0,
    "delivery_error_rate": 0,
    "opens_count": 0,
    "opens_rate": 0,
    "unique_opens_count": 0,
    "unique_opens_rate": 0,
    "clicks_count": 0,
    "clicks_rate": 0,
    "unique_clicks_count": 0,
    "unique_clicks_rate": 0,
    "unsubscribes_count": 0,
    "unsubscribes_rate": 0,
    "complaints_count": 0,
    "complaints_rate": 0,
    "bounces_count": 0,
    "bounces_rate": 0,
    "hard_bounces_count": 0,
    "hard_bounces_rate": 0,
    "soft_bounces_count": 0,
    "soft_bounces_rate": 0,
    "internal_bounces_count": 0,
    "internal_bounces_rate": 0
  }
}

This endpoint retrieves the campaign stats the given CAMPAIGN-UNIQUE-ID.

HTTP Request

GET API-URL/campaigns/CAMPAIGN-UNIQUE-ID/stats

Query Parameters

Parameter Required Description
CAMPAIGN-UNIQUE-ID yes Campaign unique id to retrieve.

Campaigns tracking

Campaigns tracking endpoint

// CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\CampaignsTracking();
# CREATE THE ENDPOINT
endpoint = CampaignsTracking.new
from mailwizz.endpoint.campaigns_tracking import CampaignsTracking

"""
CREATE THE ENDPOINT
"""
endpoint = CampaignsTracking()

Track subscriber click for campaign

// Track subscriber click for campaign click
$response = $endpoint->trackUrl('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', 'URL-HASH');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# Track subscriber click for campaign click
response = endpoint.track_url('CAMPAIGN_UID', 'SUBSCRIBER_UID', 'HASH_URL')

# DISPLAY RESPONSE
puts response.body
"""
Track subscriber click for campaign click
"""
response = endpoint.track_url(campaign_uid='CAMPAIGN_UID', subscriber_uid='SUBSCRIBER_UID', hash_string='')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {}
}

This endpoint set a campaign tracking url click action.

HTTP Request

GET API-URL/campaigns/CAMPAIGN-UID/track-url/SUBSCRIBER-UNIQUE-ID/URL-HASH

Query Parameters

Parameter Required Description
CAMPAIGN-UID Yes Campaign unique identifier.
SUBSCRIBER-UNIQUE-ID Yes Subscriber unique identifier.
URL-HASH Yes The url hash which the subscriber clicked.

Track subscriber open

// Track subscriber open for campaign
$response = $endpoint->trackOpening('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# Track subscriber open for campaign
response = endpoint.track_opening('CAMPAIGN_UID', 'SUBSCRIBER_UID')

# DISPLAY RESPONSE
puts response.body
"""
Track subscriber open for campaign
"""
response = endpoint.track_opening(campaign_uid='CAMPAIGN_UID', subscriber_uid='SUBSCRIBER_UID')

"""
DISPLAY RESPONSE
"""
print(response.content) 

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {}
}

This endpoint sets the track campaign open for a certain subscriber.

HTTP Request

GET API-URL/campaigns/CAMPAIGN-UID/track-opening/SUBSCRIBER-UID

Query Parameters

Parameter Required Description
CAMPAIGN-UID Yes Campaign unique identifier.
SUBSCRIBER-UNIQUE-ID Yes Subscriber unique identifier.

Track subscriber unsubscribe

// Track subscriber unsubscribe for campaign
$response = $endpoint->trackUnsubscribe('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', [
    'ip_address' => '123.123.123.123',
    'user_agent' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Safari/537.36',
    'reason'     => 'Reason for unsubscribe!',
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# Track subscriber unsubscribe for campaign
response = endpoint.track_unsubscribe('CAMPAIGN_UID', 'SUBSCRIBER_UID', {
    'ip_address': '123.123.123.123',
    'user_agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Safari/537.36',
    'reason': 'Reason for unsubscribe!',
})

# DISPLAY RESPONSE
puts response.body
"""
Track subscriber unsubscribe for campaign
"""
response = endpoint.track_unsubscribe(campaign_uid='CAMPAIGN_UID', subscriber_uid='SUBSCRIBER_UID', data={
    'ip_address': '123.123.123.123',
    'user_agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Safari/537.36',
    'reason': 'Reason for unsubscribe!',
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {}
}

This endpoint sets the track campaign unsubscribe for a certain subscriber.

HTTP Request

POST API-URL/campaigns/CAMPAIGN-UID/track-unsubscribe/SUBSCRIBER-UID

POST Parameters

Parameter Required Description
CAMPAIGN-UID Yes Campaign unique identifier.
SUBSCRIBER-UNIQUE-ID Yes Subscriber unique identifier.
ip_address No IP address from which the subscriber unsubscribes
user_agent No Subscriber user agent
reason No Unsubscribe reason

Campaign bounces

Campaigns bounces endpoint

// CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\CampaignBounces();
# CREATE THE ENDPOINT
endpoint = CampaignBounces.new 
from mailwizz.endpoint.campaign_bounces import CampaignBounces

"""
CREATE THE ENDPOINT
"""
endpoint = CampaignBounces()

Get all bounces

// GET ALL ITEMS
$response = $endpoint->getBounces($campaignUid = CAMPAIGN-UNIQUE-ID, $pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo "<pre>";
print_r($response->body);
echo "</pre>";
# GET ALL ITEMS
response = endpoint.get_bounces(campaign_uid = 'CAMAPAIGN-UNIQUE-ID', page = 1, per_page = 10)

# DISPLAY RESPONSE
puts response.body
"""
GET ALL ITEMS
"""
response = endpoint.get_bounces(campaign_uid='CAMAPAIGN-UNIQUE-ID', page=1, per_page=10)

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "1",
    "total_pages": 1,
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "records": [
      {
        "message": "5.1.1 : Recipient address rejected: User unknown in virtual mailbox table",
        "processed": "no",
        "bounce_type": "hard",
        "subscriber": {
          "subscriber_uid": "xq907cko16da3",
          "email": "user@example.com"
        }
      }
    ]
  }
}

This endpoint retrieves all the bounces of a campaign.

HTTP Request

GET API-URL/campaigns/CAMAPAIGN-UNIQUE-ID/bounces

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.

Create a bounce

// CREATE BOUNCE
$response = $endpoint->create('CAMPAIGN-UNIQUE-ID', [
    'message'        => 'The reason why this email bounced', // max 250 chars
    'bounce_type'    => 'hard', // hard, soft or internal
    'subscriber_uid' => 'SUBSCRIBER-UNIQUE-ID' // 13 chars unique subscriber identifier
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# CREATE BOUNCE
response = endpoint.create('CAMPAIGN-UNIQUE-ID', {
    # required
    'message': 'The reason why this email bounced',
    'bounce_type': 'hard',
    'subscriber_uid': 'SUBSCRIBER-UNIQUE-ID'
})

# DISPLAY RESPONSE
puts response.body
"""
CREATE BOUNCE
"""
response = endpoint.create('CAMPAIGN-UNIQUE-ID', {
    # required
    'message': 'The reason why this email bounced',
    'bounce_type': 'hard',
    'subscriber_uid': 'SUBSCRIBER-UNIQUE-ID'
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "record": {
      "message": "The reason why this email bounced",
      "processed": "no",
      "bounce_type": "hard",
      "subscriber": {
        "subscriber_uid": "fo428vd43x832",
        "email": "user@example.com"
      }
    }
  }
}

This endpoint creates a campaign bounce

HTTP Request

POST API-URL/campaigns/CAMAPAIGN-UNIQUE-ID/bounces

POST Parameters

Parameter Required Description
message yes The bounce message to be recorded.
bounce_type yes Bounce type (hard, soft or internal).
subscriber_uid yes The subscriber for which we record the bounce

Countries

Countries endpoint

// CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\Countries();
# CREATE THE ENDPOINT
endpoint = Countries.new
from mailwizz.endpoint.countries import Countries

"""
CREATE THE ENDPOINT
"""
endpoint = Countries()

Get all countries

// GET ALL ITEMS
$response = $endpoint->getCountries($pageNumber = 23, $perPage = 10);

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# GET ALL ITEMS
response = endpoint.get_countries(page = 1, per_page = 10)

# DISPLAY RESPONSE
puts response.body 
"""
GET ALL ITEMS
"""
response = endpoint.get_countries(page=1, per_page=10)

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "240",
    "total_pages": 24,
    "current_page": 23,
    "next_page": 24,
    "prev_page": 22,
    "records": [
      {
        "country_id": "218",
        "name": "Tuvalu",
        "code": "TV"
      },
      {
        "country_id": "219",
        "name": "Uganda",
        "code": "UG"
      },
      {
        "country_id": "220",
        "name": "Ukraine",
        "code": "UA"
      },
      {
        "country_id": "221",
        "name": "United Arab Emirates",
        "code": "AE"
      },
      {
        "country_id": "222",
        "name": "United Kingdom",
        "code": "GB"
      },
      {
        "country_id": "223",
        "name": "United States",
        "code": "US"
      },
      {
        "country_id": "224",
        "name": "United States Minor Outlying Islands",
        "code": "UM"
      },
      {
        "country_id": "225",
        "name": "Uruguay",
        "code": "UY"
      },
      {
        "country_id": "226",
        "name": "Uzbekistan",
        "code": "UZ"
      },
      {
        "country_id": "227",
        "name": "Vanuatu",
        "code": "VU"
      }
    ]
  }
}

This endpoint retrieves all the countries.

HTTP Request

GET API-URL/countries

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.

Get all zones of a country

// get country zones
$response = $endpoint->getZones(COUNTRY-ID, $pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# GET COUNTRY ZONES
response = endpoint.get_zones(country_id = COUNTRY-ID, page = 1, per_page = 10)

# DISPLAY RESPONSE
puts response.body
"""
GET COUNTRY ZONES
"""
response = endpoint.get_zones(country_id=COUNTRY-ID, page=1, per_page=10)

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "65",
    "total_pages": 7,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "records": [
      {
        "zone_id": "3613",
        "name": "Alabama",
        "code": "AL"
      },
      {
        "zone_id": "3614",
        "name": "Alaska",
        "code": "AK"
      },
      {
        "zone_id": "3615",
        "name": "American Samoa",
        "code": "AS"
      },
      {
        "zone_id": "3616",
        "name": "Arizona",
        "code": "AZ"
      },
      {
        "zone_id": "3617",
        "name": "Arkansas",
        "code": "AR"
      },
      {
        "zone_id": "3618",
        "name": "Armed Forces Africa",
        "code": "AF"
      },
      {
        "zone_id": "3619",
        "name": "Armed Forces Americas",
        "code": "AA"
      },
      {
        "zone_id": "3620",
        "name": "Armed Forces Canada",
        "code": "AC"
      },
      {
        "zone_id": "3621",
        "name": "Armed Forces Europe",
        "code": "AE"
      },
      {
        "zone_id": "3622",
        "name": "Armed Forces Middle East",
        "code": "AM"
      }
    ]
  }
}

This endpoint retrieves all the zones of a country.

HTTP Request

GET API-URL/countries/COUNTRY-ID/zones

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.
COUNTRY-ID Country MailWizz ID to retrieve zones for

Customers

Customers endpoint

// CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\Customers();
# CREATE THE ENDPOINT
endpoint = Customers.new
from mailwizz.endpoint.customers import Customers

"""
CREATE THE ENDPOINT
"""
endpoint = Customers()

Create a customer

// CREATE CUSTOMER
$response = $endpoint->create([
    'customer' => [
        'first_name' => 'John',
        'last_name'  => 'Doe',
        'email'      => 'john.doe@doe.com',
        'password'   => 'superDuperPassword',
        'timezone'   => 'UTC',
        'birthDate'  => 'Y-m-d'
    ],
    // company is optional, unless required from app settings
    'company'  => [
        'name'     => 'John Doe LLC',
        'country'  => 'United States', // see the countries endpoint for available countries and their zones
        'zone'     => 'New York', // see the countries endpoint for available countries and their zones
        'city'     => 'Brooklyn',
        'zip_code' => 11222,
        'address_1'=> 'Some Address',
        'address_2'=> 'Some Other Address',
    ],
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# CREATE CUSTOMER
response = endpoint.create(data = {
    'customer': {
        'first_name': 'John',
        'last_name': 'Doe',
        'email': 'john.doe@doe.com',
        'password': 'superDuperPassword',
        'timezone': 'UTC',
        'birthDate': '1979-07-30'
    },
    # company is optional, unless required from app settings
    'company': {
        'name': 'John Doe LLC',
        'country': 'United States', # see the countries endpoint for available countries and their zones
        'zone': 'New York', # see the countries endpoint for available countries and their zones
        'city': 'Brooklyn',
        'zip_code': 11222,
        'address_1': 'Some Address',
        'address_2': 'Some Other Address',
    },
})

# DISPLAY RESPONSE
puts response.body
"""
CREATE CUSTOMER
"""
response = endpoint.create({
    'customer': {
        'first_name': 'John',
        'last_name': 'Doe',
        'email': 'john.doe@doe.com',
        'password': 'superDuperPassword',
        'timezone': 'UTC',
        'birthDate': '1979-07-30'
    },
    # company is optional, unless required from app settings
    'company': {
        'name': 'John Doe LLC',
        'country': 'United States',  # see the countries endpoint for available countries and their zones
        'zone': 'New York',  # see the countries endpoint for available countries and their zones
        'city': 'Brooklyn',
        'zip_code': 11222,
        'address_1': 'Some Address',
        'address_2': 'Some Other Address',
    },
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "customer_uid": "wc149l7wdm9be"
}

This endpoint creates a customer

HTTP Request

POST API-URL/customers

POST Parameters

Parameter Type Required Description
customer array yes The array with the customer details.
company array no The array with the company details if required by the MailWizz settings.

Customer block

Parameter Type Required Description
first_name string yes Customer first name
last_name string yes Customer last name
email string yes Customer email
password string yes Customer password
timezone string yes Customer timezone(i.e. UTC)

Company block

Parameter Type Required Description
name string yes Company name
country string yes Company country (See the Countries endpoint for available countries and zones)
zone string yes Company zone
city string yes Company city
zip_code string yes Company zipcode
address_1 string yes Company address
address_2 string yes Company another address

Templates

Templates endpoint

// CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\Templates();
# CREATE THE ENDPOINT
endpoint = Templates.new
from mailwizz.endpoint.templates import Templates

"""
CREATE THE ENDPOINT
"""
endpoint = Templates()

Get all templates

// GET ALL ITEMS
$response = $endpoint->getTemplates($pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# GET ALL TEMPLATES
response = endpoint.get_templates(page = 1, per_page = 10)

# DISPLAY RESPONSE
puts response.body
"""
GET ALL TEMPLATES
"""
response = endpoint.get_templates(page=1, per_page=10)

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "records": [
      {
      "name": "portfolio_html (1)",
      "content": "HTML content...",
      "screenshot": "https:\/\/domain.com\/frontend\/assets\/gallery\/ew055sq9tn97e\/img_ytStill.png"
     }
    ]
  }
}

This endpoint retrieves all the templates.

HTTP Request

GET API-URL/templates

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.

Get one template

// GET ONE ITEM
$response = $endpoint->getTemplate('TEMPLATE-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# GET ONE ITEM
response = endpoint.get_template(template_uid = 'TEMPLATE-UNIQUE-ID')

# DISPLAY RESPONSE
puts response.body
"""
GET ONE ITEM
"""
response = endpoint.get_template(template_uid='TEMPLATE-UNIQUE-ID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "record": {
      "name": "portfolio_html (1)",
      "content": "HTML content...",
      "screenshot": "https:\/\/domain.com\/frontend\/assets\/gallery\/ew055sq9tn97e\/img_ytStill.png"
    }
  }
}

This endpoint retrieves the template with the given TEMPLATE-UNIQUE-ID.

HTTP Request

GET API-URL/templates/TEMPLATE-UNIQUE-ID

Query Parameters

Parameter Required Description
TEMPLATE-UNIQUE-ID yes Template unique id which to retrieve.

Search templates

// Search ALL ITEMS (available from MailWizz 1.4.4)
$response = $endpoint->searchTemplates($pageNumber = 1, $perPage = 10, [
    'name' => 'my template name'
]);

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# SEARCH FOR TEMPLATES
response = endpoint.search_templates(page = 1, per_page = 10, filters = {
    'name': 'example-template'
})

# DISPLAY RESPONSE
puts response.body
"""
SEARCH FOR TEMPLATES
"""
response = endpoint.search_templates(page=1, per_page=10, filters={
    'name': 'example-template'
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "records": [
      {
      "name": "portfolio_html (1)",
      "content": "HTML content...",
      "screenshot": "https:\/\/domain.com\/frontend\/assets\/gallery\/ew055sq9tn97e\/img_ytStill.png"
     }
    ]
  }
}

This endpoint retrieves the templates based on the filter keys values.

HTTP Request

GET API-URL/templates

Query Parameters

Parameter Type Required Description
filters array yes Indexed array having template attributes as keys.(i.e.: name )

Create a template

// CREATE A NEW TEMPLATE
$rand = rand();
$response = $endpoint->create([
    'name'          => 'My API template ' . $rand,
    'content'       => file_get_contents(__DIR__ . '/template-example.html'),
    //'archive'     => file_get_contents(__DIR__ . '/template-example.zip'),
    'inline_css'    => 'no',// yes|no
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# CREATE ONE TEMPLATE
response = endpoint.create(data = {
    'name': 'My API template ',
    # 'content': '<body>Hello</body>',
    # 'content': File.read('template-example.html'),
    # 'archive': File.read('template-example.zip'), - TODO - Request entity too large for zip in all the endpoints
    'inline_css': 'no', # yes|no
})

# DISPLAY RESPONSE
puts response.body
"""
CREATE ONE TEMPLATE
"""
response = endpoint.create(data={
    'name': 'My API template ',
    # 'content': '<body>Hello</body>',
    # 'content': open('template-example.html', 'r').read(),
    'archive': open('template-example.zip', 'rb').read(),
    'inline_css': 'no',  # yes|no
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "template_uid": "jo441taeq281e"
}

This endpoint creates a template.

HTTP Request

POST API-URL/templates/create

POST Parameters

Parameter Type Required Description
data array yes Array with the template details.

Data block - required

Parameter Type Required Description
name string yes Template name
content string yes The template content
archive string no Zip archive name on the disk. This can be used when not using the plain content key
inline_css Yes/No no Allow/disallow inline css

Update a template

// UPDATE A TEMPLATE
$response = $endpoint->update('TEMPLATE-UNIQUE-ID', [
    'name'          => 'My API template - updated' . $rand,
    'content'       => file_get_contents(__DIR__ . '/template-example.html'),
    //'archive'     => file_get_contents(__DIR__ . '/template-example.zip'),
    'inline_css'    => 'no',// yes|no
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# UPDATE ONE TEMPLATE
response = endpoint.update(template_uid = 'TEMPLATE-UNIQUE-ID', data = {
    'name': 'My API template - Updated',
    # 'content': open('template-example.html', 'rb').read(),
    # 'archive': open('template-example.zip', 'rb').read(),
    'inline_css': 'no', # yes|no
})

# DISPLAY RESPONSE
puts response.body
"""
UPDATE ONE TEMPLATE
"""
response = endpoint.update(template_uid='TEMPLATE-UNIQUE-ID', data={
    'name': 'My API template - Updated',
    # 'content': open('template-example.html', 'rb').read(),
    # 'archive': open('template-example.zip', 'rb').read(),
    'inline_css': 'no',  # yes|no
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success"
}

This endpoint updates a template.

HTTP Request

PUT API-URL/templates/update/TEMPLATE-UNIQUE-ID

POST Parameters

Parameter Type Required Description
TEMPLATE-UNIQUE-ID string yes Template unique identifier
data array yes Array with the template details. See the create section for details

Delete a template

// delete template
$response = $endpoint->delete('TEMPLATE-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# DELETE A TEMPLATE
response = endpoint.delete('TEMPLATE-UNIQUE-ID')

# DISPLAY RESPONSE
puts response.body
"""
DELETE A TEMPLATE
"""
response = endpoint.delete('TEMPLATE-UNIQUE-ID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success"
}

This endpoint will delete the template with the given TEMPLATE-UNIQUE-ID.

HTTP Request

DELETE API-URL/templates/TEMPLATE-UNIQUE-ID

Query Parameters

Parameter Required Description
TEMPLATE-UNIQUE-ID yes Template unique id to delete.

Transactional Emails

Transactional emails endpoint

// CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\TransactionalEmails();
# CREATE THE ENDPOINT
endpoint = TransactionalEmails.new
"""
CREATE THE ENDPOINT
"""
endpoint = TransactionalEmails()

Get all transactional emails

// GET ALL ITEMS
$response = $endpoint->getEmails($pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# GET ALL ITEMS
response = endpoint.get_emails(page = 1, per_page = 10)

# DISPLAY RESPONSE
puts response.body
"""
GET ALL ITEMS
"""
response = endpoint.get_emails(page=1, per_page=10)

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "3",
    "total_pages": 1,
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "records": [
      {
        "email_uid": "pc939rqfc16c5",
        "customer_id": "1",
        "to_email": "john@doe.com",
        "to_name": "John Doe",
        "from_email": "jane@doe.com",
        "from_name": "Jane Doe",
        "reply_to_email": "jane@doe.com",
        "reply_to_name": "Jane Doe",
        "subject": "This is the email subject",
        "body": "<strong>Hello world!<\/strong>",
        "plain_text": "HELLO WORLD!",
        "priority": "5",
        "retries": "0",
        "max_retries": "3",
        "send_at": "2021-02-25 11:00:58",
        "fallback_system_servers": "no",
        "status": "sent",
        "date_added": "2021-02-25 11:01:00",
        "last_updated": "2021-02-25 11:02:01"
      },
      {
        "email_uid": "ja646gs7w3d09",
        "customer_id": "1",
        "to_email": "laurennntiu.zorila@gmail.com",
        "to_name": "John Doe",
        "from_email": "jane@doe.com",
        "from_name": "Jane Doe",
        "reply_to_email": "jane@doe.com",
        "reply_to_name": "Jane Doe",
        "subject": "This is the email subject",
        "body": "<strong>Hello world!<\/strong>",
        "plain_text": "HELLO WORLD!",
        "priority": "5",
        "retries": "0",
        "max_retries": "3",
        "send_at": "2021-02-23 08:57:13",
        "fallback_system_servers": "no",
        "status": "sent",
        "date_added": "2021-02-23 08:57:18",
        "last_updated": "2021-02-23 08:58:01"
      },
      {
        "email_uid": "zd716gnx0y1a1",
        "customer_id": "1",
        "to_email": "john@doe.com",
        "to_name": "John Doe",
        "from_email": "jane@doe.com",
        "from_name": "Jane Doe",
        "reply_to_email": "jane@doe.com",
        "reply_to_name": "Jane Doe",
        "subject": "This is the email subject",
        "body": "<strong>Hello world!<\/strong>",
        "plain_text": "HELLO WORLD!",
        "priority": "5",
        "retries": "0",
        "max_retries": "3",
        "send_at": "2021-02-23 08:53:10",
        "fallback_system_servers": "no",
        "status": "sent",
        "date_added": "2021-02-23 08:53:15",
        "last_updated": "2021-02-23 08:54:01"
      }
    ]
  }
}

This endpoint retrieves all the transactional emails.

HTTP Request

GET API-URL/transactional-emails

Query Parameters

Parameter Default Description
pageNumber 1 Current page to retrieve.
perPage 10 Items per page to retrieve.

Get one transactional email

// GET ONE ITEM
$response = $endpoint->getEmail('EMAIL-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# GET ONE ITEM
response = endpoint.get_email(email_uid = 'EMAIL-UNIQUE-ID')

# DISPLAY RESPONSE
puts response.body
"""
GET ONE ITEM
"""
response = endpoint.get_email(email_uid='EMAIL-UNIQUE-ID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "record": {
      "email_uid": "pc939rqfc16c5",
      "customer_id": "1",
      "to_email": "john@doe.com",
      "to_name": "John Doe",
      "from_email": "jane@doe.com",
      "from_name": "Jane Doe",
      "reply_to_email": "jane@doe.com",
      "reply_to_name": "Jane Doe",
      "subject": "This is the email subject",
      "body": "<strong>Hello world!<\/strong>",
      "plain_text": "HELLO WORLD!",
      "priority": "5",
      "retries": "0",
      "max_retries": "3",
      "send_at": "2021-02-25 11:00:58",
      "fallback_system_servers": "no",
      "status": "sent",
      "date_added": "2021-02-25 11:01:00",
      "last_updated": "2021-02-25 11:02:01"
    }
  }
}

This endpoint retrieves the transactional email with the given EMAIL-UNIQUE-ID.

HTTP Request

GET API-URL/transactional-emails/EMAIL-UNIQUE-ID

Query Parameters

Parameter Required Description
EMAIL-UNIQUE-ID yes Email unique id which to retrieve.

Create a transactional email

// CREATE A NEW EMAIL
$response = $endpoint->create([
    'to_name'           => 'John Doe', // required
    'to_email'          => 'john@doe.com', // required
    'from_name'         => 'Jane Doe', // required
    'from_email'        => 'jane@doe.com', // optional
    'reply_to_name'     => 'Jane Doe', // optional
    'reply_to_email'    => 'jane@doe.com', // optional
    'subject'           => 'This is the email subject', // required
    'body'              => '<strong>Hello world!</strong>', // required
    'plain_text'        => 'Hello world!', // optional, will be autogenerated if missing
    'send_at'           => date('Y-m-d H:i:s'),  // required, UTC date time in same format!
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# CREATE A NEW EMAIL
response = endpoint.create(data = {
    'to_name': 'John Doe', # required
    'to_email': 'john@doe.com', # required
    'from_name': 'Jane Doe', # required
    'from_email': 'jane@doe.com', # optional
    'reply_to_name': 'Jane Doe', # optional
    'reply_to_email': 'jane@doe.com', # optional
    'subject': 'This is the email subject', # required
    'body': 'Hello world!', # required
    'plain_text': 'Hello world!', # optional, will be autogenerated if missing
    'send_at': Time.now.strftime('%Y-%m-%d %H:%M:%S'), # required, UTC date time in same format!
})

# DISPLAY RESPONSE
puts response.body
"""
CREATE A NEW EMAIL
"""
response = endpoint.create(data={
    'to_name': 'John Doe',  # required
    'to_email': 'john@doe.com',  # required
    'from_name': 'Jane Doe',  # required
    'from_email': 'jane@doe.com',  # optional
    'reply_to_name': 'Jane Doe',  # optional
    'reply_to_email': 'jane@doe.com',  # optional
    'subject': 'This is the email subject',  # required
    'body': 'Hello world!',  # required
    'plain_text': 'Hello world!',  # optional, will be autogenerated if missing
    'send_at': (datetime.now()).strftime('%Y-%m-%d %H:%M:%S'),  # required, UTC date time in same format!
})

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "email_uid": "vy348j4jqn1d1"
}

This endpoint creates a transactional email.

HTTP Request

POST API-URL/transactional-emails/create

POST Parameters

Parameter Type Required Description
data array yes Array with the email details.

Data block - required

Parameter Type Required Description
to_name string yes Recipient name
to_email string yes Recipient email
from_name string yes Sender name
subject string yes Email subject
body string yes Email body
send_at datetime yes UTC datetime (Y-m-d H:i:s format)
plain_text string no Email plain text. Auto generated if missing
from_email string no Sender email
reply_to_name string no Reply to name
reply_to_email string no Reply to email

Delete a transactional email

// delete email
$response = $endpoint->delete('EMAIL-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# DELETE EMAIL
response = endpoint.delete('EMAIL-UNIQUE-ID')

# DISPLAY RESPONSE
puts response.body
"""
DELETE EMAIL
"""
response = endpoint.delete('EMAIL-UNIQUE-ID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success"
}

This endpoint will delete the transactional email with the given TEMPLATE-UNIQUE-ID.

HTTP Request

DELETE API-URL/transactional-emails/EMAIL-UNIQUE-ID

Query Parameters

Parameter Required Description
EMAIL-UNIQUE-ID yes Email unique id to delete.