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:
Compatible implementations:
A small rest app that acts as a proxy between MailWizz and any other software.
HTTP Methods used
We follow the REST standards for MailWizz's API interaction, which means that we use following HTTP methods during communication:
POST - when items are created
GET - when items are listed
PUT - when items are updated
DELETE - when items are deleted
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.
Authorization
Authentication is done by sending your API key in a custom header called X-Api-Key.
Data Format
When sending data to the API endpoints, it is sent in form-data format and returned as json.
Getting started
First you need to install the SDK. See each supported language for its way of installing
PHP
Get started by installing 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-URLPUBLIC-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 |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 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_email": "from@domain.com",
"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
URL Segments
| Segment | 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
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/LIST-UNIQUE-ID
URL Segment
| Segment | Type | Required | Description |
|---|---|---|---|
| LIST-UNIQUE-ID | string | yes | List unique identifier |
POST Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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
URL Segments
| Segment | 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
URL Segments
| Segment | 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": [
{
"field_id": "12",
"tag": "EMAIL",
"label": "Email",
"required": "yes",
"help_text": null,
"visibility": "visible",
"sort_order": "0",
"type": {
"name": "Text",
"identifier": "text",
"description": "Text"
}
},
{
"field_id": "13",
"tag": "FNAME",
"label": "First name",
"required": "no",
"help_text": null,
"visibility": "visible",
"sort_order": "1",
"type": {
"name": "Text",
"identifier": "text",
"description": "Text"
}
},
{
"field_id": "14",
"tag": "LNAME",
"label": "Last name",
"required": "no",
"help_text": null,
"visibility": "visible",
"sort_order": "2",
"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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | The list unique identifier |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
Get one list field
// GET ONE ITEM
$response = $endpoint->getField('LIST-UNIQUE-ID', 'FIELD-ID');
// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
The above command returns an object structured like this JSON:
{
"status": "success",
"data": {
"record": {
"field_id": "13",
"tag": "FNAME",
"label": "First name",
"required": "no",
"help_text": null,
"visibility": "visible",
"sort_order": "1",
"type": {
"name": "Text",
"identifier": "text",
"description": "Text"
}
}
}
}
This endpoint retrieves the list field with the given FIELD-ID for the given LIST-UNIQUE-ID.
HTTP Request
GET API-URL/lists/LIST-UNIQUE-ID/fields/FIELD-ID
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique id to retrieve field for. |
| FIELD-ID | yes | List field id to retrieve |
Create a list field
// create a new list field
$response = $endpoint->create('LIST-UNIQUE-ID', [
'type' => 'dropdown',
'label' => 'Text Label',
'tag' => 'DROPDOWN',
'required' => 'no',
'visibility' => 'visible',
'sort_order' => 0,
'help_text' => 'Help',
'default_value' => '',
'description' => 'Description',
'options' => [
[
'name' => 'Option1',
'value' => 'Value1'
],
[
'name' => 'Option2',
'value' => 'Value2'
],
]
]);
// and get the response
echo '<pre>';
print_r($response->body);
echo '</pre>';
The above command returns an object structured like this JSON:
{
"status": "success",
"data": {
"record": {
"field_id": "138",
"label": "Text Label",
"tag": "DROPDOWN",
"help_text": "Help",
"description": "Description",
"default_value": "",
"required": "no",
"visibility": "visible",
"sort_order": "0",
"type": {
"name": "Dropdown",
"identifier": "dropdown",
"description": "Dropdown"
},
"list": {
"list_uid": "wo16508sn983b",
"display_name": "My list"
},
"options": {
"Value1": "Option1",
"Value2": "Option2"
}
}
}
}
This endpoint creates a list field.
The data param can contain following indexed arrays:
-> options - optional
HTTP Request
POST API-URL/lists/LIST_UID/fields
POST Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| data | array | yes | Array with the list field details. The following indexed arrays are accepted: options |
General block - required
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | yes | The field type check the field types endpoint for possible values |
| label | string | yes | The label of the field |
| tag | string | yes | The unique tag |
| required | string | yes | Whether the field is required or not (yes/no) |
| visibility | string | yes | Whether the field is visible or not (hidden/visible) |
| default_value | string | no | The field default value |
| sort_order | int | no | The field showing order in the form |
| help_text | string | no | The field help text |
| description | string | no | The field description |
| min_length | int | no | Applies for the text fields. Min length |
| max_length | int | no | Applies for the text fields. Max length maximum allowed value is 255 |
| content_rule | string | no | Applies for the text fields. Allows rules as alpha_ci/alphanum_ci/alphanumext_ci |
| content_regex | string | no | Applies for the text fields. Regex to validate the field value |
| allowed_scheme | string | no | Applies for the url field |
| whitelist_domains | string | no | Applies for the url field |
| blacklist_domains | string | no | Applies for the url field |
| max_stars | int | no | Applies for the rating field |
| default_country | string | no | Applies for the phone field. Country codes values like us/ro/bg |
Options block - optional
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | yes | The option name to show in the dropdown |
| value | string | yes | The option value for the dropdown |
Update a list field
// update list field
$response = $endpoint->update('LIST-UNIQUE-ID', 'FIELD-ID', [
'label' => 'Text Label',
'tag' => 'DROPDOWN',
'required' => 'no',
'visibility' => 'visible',
'sort_order' => 0,
'help_text' => 'Help',
'default_value' => '',
'description' => 'Description',
'options' => [
[
'name' => 'Option1',
'value' => 'Value1'
],
[
'name' => 'Option2',
'value' => 'Value2'
],
]
]);
// and get the response
echo '<pre>';
print_r($response->body);
echo '</pre>';
The above command returns an object structured like this JSON:
{
"status": "success",
"data": {
"record": {
"field_id": "138",
"label": "Text Label",
"tag": "DROPDOWN",
"help_text": "Help",
"description": "Description",
"default_value": "",
"required": "no",
"visibility": "visible",
"sort_order": "0",
"type": {
"name": "Dropdown",
"identifier": "dropdown",
"description": "Dropdown"
},
"list": {
"list_uid": "wo16508sn983b",
"display_name": "My list"
},
"options": {
"Value1": "Option1",
"Value2": "Option2"
}
}
}
}
This endpoint updates a list field.
HTTP Request
PUT API-URL/lists/LIST-UNIQUE-ID/fields/FIELD-ID
URL Segment
| Segment | Type | Required | Description |
|---|---|---|---|
| LIST-UNIQUE-ID | string | yes | List unique identifier |
| FIELD-ID | string | yes | List field id |
PUT Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| data | array | yes | Array with the list field details. The following indexed arrays are accepted: options See the create section for details |
General block - required
| Parameter | Type | Required | Description |
|---|---|---|---|
| label | string | yes | The label of the field |
| tag | string | yes | The unique tag |
| required | string | yes | Whether the field is required or not (yes/no) |
| visibility | string | yes | Whether the field is visible or not (hidden/visible) |
| default_value | string | no | The field default value |
| sort_order | int | no | The field showing order in the form |
| help_text | string | no | The field help text |
| description | string | no | The field description min_length |
| max_length | int | no | Applies for the text fields. Max length |
| content_rule | string | no | Applies for the text fields. Allows rules as alpha_ci/alphanum_ci/alphanumext_ci |
| content_regex | string | no | Applies for the text fields. Regex to validate the field value |
| allowed_scheme | string | no | Applies for the url field |
| whitelist_domains | string | no | Applies for the url field |
| blacklist_domains | string | no | Applies for the url field |
| max_stars | int | no | Applies for the rating field |
| default_country | string | no | Applies for the country field. Country codes values like us/ro/bg |
Options block - optional
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | yes | The option name to show in the dropdown |
| value | string | yes | The option value for the dropdown |
Delete a list field
// Delete FIELD
$response = $endpoint->delete('LIST-UNIQUE-ID', 'FIELD-ID');
// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
The above command returns an object structured like this JSON:
{
"status":"success"
}
This endpoint will delete the list field with the given FIELD-ID for the LIST-UNIQUE-ID.
HTTP Request
DELETE API-URL/lists/LIST-UNIQUE-ID/fields/LIST-ID
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique id to delete. |
| FIELD-ID | yes | List field id to delete |
Get all list field types
// GET ALL ITEMS
$response = $endpoint->getListFieldTypes();
// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
The above command returns an object structured like this JSON:
{
"status": "success",
"data": {
"count": "20",
"records": [
{
"name": "Text",
"identifier": "text",
"description": "Text"
},
{
"name": "Dropdown",
"identifier": "dropdown",
"description": "Dropdown"
},
{
"name": "Multiselect",
"identifier": "multiselect",
"description": "Multiselect"
},
{
"name": "Date",
"identifier": "date",
"description": "Date"
},
{
"name": "Datetime",
"identifier": "datetime",
"description": "Datetime"
},
{
"name": "Textarea",
"identifier": "textarea",
"description": "Textarea"
},
{
"name": "Country",
"identifier": "country",
"description": "Country"
},
{
"name": "State",
"identifier": "state",
"description": "State"
},
{
"name": "Checkbox List",
"identifier": "checkboxlist",
"description": "Checkbox List"
},
{
"name": "Radio List",
"identifier": "radiolist",
"description": "Radio List"
},
{
"name": "Geo Country",
"identifier": "geocountry",
"description": "Geo Country"
},
{
"name": "Geo State",
"identifier": "geostate",
"description": "Geo State"
},
{
"name": "Geo City",
"identifier": "geocity",
"description": "Geo City"
},
{
"name": "Checkbox",
"identifier": "checkbox",
"description": "Checkbox"
},
{
"name": "Consent Checkbox",
"identifier": "consentcheckbox",
"description": "Consent Checkbox"
},
{
"name": "Years Range",
"identifier": "yearsrange",
"description": "Years Range"
},
{
"name": "Phone Number",
"identifier": "phonenumber",
"description": "Phone Number"
},
{
"name": "Email",
"identifier": "email",
"description": "Email"
},
{
"name": "Url",
"identifier": "url",
"description": "Url"
},
{
"name": "Rating",
"identifier": "rating",
"description": "Rating"
}
]
}
}
This endpoint retrieves all the list field types.
HTTP Request
GET API-URL/lists/fields/types
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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | The list unique identifier |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
Get one list segment
// GET ONE ITEM
$response = $endpoint->getSegment('SEGMENT-UNIQUE-ID');
// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
The above command returns an object structured like this JSON:
{
"status": "success",
"data": {
"record": {
"segment_uid": "sx795qzttl9bb",
"segment_id": "11",
"name": "my segment with cond updated",
"operator_match": "any",
"date_added": "10/23/23, 2:36 PM",
"subscribers_count": 0,
"conditions": [
{
"field_id": "96",
"operator_id": "3",
"value": "keyword"
}
],
"campaign_conditions": []
}
}
}
This endpoint retrieves the list segment with the given SEGMENT-UNIQUE-ID.
HTTP Request
GET API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique id to retrieve segment for. |
| SEGMENT-UNIQUE-ID | yes | Segment unique id to retrieve |
Get all subscribers
// GET ALL SUBSCRIBERS OF A LIST SEGMENT
$response = $endpoint->getSubscribers('LIST-UNIQUE-ID', 'SEGMENT-UNIQUE-ID', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# GET ALL SUBSCRIBERS OF A LIST SEGMENT
response = endpoint.get_subscribers(list_uid = 'LIST-UNIQUE-ID', segment_uid = 'SEGMENT-UNIQUE-ID', page = 1, per_page = 10)
# DISPLAY RESPONSE
puts response.body
"""
GET ALL SUBSCRIBERS OF A LIST SEGMENT
"""
response = endpoint.get_subscribers(list_uid='LIST-UNIQUE-ID', segment_uid='SEGMENT-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 segment.
HTTP Request
GET API-URL/lists/LIST-UNIQUE-ID/segments/SEGMEMT-UNIQUE-ID/subscribers
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | The list unique identifier for which we retrieve the subscribers |
| SEGMENT-UNIQUE-ID | yes | Segment unique identifier |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
Create a list segment
// create a new list segment
$response = $endpoint->create('LIST-UNIQUE-ID', [
// required
'name' => 'My list segment created from the API', // required
'operator_match' => 'any', // required (any/all)
// optional
'conditions' => [
[
'field_id' => '96', // required .
'operator_id' => '3', // required . See the API-URL/lists/segments/condition-operators endpoint
'value' => 'domain.com', // required
],
[
'field_id' => '95', // required .
'operator_id' => '4', // required . See the API-URL/lists/segments/condition-operators endpoint
'value' => 'keyword', // required
]
],
'campaign_conditions' => [
[
'action' => 'click', // required (click/open)
'campaign_id' => '100', // required
'time_comparison_operator' => 'lte', // required (lte/lt/gte/gt/eq)
'time_value' => '3', // required
'time_unit' => 'day' // required (day/month/year)
],
[
'action' => 'open', // required (click/open)
'campaign_id' => '99', // required
'time_comparison_operator' => 'gte', // required (lte/lt/gte/gt/eq)
'time_value' => '3', // required
'time_unit' => 'month' // required (day/month/year)
]
],
]);
// and get the response
echo '<pre>';
print_r($response->body);
echo '</pre>';
The above command returns an object structured like this JSON:
{
"status": "success",
"data": {
"record": {
"segment_uid": "sx795qzttl9bb",
"segment_id": "11",
"name": "my segment with cond updated",
"operator_match": "any",
"date_added": "10/23/23, 2:36 PM",
"subscribers_count": 0,
"conditions": [
{
"field_id": "96",
"operator_id": "3",
"value": "keyword"
}
],
"campaign_conditions": []
}
}
}
This endpoint creates a list segment.
The data param can contain following indexed arrays:
-> conditions - optional
-> campaign_conditions - optional
HTTP Request
POST API-URL/lists/LIST_UID/segments
POST Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| data | array | yes | Array with the list segment details. The following indexed arrays are accepted: conditions, campaign_conditions, |
General block - required
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | yes | List segment name |
| operator_match | string | yes | Operator to match all the conditions: any/all |
Conditions block - optional
| Parameter | Type | Required | Description |
|---|---|---|---|
| field_id | string | yes | List custom field id. Can be retrieved using the list fields endpoint |
| operator_id | string | yes | Operator id. See the API-URL/lists/segments/operators endpoint |
| value | string | yes | Value to compare with |
Campaign conditions block - optional
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | yes | Campaign action: click/open |
| campaign_id | integer | yes | Campaign id. |
| time_comparison_operator | string | yes | Time comparison operator: (lte/lt/gte/gt/eq) |
| time_value | integer | yes | Time value |
| time_unit | string | yes | Time unit day/month/year |
Update a list segment
// update list segment
// Only the conditions present here will be kept. All other existing conditions will be removed
$response = $endpoint->update('LIST-UNIQUE-ID', 'SEGMENT-UNIQUE-ID', [
// required
'name' => 'My list segment created from the API updated', // required
'operator_match' => 'any', // required (any/all)
// optional
'conditions' => [
[
'field_id' => '96', // required .
'operator_id' => '3', // required . See the API-URL/lists/segments/condition-operators endpoint
'value' => 'domain.com', // required
],
[
'field_id' => '95', // required .
'operator_id' => '4', // required . See the API-URL/lists/segments/condition-operators endpoint
'value' => 'keyword', // required
]
],
'campaign_conditions' => [
[
'action' => 'click', // required (click/open)
'campaign_id' => '100', // required
'time_comparison_operator' => 'lte', // required (lte/lt/gte/gt/eq)
'time_value' => '3', // required
'time_unit' => 'day' // required (day/month/year)
],
[
'action' => 'open', // required (click/open)
'campaign_id' => '99', // required
'time_comparison_operator' => 'gte', // required (lte/lt/gte/gt/eq)
'time_value' => '3', // required
'time_unit' => 'month' // required (day/month/year)
]
],
]);
// and get the response
echo '<pre>';
print_r($response->body);
echo '</pre>';
The above command returns an object structured like this JSON:
{
"status": "success",
"data": {
"record": {
"segment_uid": "sx795qzttl9bb",
"segment_id": "11",
"name": "my segment with cond updated",
"operator_match": "any",
"date_added": "10/23/23, 2:36 PM",
"subscribers_count": 0,
"conditions": [
{
"field_id": "96",
"operator_id": "3",
"value": "keyword"
}
],
"campaign_conditions": []
}
}
}
This endpoint updates a list segment.
HTTP Request
PUT API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID
URL Segment
| Segment | Type | Required | Description |
|---|---|---|---|
| LIST-UNIQUE-ID | string | yes | List unique identifier |
| SEGMENT-UNIQUE-ID | string | yes | List segment unique identifier |
PUT Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| data | array | yes | Array with the list segment details. The following indexed arrays are accepted: conditions, campaign_conditions. See the create section for details |
General block - required
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | yes | List segment name |
| operator_match | string | yes | Operator to match all the conditions: any/all |
Conditions block - optional
| Parameter | Type | Required | Description |
|---|---|---|---|
| field_id | string | yes | List custom field id. Can be retrieved using the list fields endpoint |
| operator_id | string | yes | Operator id. See the API-URL/lists/segments/operators endpoint |
| value | string | yes | Value to compare with |
Campaign conditions block - optional
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | yes | Campaign action: click/open |
| campaign_id | integer | yes | Campaign id. |
| time_comparison_operator | string | yes | Time comparison operator: (lte/lt/gte/gt/eq) |
| time_value | integer | yes | Time value |
| time_unit | string | yes | Time unit day/month/year |
Delete a list segment
// Delete SEGMENT
$response = $endpoint->delete('LIST-UNIQUE-ID', 'SEGMENT-UNIQUE-ID');
// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
The above command returns an object structured like this JSON:
{
"status":"success"
}
This endpoint will delete the list segment with the given SEGMENT-UNIQUE-ID for the LIST-UNIQUE-ID.
HTTP Request
DELETE API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique id to delete. |
| SEGMENT-UNIQUE-ID | yes | List segment unique id to delete |
Get all list segment condition operators
// GET ALL ITEMS
$response = $endpoint->getConditionOperators();
// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
The above command returns an object structured like this JSON:
{
"status": "success",
"data": {
"count": "10",
"records": [
{
"operator_id": "1",
"name": "is",
"slug": "is"
},
{
"operator_id": "2",
"name": "is not",
"slug": "is-not"
},
{
"operator_id": "3",
"name": "contains",
"slug": "contains"
},
{
"operator_id": "4",
"name": "not contains",
"slug": "not-contains"
},
{
"operator_id": "5",
"name": "starts with",
"slug": "starts"
},
{
"operator_id": "6",
"name": "ends with",
"slug": "ends"
},
{
"operator_id": "7",
"name": "is greater than",
"slug": "greater"
},
{
"operator_id": "8",
"name": "is less than",
"slug": "less"
},
{
"operator_id": "9",
"name": "not starts with",
"slug": "not-starts"
},
{
"operator_id": "10",
"name": "not ends with",
"slug": "not-ends"
}
]
}
}
This endpoint retrieves all the list segment condition operators.
HTTP Request
GET API-URL/lists/segments/condition-operators
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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | The list unique identifier for which we retrieve the subscribers |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
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
URL Segments
| Segment | 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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique id to which the subscriber to retrieve belongs. |
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| 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 |
|---|---|---|
| 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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List to search in. |
Query Parameters
| Parameter | Required/Default | Description |
|---|---|---|
| array | yes | Array of custom fields {'CUSTOM_FIELD' => 'VALUE'} |
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
Search by status
// SEARCH BY STATUS
$response = $endpoint->searchByStatus('LIST-UNIQUE-ID', 'confirmed', $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": {
"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",
"status": "confirmed",
"ip_address": "",
"date_added": "2021-02-20 17:26:15"
},
{
"subscriber_uid": "kw647a5n8l516",
"EMAIL": "mstephenson5@trellian.com",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "confirmed",
"ip_address": "",
"date_added": "2021-02-20 17:26:15"
},
{
"subscriber_uid": "vo155s4b0d0ad",
"EMAIL": "ldefew4@dailymail.co.uk",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "confirmed",
"ip_address": "",
"date_added": "2021-02-20 17:26:14"
}
]
}
}
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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | The list unique identifier for which we retrieve the subscribers |
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
| status | yes | Subscribers status to retrieve. |
Get blacklisted subscribers
// Get only the blacklisted subscribers
$response = $endpoint->getBlacklistedSubscribers('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": {
"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",
"status": "blacklisted",
"ip_address": "",
"date_added": "2021-02-20 17:26:15"
},
{
"subscriber_uid": "kw647a5n8l516",
"EMAIL": "mstephenson5@trellian.com",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "blacklisted",
"ip_address": "",
"date_added": "2021-02-20 17:26:15"
},
{
"subscriber_uid": "vo155s4b0d0ad",
"EMAIL": "ldefew4@dailymail.co.uk",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "blacklisted",
"ip_address": "",
"date_added": "2021-02-20 17:26:14"
}
]
}
}
This endpoint returns all the subscribers with the status blacklisted within the list having the LIST-UNIQUE-ID.
HTTP Request
GET API-URL/lists/LIST-UNIQUE-ID/subscribers
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | The list unique identifier for which we retrieve the subscribers |
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
| status | blacklisted | The blacklisted status value. |
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",
"status": "confirmed",
"ip_address": "",
"date_added": "2021-02-20 17:26:15"
},
{
"subscriber_uid": "kw647a5n8l516",
"EMAIL": "mstephenson5@trellian.com",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "confirmed",
"ip_address": "",
"date_added": "2021-02-20 17:26:15"
},
{
"subscriber_uid": "vo155s4b0d0ad",
"EMAIL": "ldefew4@dailymail.co.uk",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "confirmed",
"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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | The list unique identifier for which we retrieve the subscribers |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
| status | confirmed | The confirmed status value |
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",
"status": "unconfirmed",
"ip_address": "",
"date_added": "2021-02-20 17:26:15"
},
{
"subscriber_uid": "kw647a5n8l516",
"EMAIL": "mstephenson5@trellian.com",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "unconfirmed",
"ip_address": "",
"date_added": "2021-02-20 17:26:15"
},
{
"subscriber_uid": "vo155s4b0d0ad",
"EMAIL": "ldefew4@dailymail.co.uk",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "unconfirmed",
"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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | The list unique identifier for which we retrieve the subscribers |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
| status | unconfirmed | The unconfirmed status value |
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",
"status": "unsubscribed",
"ip_address": "",
"date_added": "2021-02-20 17:26:15"
},
{
"subscriber_uid": "kw647a5n8l516",
"EMAIL": "mstephenson5@trellian.com",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "unsubscribed",
"ip_address": "",
"date_added": "2021-02-20 17:26:15"
},
{
"subscriber_uid": "vo155s4b0d0ad",
"EMAIL": "ldefew4@dailymail.co.uk",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "unsubscribed",
"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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | The list unique identifier for which we retrieve the subscribers |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
| status | unsubscribed | The unsubscribe status value |
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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique identifier. |
POST Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique identifier. |
POST Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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/SUBSCRIBER-UNIQUE-ID
URL Segments
| Parameter | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique identifier |
| SUBSCRIBER-UNIQUE-ID | yes | Subscriber unique identifier |
PUT Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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
PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique identifier |
| SUBSCRIBER-UNIQUE-ID | yes | Found subscriber unique identifier |
GET/PUT Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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
PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID
POST API-URL/lists/LIST-UNIQUE-ID/subscribers
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique identifier |
| SUBSCRIBER-UNIQUE-ID | yes | Found subscriber unique identifier |
GET/PUT/POST Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| data | array | yes | Array with the custom fields {name => value} to be updated. |
| string | yes | Email to be searched |
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
URL Segments
| Segment | 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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique id to which the subscriber belongs. |
| SUBSCRIBER-UNIQUE-ID | yes | Subscriber unique id to unsubscribe. |
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| 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
PUT Parameters
| Parameter | Required | Description |
|---|---|---|
| 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
URL Segments
| Segment | 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
URL Segments
| Segment | Required | Description |
|---|---|---|
| LIST-UNIQUE-ID | yes | List unique id to which the subscriber belongs. |
| SUBSCRIBER-UNIQUE-ID | yes | Subscriber unique id to delete. |
GET Parameters
| Parameter | Required | Description |
|---|---|---|
| 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",
"campaign_id": "12",
"name": "My API Campaign UPDATED #3",
"status": "sent",
"group": []
},
{
"campaign_uid": "gp5420ve90f3e",
"campaign_id": "13",
"name": "My API Campaign UPDATED #2",
"status": "sent",
"group": []
},
{
"campaign_uid": "hv4163y076d84",
"campaign_id": "14",
"name": "My API Campaign UPDATED #1",
"status": "sent",
"group": []
},
{
"campaign_uid": "xk906nd8fn506",
"campaign_id": "15",
"name": "My API Campaign UPDATED",
"status": "sent",
"group": []
},
{
"campaign_uid": "eh477yfos0258",
"campaign_id": "16",
"name": "API campaing #1",
"status": "draft",
"group": []
},
{
"campaign_uid": "db516xtc45237",
"campaign_id": "17",
"name": "API campaing #2",
"status": "draft",
"group": []
},
{
"campaign_uid": "ld526wjke1ff4",
"campaign_id": "18",
"name": "API campaing #1",
"status": "draft",
"group": []
},
{
"campaign_uid": "bx831rctawf92",
"campaign_id": "19",
"name": "API campaing",
"status": "paused",
"group": []
},
{
"campaign_uid": "tk459h475l8ef",
"campaign_id": "20",
"name": "Test #1",
"status": "sent",
"group": []
},
{
"campaign_uid": "go896lnslz8ae",
"campaign_id": "21",
"name": "Test",
"status": "sent",
"group": []
}
]
}
}
]
This endpoint retrieves all the campaigns.
HTTP Request
GET API-URL/campaigns
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
| list_uid | You can get only the campaigns for the list with the specified unique id |
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",
"campaign_id": "12",
"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/CAMPAIGN-UNIQUE-ID
URL Segments
| Segment | 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 |
|---|---|---|---|
| campaign | array | yes | Array with the email details. |
Campaign block
| 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
URL Segments
| Segment | Required | Description |
|---|---|---|
| CAMPAIGN-UNIQUE-ID | yes | Campaign unique id to update. |
POST Parameters
Same as for the create campaign call.
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
URL Segments
| Segment | 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
URL Segments
| Segment | 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
URL Segments
| Segment | 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
URL Segments
| Segment | 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
URL Segments
| Segment | 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
URL Segments
| Segment | 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
URL Segments
| Segment | 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
URL Segments
| Segment | Required | Description |
|---|---|---|
| CAMPAIGN-UID | Yes | Campaign unique identifier. |
| SUBSCRIBER-UNIQUE-ID | Yes | Subscriber unique identifier. |
POST Parameters
| Parameter | Required | Description |
|---|---|---|
| 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('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/CAMPAIGN-UNIQUE-ID/bounces
URL Segments
| Segment | Required | Description |
|---|---|---|
| CAMPAIGN-UNIQUE-ID | yes | Campaign unique id to retrieve the bounce. |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 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/CAMPAIGN-UNIQUE-ID/bounces
URL Segments
| Segment | Required | Description |
|---|---|---|
| CAMPAIGN-UNIQUE-ID | yes | Campaign unique id to create the bounce. |
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 |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 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
URL Segments
| Segment | Required | Description |
|---|---|---|
| COUNTRY-ID | Yes | Country MailWizz ID to retrieve zones for. |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 10 | Items per page to retrieve. |
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 |
| string | yes | Customer email | |
| password | string | yes | Customer password |
| timezone | string | yes | Customer timezone(i.e. UTC) |
| birthDate | string | yes | Customer birth date (YYYY-MM-DD) |
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": [
{
"template_uid": "xxxxxxxxx",
"name": "portfolio_html (1)",
"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 |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 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
URL Segments
| Segment | 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/Default | Description |
|---|---|---|---|
| page | int | 1 | Current page to retrieve. |
| per_page | int | 10 | Items per page to retrieve. |
| 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
POST Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| template | 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/TEMPLATE-UNIQUE-ID
URL Segments
| Segment | Required | Description |
|---|---|---|
| TEMPLATE-UNIQUE-ID | yes | Template unique identifier |
PUT Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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
URL Segments
| Segment | 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",
"attachments": []
},
{
"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",
"attachments": []
},
{
"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",
"attachments": []
}
]
}
}
This endpoint retrieves all the transactional emails.
HTTP Request
GET API-URL/transactional-emails
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Current page to retrieve. |
| per_page | 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",
"attachments": [
{
"type": "application/pdf",
"name": "filename",
"data": "Email attachment content blob"
}
]
}
}
}
This endpoint retrieves the transactional email with the given EMAIL-UNIQUE-ID.
HTTP Request
GET API-URL/transactional-emails/EMAIL-UNIQUE-ID
URL Segment
| Segment | 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!,
'attachments' => [
[
'type' => 'image/png',
'name' => basename(__DIR__ . '/PATH_TO_YOUR_FILE/file.png'),
'data' => base64_encode((string)file_get_contents(__DIR__ . '/PATH_TO_YOUR_FILE/file.png')),
],
[
'type' => 'image/jpeg',
'name' => basename(__DIR__ . '/PATH_TO_YOUR_FILE/file.jpg'),
'data' => base64_encode((string)file_get_contents(__DIR__ . '/PATH_TO_YOUR_FILE/file.jpg')),
],
[
'type' => 'application/pdf',
'name' => basename(__DIR__ . '/PATH_TO_YOUR_FILE/file.pdf'),
'data' => base64_encode((string)file_get_contents(__DIR__ . '/PATH_TO_YOUR_FILE/file.pdf')),
],
]
]);
// 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
POST Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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 |
| attachments | array | no | Array of attachments in the form ['type', 'name', 'data'] |
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 EMAIL-UNIQUE-ID.
HTTP Request
DELETE API-URL/transactional-emails/EMAIL-UNIQUE-ID
URL Segments
| Segment | Required | Description |
|---|---|---|
| EMAIL-UNIQUE-ID | yes | Email unique id to delete. |