Lists

Lists endpoints of the MailWizz API.

Lists endpoint

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

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

Get all lists

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

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

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

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

The above command returns an object structured like this JSON:

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

This endpoint retrieves all the lists.

HTTP Request

GET API-URL/lists

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.

Get one list

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

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

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

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

The above command returns an object structured like this JSON:

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

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

HTTP Request

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

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id which to retrieve.

Create a list

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

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

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

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

The above command returns an object structured like this JSON:

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

This endpoint creates a list.

The $data param can contain following indexed arrays:

-> general - required

-> defaults - required

-> notifications - optional

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

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

HTTP Request

POST API-URL/lists

POST Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the list details. The following indexed arrays are accepted: general, defaults, notifications, company

General block - required

ParameterTypeRequiredDescription
namestringyesList name
descriptionstringyesList description

Defaults block - required

ParameterTypeRequiredDescription
from_namestringyesFrom name
from_emailstringyesFrom email
reply_tostringyesReply to email
subjectstringnoList subject

Notifications block - optional

ParameterTypeRequiredDescription
subscribeYes/NonoNotification when new subscriber added
unsubscribeYes/NonoNotification when new subscriber unsubscribe
subscribe_tostringnoWhere to send the notifications on subscribe
unsubscribe_tostringnoWhere to send the notifications on unsubscribe

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

ParameterTypeRequiredDescription
namestringyesCompany name
countrystringyesCompany country
zonestringyesCompany zone
address_1stringyesCompany address
address_2stringnoCompany address 2
zone_namestringnoCompany address - when country doesn’t have required zone.
citystringnoCompany city
zipcodestringnoCompany zipcode

Update a list

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

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

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

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

The above command returns an object structured like this JSON:

{
  "status":"success"
}

This endpoint updates a list.

HTTP Request

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

URL Segment

SegmentTypeRequiredDescription
LIST-UNIQUE-IDstringyesList unique identifier

POST Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the list details. The following indexed arrays are accepted: general, defaults, notifications, company. See the create section for details

Copy a list

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

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

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

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

The above command returns an object structured like this JSON:

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

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

HTTP Request

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

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to copy.

Delete a list

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

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

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

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

The above command returns an object structured like this JSON:

{
  "status":"success"
}

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

HTTP Request

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

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to delete.