NAV

Introduction

Welcome to the Spotzee Marketing App’s API documentation site. Join us in our journey to become the best omnichannel marketing platform driven by intelligence and advanced automation. You can use our powerful API to integrate into 3rd party applications (Eg. Zapier) or custom apps. The API documentation provides you with the information you need to get started.

We are currently working on developing different language-based SDKs to speed up development. Still, in the meantime, we have provided you with code examples in some popular languages like PHP, Ruby and Python. We plan on updating this document with examples of other popular languages, such as Go, Node.js, and .NET in the near future.

HTTP Methods

We follow the REST API standards for all our API interactions. Here are the supported methods of communication.

Method What it does
GET Used to request data from a specified resource
POST Used to send data to an endpoint to create/update a resource
PUT Used to send data to an endpoint to create/update a resource.
DELETE Used to delete the specified resource.

Before you get started, ensure that your server supports all these methods. The most common error you will experience when these methods are not supported is the HTTP Forbidden error with the code 403. It usually means the server you are making these API calls from does not support PUT/DELETE operations. You must contact your server administrator or change configurations to execute our APIs without issues.

Authorisation

You can authenticate by sending your API key in a custom header called X-SPZ-PUBLIC-KEY. Without this, you cannot make any of the API calls.

Data format

You can use the form, x-www-form-URL-encoded, or JSON formats when sending data to our API endpoints. All of them are perfectly acceptable. The return format is, by default JSON.

Available SDKs

We have developed several software development kits (SDK) available based on your preferred programming language. However, if there is a language for which you do not see an SDK, don’t hesitate to contact our team, and we can look into creating one for you.

PHP

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

composer require spotzee-marketing/spotzee-php

You can then follow the instructions from the examples/setup.php file.

Python

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

pip install spotzee-python

You can then follow the instructions from the examples/setup_api.py file.

Ruby

You can download the latest version of the code via the GitHub repository. Before you execute the command below, ensure you have Ruby installed on your computer/server.

git clone https://github.com/spotzee-marketing/spotzee-ruby.git

You would need excon gem for SDK to work correctly. You can install this gem by using the following command: sudo gem install excon. You can then follow the instructions from the examples/setup_api.rb file.

Configuration

Please make sure to replace API-KEY with a valid API key.

https://cp.spotzee.marketing/api/
//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 your account -> API keys) :
$config = new \SpotzeeApi\Config([
    'apiUrl'    => 'https://cp.spotzee.marketing/api/',
    'apiKey'    => 'API-KEY',

    // components
    'components' => [
        'cache' => [
            'class'     => \SpotzeeApi\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
\SpotzeeApi\Base::setConfig($config);

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

include Spotzee
include Endpoint

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

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

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

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

See the language tab on the right for instructions on configuration.

API Endpoint

Use this URL to connect to any endpoints in this documentation:

https://cp.spotzee.marketing/api/

Components

When you make GET requests, our API returns proper etags. We use this to cache the request to decrease the load on our servers and improve performance on the client side. You must use the cache components to store the responses (via file cache). For more information on this, please see SpotzeeApi\Cache for a list of available cache components and their usage.

Status

Get the status rollup for the whole Spotzee services. This endpoint /status includes an indicator - one of none, minor, major, or critical, as well as a human description of the blended component status. Examples of the blended status include “All Systems Operational”, “Partial System Outage”, and “Major Service Outage”. Full API url would be https://cp.spotzee.marketing/api/status.

Lists

Lists endpoint

Not applicable
/ CREATE THE ENDPOINT
$endpoint = new SpotzeeApi\Endpoint\Lists();
# CREATE THE ENDPOINT
endpoint = Lists.new
from spotzee.endpoint.lists import Lists

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

Get all lists

curl --location 'https://cp.spotzee.marketing/api/lists?pageNumber=1&perPage=10' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/lists

Query Parameters

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

Get one list

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID

URL Segments

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

Create a list

curl --location 'https://cp.spotzee.marketing/api/lists' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'general[name]="My list created from the API"' \
--data-urlencode 'general[description]="This is a test list, created from the API."' \
--data-urlencode 'defaults[from_name]="John Doe"' \
--data-urlencode 'defaults[from_email]="johndoe@doe.com"' \
--data-urlencode 'defaults[reply_to]="johndoe@doe.com"' \
--data-urlencode 'defaults[subject]="Hello!"' \
--data-urlencode 'notifications[subscribe]="yes"' \
--data-urlencode 'notifications[unsubscribe]="yes"' \
--data-urlencode 'notifications[subscribe_to]="johndoe@doe.com"' \
--data-urlencode 'notifications[unsubscribe_to]="johndoe@doe.com"' \
--data-urlencode 'company[name]="John Doe INC"' \
--data-urlencode 'company[country]="United States"' \
--data-urlencode 'company[zone]="New York"' \
--data-urlencode 'company[address_1]="Some street address"' \
--data-urlencode 'company[address_2]=""' \
--data-urlencode 'company[zone_name]=""' \
--data-urlencode 'company[city]="New York City"' \
--data-urlencode 'company[zip_code]="10019"'
// 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 the following indexed arrays:

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

HTTP Request

POST https://cp.spotzee.marketing/api/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

curl --location --request PUT 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'general[name]="My list created from the API - now updated!"' \
--data-urlencode 'general[description]="This is a test list, created from the API."' \
--data-urlencode 'defaults[from_name]="John Doe"' \
--data-urlencode 'defaults[from_email]="johndoe@doe.com"' \
--data-urlencode 'defaults[reply_to]="johndoe@doe.com"' \
--data-urlencode 'defaults[subject]="Hello!"' \
--data-urlencode 'notifications[subscribe]="yes"' \
--data-urlencode 'notifications[unsubscribe]="yes"' \
--data-urlencode 'notifications[subscribe_to]="johndoe@doe.com"' \
--data-urlencode 'notifications[unsubscribe_to]="johndoe@doe.com"' \
--data-urlencode 'company[name]="John Doe INC"' \
--data-urlencode 'company[country]="United States"' \
--data-urlencode 'company[zone]="New York"' \
--data-urlencode 'company[address_1]="Some street address"' \
--data-urlencode 'company[address_2]=""' \
--data-urlencode 'company[zone_name]=""' \
--data-urlencode 'company[city]="New York City"' \
--data-urlencode 'company[zip_code]="10019"'
// 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 https://cp.spotzee.marketing/api/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

curl --location --request POST 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/copy' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/copy

URL Segments

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

Delete a list

curl --location --request DELETE 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/copy' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID

URL Segments

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

Fields

List fields endpoint

Not applicable
// CREATE THE ENDPOINT
$endpoint = new SpotzeeApi\Endpoint\ListFields();
# CREATE THE ENDPOINT
endpoint = ListFields.new
from spotzee.endpoint.list_fields import ListFields

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

Get all list fields

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/fields?pageNumber=1&perPage=10' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location --request GET 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/fields/FIELD-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location --request POST 'https://cp.spotzee.marketing/api/lists/LIST_UID/fields' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'type="dropdown"' \
--data-urlencode 'label="Text Label"' \
--data-urlencode 'tag="DROPDOWN"' \
--data-urlencode 'required="no"' \
--data-urlencode 'visibility="visible"' \
--data-urlencode 'sort_order=0' \
--data-urlencode 'help_text="Help"' \
--data-urlencode 'default_value=""' \
--data-urlencode 'description="Description"'
// 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
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

Update a list field

curl --location --request PUT 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/fields/FIELD-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'label="Text Label"' \
--data-urlencode 'tag="DROPDOWN"' \
--data-urlencode 'required="no"' \
--data-urlencode 'visibility="visible"' \
--data-urlencode 'sort_order=0' \
--data-urlencode 'help_text="Help"' \
--data-urlencode 'default_value=""' \
--data-urlencode 'description="Description"'
// 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
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

Delete a list field

curl --location --request DELETE 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/fields/LIST-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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

curl --location --request GET 'https://cp.spotzee.marketing/api/lists/fields/types' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/lists/fields/types

Segments

List segments endpoint

Not applicable
// CREATE THE ENDPOINT
$endpoint = new SpotzeeApi\Endpoint\ListSegments();
# CREATE THE ENDPOINT
endpoint = ListSegments.new
from spotzee.endpoint.list_segments import ListSegments

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

Get all list segments

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/segments?pageNumber=1&perPage=10' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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 in the segment

curl --location --request GET 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/segments/SEGMEMT-UNIQUE-ID/subscribers' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 segment.

HTTP Request

GET https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/lists/LIST_UID/segments' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'name="My list segment created from the API"' \
--data-urlencode 'operator_match="any"'
// 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": "xs655vtkcx569",
      "name": "my segment with cond"
    }
  }
}

This endpoint creates a list segment.

The data param can contain the following indexed arrays:

-> conditions - optional -> campaign_conditions - optional

HTTP Request

POST https://cp.spotzee.marketing/api/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

curl --location --request PUT 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'name="My list segment created from the API updated"' \
--data-urlencode 'operator_match="any"'
// 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/operators endpoint
            'value'       => 'domain.com', // required
        ],
        [
            'field_id'    => '95', // required . 
            'operator_id' => '4', // required .  See the API-URL/lists/segments/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"
}

This endpoint updates a list segment.

HTTP Request

PUT https://cp.spotzee.marketing/api/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

curl --location --request DELETE 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location --request GET 'https://cp.spotzee.marketing/api/lists/segments/operators' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/lists/segments/operators

Domains

Sending domains endpoint

Not applicable
/ CREATE THE ENDPOINT
$endpoint = new SpotzeeApi\Endpoint\SendingDomains();
# CREATE THE ENDPOINT
endpoint = SendingDomains.new
from spotzee.endpoint.sendingdomains import SendingDomains

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

Get all sending domains

curl --location --request 'https://cp.spotzee.marketing/api/ext/em/sending-domains' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// GET ALL ITEMS
$response = $endpoint->getSendingDomains;

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# GET ALL ITEMS
response = endpoint.get_sendingdomains

# DISPLAY RESPONSE
puts response.body
"""
GET ALL ITEMS
"""
response = endpointDomains.get_sendingdomains

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

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": {
        "name": "domain.com",
        "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu0zoexoRwgnO+mfzuoAQ\nq2S8+ErtHVvHMd6RID7FoNktLzvkCoLecS7u/9hSNf8U29BTIB9U06vauLisCPIt\nToGS9/NwHplcER3uddsdsdsxuZQSCKeeM395nzAC2W5Bx1ExqWWu+pcsWt0gJ\n+AQjMkPRXAnJhcPs3D5iyfrcs4cCzjuPUrhdTqV2wGbXpyUIyUzP0AwXgKZXpKzi\n3smWA/NZNr6ctxhhle0xQ4ldRqO8sDW+cR2PbxOdCl+7gqOmwp9XkpiyE32MQGDc\nU2xzQqtGTYZjkD9PKBtean959sVERr9O+QmQnQlQHSlGIN1YtAn5fWT6asdO7rNv\n6wIDAQAB\n-----END PUBLIC KEY-----\n",
        "locked": "no",
        "verified": "yes",
        "signing_enabled": "yes",
        "date_added": "2024-02-26T00:53:39.000Z",
        "last_updated": "2024-02-26T00:59:11.000Z",
        "dkim_selector": "20240226125339spz"
    }
}

This endpoint retrieves all the sending domains.

HTTP Request

GET https://cp.spotzee.marketing/api/ext/em/sending-domains

Query Parameters

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

Tracking domains endpoint

Not applicable
/ CREATE THE ENDPOINT
$endpoint = new SpotzeeApi\Endpoint\TrackingDomains();
# CREATE THE ENDPOINT
endpoint = TrackingDomains.new
from spotzee.endpoint.trackingdomains import TrackingDomains

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

Get all tracking domains

curl --location --request 'https://cp.spotzee.marketing/api/ext/em/tracking-domains' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// GET ALL ITEMS
$response = $endpoint->getTrackingDomains;

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# GET ALL ITEMS
response = endpoint.get_trackingdomains

# DISPLAY RESPONSE
puts response.body
"""
GET ALL ITEMS
"""
response = endpointDomains.get_trackingdomains

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

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": {
        "name": "trk.domain.com",
        "scheme": "https",
        "verified": "yes",
        "date_added": "2024-02-26T00:55:28.000Z",
        "last_updated": "2024-02-26T00:59:18.000Z"
    }
}

This endpoint retrieves all the tracking domains.

HTTP Request

GET https://cp.spotzee.marketing/api/ext/em/tracking-domains

Query Parameters

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

Subscribers

Subscribers endpoint

Not applicable
/ CREATE THE ENDPOINT
$endpoint = new SpotzeeApi\Endpoint\ListSubscribers();
# CREATE THE ENDPOINT
endpoint = ListSubscribers.new
from spotzee.endpoint.list_subscribers import ListSubscribers

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

Get all subscribers

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers?pageNumber=1&perPage=10' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/search-by-email?EMAIL=john.doe%40doe.com' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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
email yes Subscriber email to retrieve.

Search by email in all lists

curl --location 'https://cp.spotzee.marketing/api/lists/subscribers/search-by-email-in-all-lists?EMAIL=john.doe%40doe.com' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 all lists.

HTTP Request

GET https://cp.spotzee.marketing/api/lists/subscribers/search-by-email-in-all-lists

Query Parameters

Parameter Required Description
email yes Subscriber email to retrieve.

Search by custom fields in a list

curl --location --globoff 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/search-by-custom-fields?array={%27CUSTOM_FIELD%27%20%3D%3E%20%27VALUE%27}&pageNumber=1&perPage=10' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 field values within a list given by LIST-UNIQUE-ID.

HTTP Request

GET https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers?pageNumber=1&perPage=10&status=active' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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 https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers?pageNumber=1&perPage=10&status=confirmed' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers?pageNumber=1&perPage=10&status=unconfirmed' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers?pageNumber=1&perPage=10&status=unsubscribed' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'EMAIL="john.doe@doe.com"' \
--data-urlencode 'PHONE="+12025550145"' \
--data-urlencode 'FNAME="John"' \
--data-urlencode 'LNAME="Doe"'
// 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 https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'EMAIL="john.doe-1@doe.com"' \
--data-urlencode 'PHONE="+12025550145"' \
--data-urlencode 'FNAME="John"' \
--data-urlencode 'LNAME="Doe"' \
--data-urlencode 'EMAIL="john.doe-2@doe.com"' \
--data-urlencode 'PHONE="+12025550146"' \
--data-urlencode 'FNAME="John"' \
--data-urlencode 'LNAME="Doe"' \
--data-urlencode 'EMAIL="john.doe-3@doe.com"' \
--data-urlencode 'PHONE="+12025550147"' \
--data-urlencode 'FNAME="John"' \
--data-urlencode 'LNAME="Doe"'
// ADD SUBSCRIBERS IN BULK
$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
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
"""
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 https://cp.spotzee.marketing/api/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

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

curl --location --request PUT 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'EMAIL="john.doe@doe.com"' \
--data-urlencode 'PHONE="+12025550145"' \
--data-urlencode 'FNAME="John"' \
--data-urlencode 'LNAME="Doe"'

HTTP Request

PUT https://cp.spotzee.marketing/api/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

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

curl --location --request PUT 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'EMAIL="john.doe@doe.com"' \
--data-urlencode 'FNAME="John 1"'

HTTP Request

GET https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/search-by-email

PUT https://cp.spotzee.marketing/api/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
EMAIL string yes Email to be searched
data array yes Array with the custom fields {name => value} to be updated.

Create/Update a subscriber

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

curl --location 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'EMAIL="john.doe4@doe.com"' \
--data-urlencode 'PHONE="+12025550145"' \
--data-urlencode 'FNAME="John"' \
--data-urlencode 'LNAME="Doe"'

HTTP Request

GET https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/search-by-email

PUT https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID

POST https://cp.spotzee.marketing/api/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.
EMAIL string yes Email to be searched

Unsubscribe a subscriber

curl --location --request PUT 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID/unsubscribe' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location --request PUT 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID/unsubscribe' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'EMAIL="john@doe.com"'
// 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 https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/search-by-email

PUT https://cp.spotzee.marketing/api/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
EMAIL yes Subscriber email to unsubscribe.

Unsubscribe a subscriber by email address from all the lists

curl --location --request PUT 'https://cp.spotzee.marketing/api/lists/subscribers/unsubscribe-by-email-from-all-lists' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'EMAIL="john@doe.com"'
// 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 https://cp.spotzee.marketing/api/lists/subscribers/unsubscribe-by-email-from-all-lists

PUT Parameters

Parameter Required Description
EMAIL yes Subscriber email to unsubscribe.

Delete one subscriber

curl --location --request DELETE 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location --request DELETE 'https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'EMAIL="john@doe.com"'
// 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 https://cp.spotzee.marketing/api/lists/LIST-UNIQUE-ID/subscribers/search-by-email

DELETE https://cp.spotzee.marketing/api/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
email yes Subscriber email to retrieve.

Email campaigns

Email campaigns endpoint

Not applicable
// CREATE THE ENDPOINT
$endpoint = new SpotzeeApi\Endpoint\Campaigns();
# CREATE THE ENDPOINT
endpoint = Campaigns.new 
from datetime import datetime, timedelta
from spotzee.endpoint.campaigns import Campaigns

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

Get all email campaigns

curl --location 'https://cp.spotzee.marketing/api/campaigns?pageNumber=1&perPage=10' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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": "1",
          "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 campaign #1",
          "status": "draft",
          "group": []
        },
        {
          "campaign_uid": "db516xtc45237",
          "campaign_id": "17",
          "name": "API campaign #2",
          "status": "draft",
          "group": []
        },
        {
          "campaign_uid": "ld526wjke1ff4",
          "campaign_id": "18",
          "name": "API campaign #1",
          "status": "draft",
          "group": []
        },
        {
          "campaign_uid": "bx831rctawf92",
          "campaign_id": "19",
          "name": "API campaign",
          "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 https://cp.spotzee.marketing/api/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 email campaign

curl --location 'https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID

URL Segments

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

Create an email campaign

curl --location 'https://cp.spotzee.marketing/api/campaigns' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'campaign[name]="My API Campaign"' \
--data-urlencode 'campaign[type]="regular"' \
--data-urlencode 'campaign[from_name]="John Doe"' \
--data-urlencode 'campaign[from_email]="john.doe@doe.com"' \
--data-urlencode 'campaign[subject]="Hey, i am testing the campaigns via API"' \
--data-urlencode 'campaign[reply_to]="john.doe@doe.com"' \
--data-urlencode 'campaign[send_at]="2019-06-04 18:10:05"' \
--data-urlencode 'campaign[list_uid]="LIST-UNIQUE-ID"' \
--data-urlencode 'campaign[segment_uid]="SEGMENT-UNIQUE-ID"' \
--data-urlencode 'options[url_tracking]="no"' \
--data-urlencode 'options[json_feed]="no"' \
--data-urlencode 'options[xml_feed]="no"' \
--data-urlencode 'options[plain_text_email]="yes"' \
--data-urlencode 'options[email_stats]=""' \
--data-urlencode 'options[autoresponder_event]="AFTER-SUBSCRIBE"' \
--data-urlencode 'options[autoresponder_time_unit]="hour"' \
--data-urlencode 'options[autoresponder_time_value]="1"' \
--data-urlencode 'options[autoresponder_open_campaign_id]="1"' \
--data-urlencode 'options[cronjob]="0 0 * * *"' \
--data-urlencode 'options[cronjob_enabled]="1"' \
--data-urlencode 'template[archive]=@"/Desktop/template.zip"' \
--data-urlencode 'template[template_uid]="TEMPLATE-UNIQUE-ID"' \
--data-urlencode 'template[content]=@"/Desktop/template-example.zip"' \
--data-urlencode 'template[inline_css]="no"' \
--data-urlencode 'template[plain_text]=""' \
--data-urlencode 'template[auto_plain_text]="yes"'
// 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 https://cp.spotzee.marketing/api/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 Spotzee
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
tracking_domain_id string yes Tracking domain id from Spotzee
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 an email campaign

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

HTTP Request

PUT https://cp.spotzee.marketing/api/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 an email campaign

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

HTTP Request

POST https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID/copy

URL Segments

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

Pause/unpause an email campaign

This endpoint pauses/unpauses the campaign with the given CAMPAIGN-UNIQUE-ID.

curl --location --request PUT 'https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID/pause-unpause' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

HTTP Request

PUT https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID/pause-unpause

URL Segments

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

Mark an email campaign as sent

curl --location --request PUT 'https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID/mark-sent' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID/mark-sent

URL Segments

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

Delete an email campaign

curl --location --request DELETE 'https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID

URL Segments

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

Get stats on an email campaign

curl --location 'https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID/stats' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 from the given CAMPAIGN-UNIQUE-ID.

HTTP Request

GET https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID/stats

URL Segments

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

Campaigns tracking endpoint

Not applicable
// 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()

Email campaigns tracking

curl --location 'https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UID/track-url/SUBSCRIBER-UNIQUE-ID/URL-HASH' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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": {}
}

Track subscriber clicks for the campaign. This endpoint set a campaign tracking URL click action.

HTTP Request

GET https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UID/track-opening/SUBSCRIBER-UID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UID/track-unsubscribe/SUBSCRIBER-UID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'ip_address="123.123.123.123"' \
--data-urlencode '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"' \
--data-urlencode 'reason="Reason for 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 https://cp.spotzee.marketing/api/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

Bounces endpoint

Not applicable
// 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

curl --location 'https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID/bounces?pageNumber=1&perPage=10' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID/bounces' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'message="The reason why this email bounced"' \
--data-urlencode 'bounce_type="hard"' \
--data-urlencode 'subscriber_uid="SUBSCRIBER-UNIQUE-ID"'
// 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 https://cp.spotzee.marketing/api/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

Delivery logs endpoint

Not applicable
// CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\CampaignDeliveryLogs();

Get all delivery logs

curl --location 'https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID/delivery-logs' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// GET ALL ITEMS
$response = $endpoint->getDeliveryLogs($campaignUid = 'CAMPAIGN-UNIQUE-ID', $pageNumber = 1, $perPage = 10);

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

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "2",
    "total_pages": 1,
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "records": [
      {
        "campaign": {
          "campaign_uid": "so5554wgk2cd6",
          "list": {
            "list_uid": "ab5554xyz2cd6"
          }
        },
        "subscriber": {
          "subscriber_uid": "gz589po8oz3af",
          "email": "subscriber87@example.gov"
        },
        "message": "OK",
        "retries": "0",
        "max_retries": "3",
        "email_message_id": "38de121ef62e8c9c2a12fa63679f764f7c3a259c@onetwist.com",
        "delivery_confirmed": "yes",
        "status": "success",
        "date_added": "2021-12-20 09:29:31"
      },
      {
        "campaign": {
          "campaign_uid": "so5554wgk2cd6",
          "list": {
            "list_uid": "ab5554xyz2cd6"
          }
        },
        "subscriber": {
          "subscriber_uid": "rs727cybga6d0",
          "email": "subscriber68@gmail.net"
        },
        "message": "OK",
        "retries": "0",
        "max_retries": "3",
        "email_message_id": "1174caa36efedc6d6c91e0ea4cce5fdda9bc7a4a@onetwist.com",
        "delivery_confirmed": "yes",
        "status": "success",
        "date_added": "2021-12-20 09:29:27"
      }
    ]
  }
}

This endpoint retrieves all the delivery logs of a campaign.

HTTP Request

GET https://cp.spotzee.marketing/api/campaigns/CAMPAIGN-UNIQUE-ID/delivery-logs

URL Segments

Segment Required Description
CAMPAIGN-UNIQUE-ID yes Campaign to retrieve the delivery logs for.

Query Parameters

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

Get a delivery log based on its unique email message id

curl --location 'https://cp.spotzee.marketing/api/campaigns/delivery-logs/email-message-id/EMAIL-MESSAGE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// GET A DELIVERY LOG BY THE EMAIL MESSAGE ID
$response = $endpoint->getDeliveryLogByEmailMessageId('EMAIL-MESSAGE-ID');

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

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "record": {
      "campaign": {
        "campaign_uid": "so5554wgk2cd6",
        "list": {
          "list_uid": "ab5554xyz2cd6"
        }
      },
      "subscriber": {
        "subscriber_uid": "nh567s19hw8a0",
        "email": "subscriber38@gmail.mil"
      },
      "message": "OK",
      "retries": "0",
      "max_retries": "3",
      "email_message_id": "e79019a2b9cad8c73cd0d3137913378005a69fc1@onetwist.com",
      "delivery_confirmed": "yes",
      "status": "success",
      "date_added": "2021-12-20 09:29:26"
    }
  }
}

This endpoint retrieves a delivery log based on its unique email message id.

HTTP Request

GET https://cp.spotzee.marketing/api/campaigns/delivery-logs/email-message-id/EMAIL-MESSAGE-ID

EMAIL-MESSAGE-ID - The email unique ID to retrieve the delivery log.

URL Segments

Segment Required Description
EMAIL-MESSAGE-ID yes The email unique id to retrieve the delivery log for.

Email delivery

Email delivery endpoint

Not applicable

Get email delivery credits

curl --location 'https://cp.spotzee.marketing/api/email-delivery/credits' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": {
        "remain": "22825",
        "total": "100000",
        "used": "77175",
        "last_reset": "2024-03-19 21:50:33",
        "next_reset": "2024-04-19 21:50:33"
    }
}

This endpoint retrieves the email delivery credit balance.

Get all email delivery activity

curl --location 'https://cp.spotzee.marketing/api/email-delivery/email-activity?page=1&limit=3&start_date=2024-04-01&end_date=2024-04-30' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": {
        "count": 10,
        "total_pages": 1,
        "current_page": 1,
        "next_page": null,
        "prev_page": null,
        "records": [
            {
                "email_id": 1,
                "email_uid": "abcd1234",
                "to_email": "john@example.com",
                "to_name": "John Doe",
                "from_email": "jane@example.com",
                "from_name": "Jane Smith",
                "reply_to_email": "jane@example.com",
                "reply_to_name": "Jane Smith",
                "subject": "Test Email 1",
                "priority": 3,
                "retries": 0,
                "max_retries": 3,
                "send_at": "2024-01-01 09:00:00",
                "status": "sent",
                "date_added": "2024-01-01 08:55:00",
                "last_updated": "2024-01-01 09:00:02",
                "tracking_domain_id": 1,
                "email_stream_uid": null
            },
            {
                "email_id": 2,
                "email_uid": "efgh5678",
                "to_email": "bob@example.com",
                "to_name": "Bob Johnson",
                "from_email": "alice@example.com",
                "from_name": "Alice Brown",
                "reply_to_email": "alice@example.com",
                "reply_to_name": "Alice Brown",
                "subject": "Test Email 2",
                "priority": 4,
                "retries": 1,
                "max_retries": 3,
                "send_at": "2024-01-02 10:30:00",
                "status": "delivered",
                "date_added": "2024-01-02 10:25:00",
                "last_updated": "2024-01-02 10:32:15",
                "tracking_domain_id": 2,
                "email_stream_uid": null
            },
            {
                "email_id": 3,
                "email_uid": "ijkl9012",
                "to_email": "sarah@example.com",
                "to_name": "Sarah Lee",
                "from_email": "mike@example.com",
                "from_name": "Mike Davis",
                "reply_to_email": "mike@example.com",
                "reply_to_name": "Mike Davis",
                "subject": "Test Email 3",
                "priority": 2,
                "retries": 0,
                "max_retries": 3,
                "send_at": "2024-01-03 14:15:00",
                "status": "opened",
                "date_added": "2024-01-03 14:10:00",
                "last_updated": "2024-01-03 14:17:45",
                "tracking_domain_id": 1,
                "email_stream_uid": "stream123"
            }
        ]
    }
}

This endpoint retrieves all the email delivery activity.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/email-activity

Query Parameters

Parameter Default Description
page 1 Current page to retrieve.
limit 10 Items per page to retrieve.
start_date last 7 days The ‘From date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
end_date last 7 days The ‘To date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
email_stream You can get data that is relating to specified email stream code

Get email delivery stats

curl --location 'https://cp.spotzee.marketing/api/email-delivery/get-stats?page=1&start_date=2024-04-01&end_date=2024-04-30' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": {
        "processed_count": 279841,
        "delivery_success_count": 279725,
        "delivery_success_rate": 99,
        "delivery_error_count": 27,
        "delivery_error_rate": 0,
        "opens_count": 20838,
        "opens_rate": 7,
        "unique_opens_count": 1,
        "unique_opens_rate": 0,
        "clicks_count": 389492,
        "clicks_rate": 139,
        "unique_clicks_count": 1,
        "unique_clicks_rate": 0,
        "unsubscribes_count": 8797,
        "unsubscribes_rate": 3,
        "complaints_count": 5333,
        "complaints_rate": 1,
        "bounces_count": 60275,
        "bounces_rate": 21,
        "hard_bounces_count": 58575,
        "hard_bounces_rate": 20,
        "soft_bounces_count": 7,
        "soft_bounces_rate": 0,
        "internal_bounces_count": 1693,
        "internal_bounces_rate": 0
    }
}

This endpoint retrieves all the stats for the emails delivered.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/get-stats

Query Parameters

Parameter Default Description
page 1 Current page to retrieve.
limit 10 Items per page to retrieve.
start_date last 7 days The ‘From date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
end_date last 7 days The ‘To date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
email_stream You can get data that is relating to specified email stream code

Get an email delivery detail

curl --location 'https://cp.spotzee.marketing/api/email-delivery/email-query/EMAIL-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": {
        "email_id": 1,
        "email_uid": "abcd1234",
        "to_email": "john@example.com",
        "to_name": "John Doe",
        "from_email": "jane@example.com",
        "from_name": "Jane Smith",
        "reply_to_email": "jane@example.com",
        "reply_to_name": "Jane Smith",
        "subject": "Summer sale on now!",
        "send_at": "2024-01-01 09:00:00",
        "status": "sent",
        "email_stream_uid": "stream123",
        "open_count": 1,
        "open_records": [
            {
                "ip_address": "172.212.2.7",
                "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.198 Safari/537.36",
                "date_added": "2024-01-02 09:00:00",
                "email_stream_uid": "stream123"
            }
        ],
        "click_count": 1,
        "click_records": [
            {
                "destination": "https://summersale.com",
                "date_added": "2024-01-03 09:00:00",
                "email_stream_uid": "stream123"
            }
        ],
        "bounce_count": 0,
        "bounce_records": [],
        "unsubscribe_count": 0,
        "unsubscribe_records": [],
        "complaint_count": 0,
        "complaint_records": []
    }
}

This endpoint retrieves all the stats for the emails delivered.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/email-query

URL Segments

Segment Required Description
EMAIL-UNIQUE-ID yes Email’s unique id which to retrieve.

Get email delivery opens

curl --location 'https://cp.spotzee.marketing/api/email-delivery/opens?page=1&limit=3&start_date=2024-04-01 00:00:00&end_date=2024-04-30 17:30:00' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

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": "abcd1234",
                "from_email": "sender1@example.com",
                "to_email": "recipient1@example.com",
                "subject": "Test Email 1",
                "ip_address": "192.168.0.1",
                "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
                "date_added": "2024-01-01 09:00:00",
                "email_stream_uid": "stream123",
                "opened_times": 2
            },
            {
                "email_uid": "efgh5678",
                "from_email": "sender2@example.com",
                "to_email": "recipient2@example.com",
                "subject": "Test Email 2",
                "ip_address": "10.0.0.1",
                "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
                "date_added": "2024-02-15 14:30:00",
                "email_stream_uid": "stream456",
                "opened_times": 1
            },
            {
                "email_uid": "ijkl9012",
                "from_email": "sender3@example.com",
                "to_email": "recipient3@example.com",
                "subject": "Test Email 3",
                "ip_address": "172.16.0.1",
                "user_agent": "Mozilla/5.0 (Linux; Android 12; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Mobile Safari/537.36",
                "date_added": "2024-03-30 18:45:00",
                "email_stream_uid": "stream789",
                "opened_times": 3
            }
        ]
    }
}

This endpoint retrieves all the opens for the emails delivered.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/opens

Query Parameters

Parameter Default Description
page 1 Current page to retrieve.
limit 10 Items per page to retrieve.
start_date last 7 days The ‘From date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
end_date last 7 days The ‘To date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
email_stream You can get data that is relating to specified email stream code

Get email delivery unique opens

curl --location 'https://cp.spotzee.marketing/api/email-delivery/unique-opens?page=1&limit=3&start_date=2024-04-01 00:00:00&end_date=2024-04-30 17:30:00' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

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": "abcd1234",
                "from_email": "sender1@example.com",
                "to_email": "recipient1@example.com",
                "subject": "Test Email 1",
                "ip_address": "192.168.0.1",
                "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
                "date_added": "2024-01-01 09:00:00",
                "email_stream_uid": "stream123",
                "opened_times": 2
            },
            {
                "email_uid": "efgh5678",
                "from_email": "sender2@example.com",
                "to_email": "recipient2@example.com",
                "subject": "Test Email 2",
                "ip_address": "10.0.0.1",
                "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
                "date_added": "2024-02-15 14:30:00",
                "email_stream_uid": "stream456",
                "opened_times": 1
            },
            {
                "email_uid": "ijkl9012",
                "from_email": "sender3@example.com",
                "to_email": "recipient3@example.com",
                "subject": "Test Email 3",
                "ip_address": "172.16.0.1",
                "user_agent": "Mozilla/5.0 (Linux; Android 12; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Mobile Safari/537.36",
                "date_added": "2024-03-30 18:45:00",
                "email_stream_uid": "stream789",
                "opened_times": 3
            }
        ]
    }
}

This endpoint retrieves all the unique opens for the emails delivered.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/unique-opens

Query Parameters

Parameter Default Description
page 1 Current page to retrieve.
limit 10 Items per page to retrieve.
start_date last 7 days The ‘From date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
end_date last 7 days The ‘To date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
email_stream You can get data that is relating to specified email stream code

Get email delivery clicks

curl --location 'https://cp.spotzee.marketing/api/email-delivery/clicks?page=1&limit=3&start_date=2024-04-01 00:00:00&end_date=2024-04-30 17:30:00' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

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": "abcd1234",
                "from_email": "sender1@example.com",
                "to_email": "recipient1@example.com",
                "subject": "Test Email 1",
                "destination": "https://example.com/unsubscribe/1",
                "date_added": "2024-01-01 09:00:00",
                "email_stream_uid": "stream123",
                "clicked_times": 2
            },
            {
                "email_uid": "efgh5678",
                "from_email": "sender2@example.com",
                "to_email": "recipient2@example.com",
                "subject": "Test Email 2",
                "destination": "https://example.com/login?ref=abc123",
                "date_added": "2024-02-15 14:30:00",
                "email_stream_uid": "stream456",
                "clicked_times": 1
            },
            {
                "email_uid": "ijkl9012",
                "from_email": "sender3@example.com",
                "to_email": "recipient3@example.com",
                "subject": "Test Email 3",
                "destination": "https://example.com/profile/update",
                "date_added": "2024-03-30 18:45:00",
                "email_stream_uid": "stream789",
                "clicked_times": 3
            }
        ]
    }
}

This endpoint retrieves all the clicks for the emails delivered.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/clicks

Query Parameters

Parameter Default Description
page 1 Current page to retrieve.
limit 10 Items per page to retrieve.
start_date last 7 days The ‘From date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
end_date last 7 days The ‘To date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
email_stream You can get data that is relating to specified email stream code

Get email delivery unique clicks

curl --location 'https://cp.spotzee.marketing/api/email-delivery/unique-clicks?page=1&limit=3&start_date=2024-04-01 00:00:00&end_date=2024-04-30 17:30:00' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

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": "abcd1234",
                "from_email": "sender1@example.com",
                "to_email": "recipient1@example.com",
                "subject": "Test Email 1",
                "destination": "https://example.com/unsubscribe/1",
                "date_added": "2024-01-01 09:00:00",
                "email_stream_uid": "stream123",
                "clicked_times": 2
            },
            {
                "email_uid": "efgh5678",
                "from_email": "sender2@example.com",
                "to_email": "recipient2@example.com",
                "subject": "Test Email 2",
                "destination": "https://example.com/login?ref=abc123",
                "date_added": "2024-02-15 14:30:00",
                "email_stream_uid": "stream456",
                "clicked_times": 1
            },
            {
                "email_uid": "ijkl9012",
                "from_email": "sender3@example.com",
                "to_email": "recipient3@example.com",
                "subject": "Test Email 3",
                "destination": "https://example.com/profile/update",
                "date_added": "2024-03-30 18:45:00",
                "email_stream_uid": "stream789",
                "clicked_times": 3
            }
        ]
    }
}

This endpoint retrieves all the unique clicks for the emails delivered.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/unique-clicks

Query Parameters

Parameter Default Description
page 1 Current page to retrieve.
limit 10 Items per page to retrieve.
start_date last 7 days The ‘From date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
end_date last 7 days The ‘To date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
email_stream You can get data that is relating to specified email stream code

Get email delivery unsubscribes

curl --location 'https://cp.spotzee.marketing/api/email-delivery/unsubscribes?page=1&limit=3&start_date=2024-04-01 00:00:00&end_date=2024-04-30 17:30:00' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

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": "abc123",
                "from_email": "sender1@example.com",
                "to_email": "recipient1@example.com",
                "subject": "Test Email 1",
                "date_added": "2024-01-01 09:00:00",
                "email_stream_uid": "stream123",
                "unsubscribe_reason": ""
            },
            {
                "email_uid": "def456",
                "from_email": "sender2@example.com",
                "to_email": "recipient2@example.com",
                "subject": "Test Email 2",
                "date_added": "2024-02-15 14:30:00",
                "email_stream_uid": "stream456",
                "unsubscribe_reason": ""
            },
            {
                "email_uid": "ghi789",
                "from_email": "sender3@example.com",
                "to_email": "recipient3@example.com",
                "subject": "Test Email 3",
                "date_added": "2024-03-30 18:45:00",
                "email_stream_uid": "stream789",
                "unsubscribe_reason": ""
            }
        ]
    }
}

This endpoint retrieves all unsubscribes or opt-outs for the emails delivered.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/unsubscribes

Query Parameters

Parameter Default Description
page 1 Current page to retrieve.
limit 10 Items per page to retrieve.
start_date last 7 days The ‘From date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
end_date last 7 days The ‘To date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
email_stream You can get data that is relating to specified email stream code

Get email delivery bounces

curl --location 'https://cp.spotzee.marketing/api/email-delivery/bounces?page=1&limit=3&start_date=2024-04-01 00:00:00&end_date=2024-04-30 17:30:00' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

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": "abc123",
                "from_email": "sender@example.com",
                "to_email": "nonexistent@example.com",
                "subject": "Test Email 1",
                "message": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces.",
                "bounce_type": "hard",
                "processed": "yes",
                "date_added": "2024-01-01 09:00:00",
                "email_stream_uid": null
            },
            {
                "email_uid": "def456",
                "from_email": "sender@example.com",
                "to_email": "recipient@example.com",
                "subject": "Test Email 2",
                "message": "Network error: Connection timed out",
                "bounce_type": "soft",
                "processed": "no",
                "date_added": "2024-02-15 14:30:00",
                "email_stream_uid": null
            },
            {
                "email_uid": "ghi789",
                "from_email": "sender@example.com",
                "to_email": "recipient@example.com",
                "subject": "Test Email 3",
                "message": "550 5.4.1 Recipient address rejected: Access denied.",
                "bounce_type": "hard",
                "processed": "yes",
                "date_added": "2024-03-30 18:45:00",
                "email_stream_uid": "stream123"
            }
        ]
    }
}

This endpoint retrieves all the soft, hard, and internal bounces for the emails delivered.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/bounces

Query Parameters

Parameter Default Description
page 1 Current page to retrieve.
limit 10 Items per page to retrieve.
start_date last 7 days The ‘From date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
end_date last 7 days The ‘To date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
email_stream You can get data that is relating to specified email stream code

Get email delivery spam complaints

curl --location 'https://cp.spotzee.marketing/api/email-delivery/complaints?page=1&limit=3&start_date=2024-04-01 00:00:00&end_date=2024-04-30 17:30:00' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

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": "abc123",
                "from_email": "sender1@example.com",
                "to_email": "recipient1@example.com",
                "subject": "Test Email 1",
                "date_added": "2024-01-01 09:00:00",
                "email_stream_uid": null
            },
            {
                "email_uid": "def456",
                "from_email": "sender2@example.com",
                "to_email": "recipient2@example.com",
                "subject": "Test Email 2",
                "date_added": "2024-02-15 14:30:00",
                "email_stream_uid": null
            },
            {
                "email_uid": "ghi789",
                "from_email": "sender3@example.com",
                "to_email": "recipient3@example.com",
                "subject": "Test Email 3",
                "date_added": "2024-03-30 18:45:00",
                "email_stream_uid": null
            }
        ]
    }
}

This endpoint retrieves all the spam/abuse complaints for the emails delivered.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/complaints

Query Parameters

Parameter Default Description
page 1 Current page to retrieve.
limit 10 Items per page to retrieve.
start_date last 7 days The ‘From date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
end_date last 7 days The ‘To date and time’ in YYYY/MM/DD HH:MM:SS format as per the user’s timezone.
email_stream You can get data that is relating to specified email stream code

Get email delivery IP address(es) assigned

curl --location 'https://cp.spotzee.marketing/api/email-delivery/ips/assigned' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": {
        "count": 2,
        "total_pages": 1,
        "current_page": 1,
        "next_page": null,
        "prev_page": null,
        "records": [
            {
                "ip": "192.0.0.1",
                "warmup": false,
                "date_added": "2022-04-01 12:15:14"
            },
            {
                "ip": "192.0.0.2",
                "warmup": false,
                "date_added": "2022-04-02 12:22:08"
            }
        ]
    }
}

This endpoint retrieves all the IP(s) assigned for the email delivery.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/ips/assigned

Get all email delivery HTTP webhook(s)

curl --location 'https://cp.spotzee.marketing/api/email-delivery/webhook/http' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": [
        "https://cp.spotzee.marketing/dswh/xxx/1"
    ]
}

This endpoint retrieves all the HTTP webhook(s) assigned for the email delivery.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/webhook/http

Create a email delivery HTTP webhook

curl --location --request POST 'https://cp.spotzee.marketing/api/email-delivery/webhook/http' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

The above command returns an object structured like this JSON:

{
    "status": "success"
}

This endpoint creates the specified HTTP webhook for the email delivery.

HTTP Request

POST https://cp.spotzee.marketing/api/email-delivery/webhook/http

Query Parameters

Parameter Default Description
url The HTTP webhook URL you wish to take action on.
event_types All The events you want your webhook to receive.

Delete email delivery HTTP webhook(s)

curl --location --request DELETE 'https://cp.spotzee.marketing/api/email-delivery/webhook/http' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

The above command returns an object structured like this JSON:

{
    "status": "success"
}

This endpoint deletes the specified HTTP webhook for the email delivery.

HTTP Request

DELETE https://cp.spotzee.marketing/api/email-delivery/webhook/http

Query Parameters

Parameter Default Description
url The HTTP webhook URL you wish to take action on.

Get all email delivery email webhook(s)

curl --location 'https://cp.spotzee.marketing/api/email-delivery/webhook/email' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": [
      "receive-events@domain.com"
    ]
}

This endpoint retrieves all the email webhook(s) assigned for the email delivery.

HTTP Request

GET https://cp.spotzee.marketing/api/email-delivery/webhook/email

Create a email delivery email webhook

curl --location --request POST 'https://cp.spotzee.marketing/api/email-delivery/webhook/email' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

The above command returns an object structured like this JSON:

{
    "status": "success"
}

This endpoint creates the specified email webhook for the email delivery.

HTTP Request

POST https://cp.spotzee.marketing/api/email-delivery/webhook/email

Query Parameters

Parameter Default Description
email The email webhook address you wish to take action on.
event_types All The events you want your webhook to receive.

Delete email delivery email webhook

curl --location --request DELETE 'https://cp.spotzee.marketing/api/email-delivery/webhook/email' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'

The above command returns an object structured like this JSON:

{
    "status": "success"
}

This endpoint deletes the specified email webhook for the email delivery.

HTTP Request

DELETE https://cp.spotzee.marketing/api/email-delivery/webhook/email

Query Parameters

Parameter Default Description
email The email webhook address you wish to take action on.

Email templates

Email templates endpoint

Not applicable
// CREATE THE ENDPOINT
$endpoint = new SpotzeeApi\Endpoint\Templates();
# CREATE THE ENDPOINT
endpoint = Templates.new
from spotzee.endpoint.templates import Templates

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

Get all email templates

curl --location 'https://cp.spotzee.marketing/api/templates?pageNumber=1&perPage=10' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/templates

Query Parameters

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

Get one email template

curl --location 'https://cp.spotzee.marketing/api/templates/TEMPLATE-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/templates/TEMPLATE-UNIQUE-ID

URL Segments

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

Search email templates

curl --location --request GET 'https://cp.spotzee.marketing/api/templates?pageNumber=1&perPage=10' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'filters[name]="my template name"'
// Search ALL ITEMS
$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 key values.

HTTP Request

GET https://cp.spotzee.marketing/api/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 an email template

curl --location 'https://cp.spotzee.marketing/api/templates' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'name="My API template"' \
--data-urlencode 'content=@"/Desktop/template-example.html"' \
--data-urlencode 'archive=@"/Desktop/template-example.zip"' \
--data-urlencode 'inline_css="no"'
// 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 https://cp.spotzee.marketing/api/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 an email template

curl --location --request PUT 'https://cp.spotzee.marketing/api/templates/TEMPLATE-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'name="My API template"' \
--data-urlencode 'content=@"/Desktop/template-example.html"' \
--data-urlencode 'archive=@"/Desktop/template-example.zip"' \
--data-urlencode 'inline_css="no"'
// 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 https://cp.spotzee.marketing/api/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 an email template

curl --location --request DELETE 'https://cp.spotzee.marketing/api/templates/TEMPLATE-UNIQUE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' 
// 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 https://cp.spotzee.marketing/api/templates/TEMPLATE-UNIQUE-ID

URL Segments

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

Email validation

Email validation endpoint

Not applicable
// CREATE THE ENDPOINT
$endpoint = new SpotzeeApi\Endpoint\EmailValidation();
# CREATE THE ENDPOINT
endpoint = EmailValidation.new
from spotzee.endpoint.emailvalidation import EmailValidation

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

Validate a single email

curl --location 'https://cp.spotzee.marketing/api/email-validation/validate-single' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'email="john.doe@doe.com"'
// VALIDATE A SINGLE EMAIL
$response = $endpoint->create([
    'email'           => 'john.doe@doe.com' // required
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# VALIDATE A SINGLE EMAIL
response = endpoint.create(data = {
    'email': 'john.doe@doe.com' # required
})

# DISPLAY RESPONSE
puts response.body
"""
VALIDATE A SINGLE EMAIL
"""
response = endpoint.create(data={
    'email': 'john.doe@doe.com'  # required
})

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

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": {
        "email": "john.doe@doe.com",
        "result": "catch_all",
        "resultcode": 2
    }
}

This endpoint validates a single email.

HTTP Request

POST https://cp.spotzee.marketing/api/email-validation/validate-single

POST Parameters

Parameter Type Required Description
email string yes The email address you would like to validate.

Validate via file upload

curl --location 'https://cp.spotzee.marketing/api/email-validation/file-upload' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'file=@"email="/file.csv"'
// VALIDATE MULTIPLE EMAILS
$response = $endpoint->create([
    'file'       => file_get_contents(__DIR__ . '/file.csv')
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# VALIDATE MULTIPLE EMAILS
response = endpoint.create(data = {
    'file': File.read('file.csv')
})

# DISPLAY RESPONSE
puts response.body
"""
VALIDATE MULTIPLE EMAILS
"""
response = endpoint.create(data={
    'file': open('file.csv', 'r').read()
})

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

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": {
        "unique_emails": 100,
        "file_id": 13777
    }
}

This endpoint validates multiple emails that exist in the provided file.

HTTP Request

POST https://cp.spotzee.marketing/api/email-validation/file-upload

POST Parameters

Parameter Type Required Description
file string yes The file containing all the email address you would like to validate. We accept CSV, TXT, XLSX formats.

Get the file information

curl --location 'https://cp.spotzee.marketing/api/email-validation/file-info' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'file_id="FILE-ID"'
// GET THE FILE INFORMATION
$response = $endpoint->create([
    'file_id'           => 'FILE-ID' // required
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# GET THE FILE INFORMATION
response = endpoint.create(data = {
    'file_id': 'FILE-ID' # required
})

# DISPLAY RESPONSE
puts response.body
"""
GET THE FILE INFORMATION
"""
response = endpoint.create(data={
    'file_id': 'FILE-ID'  # required
})

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

The above command returns an object structured like this JSON:

{
    "status": "success",
    "data": {
        "ok": 50,
        "invalid": 21,
        "unknown": 5,
        "revalidate": 2,
        "validated": 90,
        "catch_all": 10,
        "disposable": 7,
        "invalidated": 10,
        "unique_emails": 100,
        "status": "completed"
    }
}

This endpoint gets the information about the file uploaded.

HTTP Request

POST https://cp.spotzee.marketing/api/email-validation/file-info

POST Parameters

Parameter Type Required Description
file_id integer yes The file ID you would like the information on.

Download the results

curl --location 'https://cp.spotzee.marketing/api/email-validation/download-results?file_id=FILE-ID&filter=FILTERS&statuses=STATUSES&free=0&role=0' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// DOWNLOAD THE RESULTS
$response = $endpoint->create([
    'file_id'           => 'FILE-ID', // required
    'filter'            => 'FILTERS', // required
    'statuses'          => 'STATUSES',
    'free'              => '0',
    'role'              => '0'
]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# VALIDATE A SINGLE EMAIL
response = endpoint.create(data = {
    'file_id': 'FILE-ID', # required
    'filter': 'FILTERS', # required
    'statuses': 'STATUSES',
    'free': '0',
    'role': '0'
})

# DISPLAY RESPONSE
puts response.body
"""
VALIDATE A SINGLE EMAIL
"""
response = endpoint.create(data={
    'file_id': 'FILE-ID',  # required
    'filter': 'FILTERS',  # required
    'statuses': 'STATUSES',
    'free': '0',
    'role': '0'
})

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

The above command returns an object structured like this JSON:

"email","quality","result","free","role","name","attributes"
"john.doe-1@doe.com","good","ok","yes","yes","John Doe","{""age"": 42, ""planet"": ""Mars""}"
"john.doe-2@doe.com","good","ok","yes","no","John Doe","{""age"": 24, ""job"": ""Time Traveller""}"

This endpoint downloads email validation results.

HTTP Request

POST https://cp.spotzee.marketing/api/email-validation/download-results

Query Parameters

Parameter Type Required Description
file_id string yes The results you want to download for a given file.
filter string yes The filtered downloadable results. Possible values are ok, ok_and_catch_all, unknown, invalid, all, custom.
statuses string no The filtered downloadable results. Possible values are ok, catch_all, unknown, invalid, disposable. Eg. statuses=ok,invalid,disposable
free string no The option to filter free email service provider’s emails. Possible values are 0, 1.
role string no The option to filter role-based email addresses. Possible values are 0, 1.

Delete a file

curl --location --request DELETE 'https://cp.spotzee.marketing/api/email-validation/delete-file?file_id=FILE-ID' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// DELETE A FILE
$response = $endpoint->delFile($file_id = FILE-ID);

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';
# DELETE A FILE
response = endpoint.del_file(file_id = FILE-ID)

# DISPLAY RESPONSE
puts response.body
"""
DELETE A FILE
"""
response = endpointLists.del_file(file_id=FILE-ID)

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

The above command returns an object structured like this JSON:

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

This endpoint deletes the file uploaded for processing.

HTTP Request

DELETE https://cp.spotzee.marketing/api/email-validation/delete-file

Query Parameters

Parameter Type Required Description
file_id integer yes The file ID you would like to delete.

Get the balance

curl --location 'https://cp.spotzee.marketing/api/email-validation/balance' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// VALIDATE A SINGLE EMAIL
$response = $endpoint->create([]);

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';
# VALIDATE A SINGLE EMAIL
response = endpoint.create(data = {})

# DISPLAY RESPONSE
puts response.body
"""
VALIDATE A SINGLE EMAIL
"""
response = endpoint.create(data={})

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

The above command returns an object structured like this JSON:

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

This endpoint retrieves the credit balance.

HTTP Request

GET https://cp.spotzee.marketing/api/email-validation/balance

Countries

Countries endpoint

Not applicable
// CREATE THE ENDPOINT
$endpoint = new SpotzeeApi\Endpoint\Countries();
# CREATE THE ENDPOINT
endpoint = Countries.new
from spotzee.endpoint.countries import Countries

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

Get all countries

curl --location 'https://cp.spotzee.marketing/api/countries?pageNumber=1&perPage=10' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/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

curl --location 'https://cp.spotzee.marketing/api/countries/COUNTRY-ID/zones?pageNumber=1&perPage=10' \
--header 'X-SPZ-PUBLIC-KEY: API-KEY'
// 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 https://cp.spotzee.marketing/api/countries/COUNTRY-ID/zones

URL Segments

Segment Required Description
COUNTRY-ID Yes Country ID to retrieve zones for.

Query Parameters

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