# Introduction
Welcome to the **SenderWiz API Documentation** π
**SenderWiz** offers a robust and flexible API that allows seamless integration with third-party platforms, custom applications, and internal tools. With this API, you can automate workflows, manage email campaigns, and access key SenderWiz functionalities programmatically.
### Overview
The SenderWiz API provides all essential operations to power your integration needs β from creating campaigns and managing contacts to sending emails and retrieving reports.
By following industry-standard RESTful conventions, the API is simple to use, predictable, and developer-friendly.
### HTTP Methods Used
SenderWiz API adheres to the REST architecture and uses standard HTTP methods:
* **`POST`** β Used to create new resources
* **`GET`** β Used to retrieve or list existing resources
* **`PUT`** β Used to update existing resources
* **`DELETE`** β Used to remove resources
> β οΈ Ensure that your server or hosting provider supports **PUT** and **DELETE** methods. If you encounter an **HTTP 403 Forbidden** error during these operations, your server may be blocking these methods. Please review your server configuration or contact your hosting provider to allow them.
### Authorization
Authentication is required for all API requests and is handled via API keys sent in custom headers.
Depending on the type of access required, use the appropriate header:
* **Customer Tasks**: Use `X-API-KEY`
* **Admin Tasks**: Use `X-ADMIN-API-KEY`
Make sure to keep your API keys secure and never expose them in public-facing applications.
### Data Format
* **Requests**: Data must be sent using `form-data` (multipart/form-data) encoding.
* **Responses**: All API responses are returned in standard **JSON** format for easy parsing and integration.
***
# API URL and Key
This guide explains how customers and administrators can locate their respective API URLs and generate API keys to start integrating with the SenderWiz platform.
### π Accessing Your API URL and Key
To integrate with SenderWiz, you'll need your unique **API URL** and **API key**.
These are available separately for both **Customer** and **Admin** panels.
***
### π€ Customer Panel
#### Step 1: Go to API Section
* Login to your **Customer Account**
* Click on your name or profile in the top-right corner
* From the dropdown, select **API**
***
#### Step 2: View API URL
* Once in the API section, click the **info** icon (`βΉοΈ`)
* A pop-up will show your API base URL\
π Example: `https://app.senderwizpro.com/api`
***
#### Step 3: Create API Key
* Click the **Create new** button
* Your API key will be instantly generated
* You can add optional fields like:
* **Name** (to label the key)
* **IP Whitelist**
* **IP Blacklist**
* After entering the optional fields, click **Save changes**
***
### π οΈ Admin Panel
The process for Admin is similar to the Customer panel but is accessible only via the **Admin Dashboard**. The Admin will have separate keys and API endpoint URLs.
{% hint style="warning" %}
Please ensure that you do not share your API key publicly. Treat it like a password.
{% endhint %}
#### Step 1: Go to API Section
* Login to your **Admin Account**
* Click on your name or profile in the top-right corner
* From the dropdown, select **API**
***
#### Step 2: View API URL
* Once in the API section, click the **info** icon (`βΉοΈ`)
* A pop-up will show your API base URL\
π Example: `https://app.senderwizpro.com/api/admin`
***
#### Step 3: Create API Key
* Click the **Create new** button
* Your API key will be instantly generated
* You can add optional fields like:
* **Name** (to label the key)
* **IP Whitelist**
* **IP Blacklist**
* After entering the optional fields, click **Save changes**
***
### Final Notes
* Use the generated API key in your integration headers or parameters.
* Always whitelist trusted IPs when setting up your API key for added security.
* You can manage, regenerate, or revoke API keys anytime from the same section.
***
# Contact List
# Get All Lists
Retrieve a paginated list of all subscriber lists associated with your SenderWiz account using this endpoint. Useful for managing and referencing available list records.
### π Get All Lists
Retrieve all available subscriber lists associated with your account.
#### **πΉ HTTP Request**
```http
GET API-URL/lists
```
#### **πΈ Query Parameters**
| Parameter | Default | Description |
| ---------- | ------- | ----------------------------------- |
| `page` | 1 | Current page number to retrieve. |
| `per_page` | 10 | Number of items per page to return. |
#### **π Authorization Header**
Include your customer API key:
```
X-API-KEY: your-api-key-here
```
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getLists($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
Returns a JSON array of list objects including metadata such as list ID, name, and creation details.
```json
{
"status": "success",
"data": {
"count": "12",
"total_pages": 2,
"current_page": 1,
"next_page": 2,
"prev_page": null,
"records": [
{
"general": {
"list_uid": "lm451q7h7j3e2",
"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": "xj35478ymfe15",
"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"
}
}
}
]
}
}
```
***
# Get One List
Fetch detailed information about a specific subscriber list by providing its unique list UID. Includes general, default, and notification configuration data.
### π Get One List
Retrieve details of a specific list using its unique ID.
#### **πΉ HTTP Request**
```http
GET API-URL/lists/LIST-UNIQUE-ID
```
#### **πΈ URL Segments**
| Segment | Required | Description |
| ---------------- | -------- | --------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the list to fetch. |
#### **π Authorization Header**
Include your customer API key:
```
X-API-KEY: your-api-key-here
```
#### π» PHP Example
```php
// get a single list
$response = $endpoint->getList('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
#### **π¦ Sample JSON Response**
```json
{
"status": "success",
"data": {
"record": {
"general": {
"list_uid": "lm451q7h7j3e2",
"name": "API Test List",
"display_name": "Testing list",
"description": "This is a test list, created from the API."
},
"defaults": {
"from_email": "emily.carter@example.org",
"from_name": "Emily Carter",
"reply_to": "emily.carter@example.org",
"subject": "Welcome to Our Newsletter!"
},
"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"
}
}
}
}
}
```
# Create a List
Create a new subscriber list by submitting general details, optional sender defaults, notification preferences information. Required fields must be included for a successful request.
### β Create a List
Create a new subscriber list under your SenderWiz account.
#### πΉ HTTP Request
```http
POST API-URL/lists
```
#### πΈ Authorization Header
Include your customer API key:
```
X-API-KEY: your-api-key-here
```
#### π POST Parameters
| Parameter | Type | Required | Description |
| --------- | ----- | -------- | ----------------------------------------------------------------------------------------- |
| `data` | array | Yes | Array containing list details. Accepts `general`, `defaults`, and `notifications` blocks. |
***
#### π¦ `general` Block *(Required)*
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ----------------- |
| `name` | string | Yes | Name of the list. |
| `description` | string | No | List description |
***
#### π¦ `defaults` Block *(Optional)*
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ----------------------- |
| `from_name` | string | Yes | Sender's name. |
| `from_email` | string | Yes | Sender's email address. |
| `reply_to` | string | Yes | Reply-to email address. |
| `subject` | string | No | Default subject line. |
***
#### π¦ `notifications` Block *(Optional)*
| Parameter | Type | Required | Description |
| ---------------- | ------ | -------- | --------------------------------------------------- |
| `subscribe` | Yes/No | No | Notify on new subscriber (yes or no). |
| `unsubscribe` | Yes/No | No | Notify on unsubscribe (yes or no). |
| `subscribe_to` | string | No | Email address to receive subscribe notifications. |
| `unsubscribe_to` | string | No | Email address to receive unsubscribe notifications. |
***
#### π» PHP Example
```php
// create a new list
$response = $endpoint->create([
// required
'general' => [
'name' => 'API Test List', // required
'description' => 'This is a test list, created from the API.', // optional
],
// optional
'defaults' => [
'from_name' => 'Emily Carter', // required
'from_email'=> 'emily.carter@example.org', // required
'reply_to' => 'emily.carter@example.org', // required
'subject' => 'Welcome to Our Newsletter!', // required
],
// 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' => 'emily.carter@example.org',
'unsubscribe_to' => 'emily.carter@example.org',
],
]);
// and get the response
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"list_uid": "lm451q7h7j3e2"
}
```
***
# Update a List
Update the details of an existing subscriber list using its unique list UID. This includes modifying sender info, list settings, and optional default, notification data.
### βοΈ Update a List
Update an existing subscriber list using its unique ID.
#### πΉ HTTP Request
```http
PUT API-URL/lists/LIST-UNIQUE-ID
```
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ---------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the list to update. |
#### π Authorization Header
Include your customer API key:
```
X-API-KEY: your-api-key-here
```
#### π PUT Parameters
| Parameter | Type | Required | Description |
| --------- | ----- | -------- | ----------------------------------------------------------------------------------------- |
| `data` | array | Yes | Array containing list details. Accepts `general`, `defaults`, and `notifications` blocks. |
***
#### π¦ `general` Block *(Required)*
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ----------------- |
| `name` | string | Yes | Name of the list. |
| `description` | string | No | List description |
***
#### π¦ `defaults` Block *(Optional)*
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ----------------------- |
| `from_name` | string | Yes | Sender's name. |
| `from_email` | string | Yes | Sender's email address. |
| `reply_to` | string | Yes | Reply-to email address. |
| `subject` | string | No | Default subject line. |
***
#### π¦ `notifications` Block *(Optional)*
| Parameter | Type | Required | Description |
| ---------------- | ------ | -------- | --------------------------------------------------- |
| `subscribe` | Yes/No | No | Notify on new subscriber (yes or no). |
| `unsubscribe` | Yes/No | No | Notify on unsubscribe (yes or no). |
| `subscribe_to` | string | No | Email address to receive subscribe notifications. |
| `unsubscribe_to` | string | No | Email address to receive unsubscribe notifications. |
***
#### π» PHP Example
```php
// update list
$response = $endpoint->update('LIST-UNIQUE-ID', [
// required
'general' => [
'name' => 'API Test List - Updated!', // required
'description' => 'This is a test list, updated from the API.', // optional
],
// optional
'defaults' => [
'from_name' => 'Emily Carter', // required
'from_email'=> 'emily.carter@example.org', // required
'reply_to' => 'emily.carter@example.org', // required
'subject' => 'Welcome to Our Newsletter!', // required
],
// 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' => 'emily.carter@example.org',
'unsubscribe_to' => 'emily.carter@example.org',
],
]);
// and get the response
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Copy a List
Create an exact duplicate of an existing list, including settings but excluding subscribers. A new unique list UID is returned in the response.
### π Copy a List
Duplicate an existing subscriber list using its unique ID.
#### πΉ HTTP Request
```http
POST API-URL/lists/LIST-UNIQUE-ID/copy
```
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | -------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the list to copy. |
#### π Authorization Header
Include your customer API key:
```
X-API-KEY: your-api-key-here
```
#### π» PHP Example
```php
// copy a list
$response = $endpoint->copy('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
The above command returns an object structured like this JSON:
{
"status":"success",
"list_uid": "lm451q7h7j3e2"
}
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"list_uid": "lm451q7h7j3e2"
}
```
{% hint style="warning" %}
π This endpoint creates an exact duplicate of the specified list, including its settings, but not its subscribers.
{% endhint %}
# Delete a List
Permanently delete a specific subscriber list by its unique list UID. This action removes all associated list data and cannot be undone.
### ποΈ Delete a List
Remove a subscriber list permanently using its unique list ID. This action cannot be undone.
#### πΉ HTTP Request
```http
DELETE API-URL/lists/LIST-UNIQUE-ID
```
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ---------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the list to delete. |
#### π Authorization Header
Include your customer API key:
```
X-API-KEY: your-api-key-here
```
#### π» PHP Example
```php
// delete a list
$response = $endpoint->delete('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
{% hint style="danger" %}
Deleting a list is a **permanent action**. All associated data will be lost and cannot be recovered.
{% endhint %}
# Fields
# Get All List Fields
Retrieve all subscriber fields (default and custom) for a specific list using its unique ID. Fields include metadata such as tag, label, type, visibility, and order.
### π§Ύ Get All List Fields
Retrieve all the custom and default fields defined in a specific subscriber list.
#### πΉ HTTP Request
```http
GET API-URL/lists/LIST-UNIQUE-ID/fields
```
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ------------------------------ |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the list. |
#### πΈ Query Parameters
| Parameter | Default | Description |
| ---------- | ------- | ----------------------------------- |
| `page` | 1 | Current page number to retrieve. |
| `per_page` | 10 | Number of items to return per page. |
#### π Authorization Header
Include your customer API key:
```
X-API-KEY: your-api-key-here
```
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getFields('LIST-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"records": [
{
"field_id": "11",
"tag": "EMAIL",
"label": "Email",
"required": "yes",
"help_text": null,
"visibility": "visible",
"sort_order": "0",
"type": {
"name": "Text",
"identifier": "text",
"description": "Text"
}
},
{
"field_id": "12",
"tag": "FNAME",
"label": "First name",
"required": "no",
"help_text": null,
"visibility": "visible",
"sort_order": "1",
"type": {
"name": "Text",
"identifier": "text",
"description": "Text"
}
},
{
"field_id": "13",
"tag": "LNAME",
"label": "Last name",
"required": "no",
"help_text": null,
"visibility": "visible",
"sort_order": "2",
"type": {
"name": "Text",
"identifier": "text",
"description": "Text"
}
}
]
}
}
```
***
# Get One List Field
Fetch the complete configuration of a specific field from a list using its list UID and field ID. Response includes tag, label, visibility, and type metadata.
### π§Ύ Get One List Field
Retrieve detailed information about a specific field within a subscriber list.
#### πΉ HTTP Request
```http
GET API-URL/lists/LIST-UNIQUE-ID/fields/FIELD-ID
```
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ------------------------------------ |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the list. |
| `FIELD-ID` | Yes | Unique identifier of the list field. |
#### π Authorization Header
Include your customer API key:
```
X-API-KEY: your-api-key-here
```
#### π» PHP Example
```php
// GET ONE ITEM
$response = $endpoint->getField('LIST-UNIQUE-ID', 'FIELD-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"record": {
"field_id": "11",
"tag": "FNAME",
"label": "First name",
"required": "no",
"help_text": null,
"visibility": "visible",
"sort_order": "1",
"type": {
"name": "Text",
"identifier": "text",
"description": "Text"
}
}
}
}
```
***
# Create a List Field
Add a custom field to a subscriber list by specifying field type, label, tag, and optional validation or options. Useful for capturing personalized subscriber data.
### β Create a List Field
Add a custom field to a specific subscriber list. Fields can be of various types such as text, dropdown, date, etc., and include validation options like required status, visibility, default values, and custom tags.
#### πΉ HTTP Request
```http
POST API-URL/lists/LIST-UNIQUE-ID/fields
```
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ------------------------------ |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the list. |
#### π Authorization Header
Include your customer API key:
```
X-API-KEY: your-api-key-here
```
#### π POST Parameters
| Parameter | Type | Required | Description |
| --------------- | ------- | ----------- | -------------------------------------------------------- |
| `label` | string | Yes | Field label visible to users. |
| `tag` | string | Yes | Internal tag (e.g., FNAME, EMAIL, etc.). Must be unique. |
| `required` | yes/no | No | Indicates if field is required (`yes` or `no`). |
| `help_text` | string | No | Helper text shown below the field. |
| `default_value` | string | No | Pre-filled value shown in the field. |
| `sort_order` | integer | No | Order in which the field appears. |
| `visibility` | string | No | Set as `visible` or `hidden`. |
| `type` | string | Yes | Type of field (`text`, `dropdown`, `date`, etc.). |
| `description` | string | No | Additional notes or usage info (optional). |
| `options` | array | Conditional | Required only for dropdown, radio, checkbox field types. |
***
#### π» PHP Example
```php
// 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 '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"record": {
"field_id": "111",
"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": "lm451q7h7j3e2",
"display_name": "My list"
},
"options": {
"Value1": "Option1",
"Value2": "Option2"
}
}
}
}
```
***
# Update a List Field
### βοΈ Update a List Field
Update an existing custom field in a subscriber list by providing its list UID and field ID.
#### πΉ HTTP Request
```http
PUT API-URL/lists/LIST-UNIQUE-ID/fields/FIELD-ID
```
#### πΈ URL Segments
| Segment | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------- |
| `LIST-UNIQUE-ID` | string | Yes | Unique identifier of the list. |
| `FIELD-ID` | string | Yes | Unique identifier of the field. |
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π PUT Parameters
| Parameter | Type | Required | Description |
| ------------------- | ------- | -------- | -------------------------------------------------------------- |
| `label` | string | Yes | Field label visible to users. |
| `tag` | string | Yes | Unique tag identifier (e.g., FNAME). |
| `required` | yes/no | Yes | Whether the field is mandatory. |
| `visibility` | string | Yes | Field visibility (`visible` or `hidden`). |
| `default_value` | string | No | Pre-filled value shown in the field. |
| `sort_order` | integer | No | Position order of the field in the form. |
| `help_text` | string | No | Helper text to guide users. |
| `description` | string | No | Description of the field. |
| `min_length` | integer | No | Minimum allowed characters (for text fields). |
| `max_length` | integer | No | Maximum allowed characters (for text fields). |
| `content_rule` | string | No | Rule for text fields (`alpha_ci`, `alphanum_ci`, etc.). |
| `content_regex` | string | No | Custom regex validation for field values. |
| `allowed_scheme` | string | No | Used for URL field types (e.g., https). |
| `whitelist_domains` | string | No | Allowed domains (comma-separated) for URL fields. |
| `blacklist_domains` | string | No | Blocked domains (comma-separated) for URL fields. |
| `max_stars` | integer | No | Used in rating fields. |
| `default_country` | string | No | Country code (e.g., `us`, `ro`, `in`) for country field types. |
***
#### π¦ Options Block *(Optional)*
For field types like `dropdown`, `radio`, or `checkbox`, define selectable options.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------- |
| `name` | string | Yes | Option label shown to the user. |
| `value` | string | Yes | Internal value stored for the option. |
***
#### π» PHP Example
```php
// 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 '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"record": {
"field_id": "111",
"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": "lm451q7h7j3e2",
"display_name": "My list"
},
"options": {
"Value1": "Option1",
"Value2": "Option2"
}
}
}
}
```
***
# Delete a List Field
Permanently delete a custom field from a subscriber list using its list UID and field ID. This is useful for cleaning up unused or outdated fields.
### ποΈ Delete a List Field
Delete a specific custom field from a subscriber list using its list UID and field ID. \
This action is permanent and cannot be undone.
#### πΉ HTTP Request
```http
DELETE API-URL/lists/LIST-UNIQUE-ID/fields/FIELD-ID
```
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ------------------------------------ |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the list. |
| `FIELD-ID` | Yes | Unique identifier of the list field. |
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// Delete FIELD
$response = $endpoint->delete('LIST-UNIQUE-ID', 'FIELD-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
> β οΈ Deleting a field will remove it from all list forms and subscriber records associated with this list.
***
####
# Get All List Field Types
Fetch the full list of supported field types for list customization. This includes standard input fields like text, email, and dropdown, as well as advanced types such as geolocation, ratings, etc.
### π Get All List Field Types
Retrieve all available field types that can be used when creating or updating custom fields in a subscriber list.
#### πΉ HTTP Request
```http
GET API-URL/lists/fields-types
```
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
$response = $endpoint->getListFieldTypes();
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"count": "1",
"total_pages": 1,
"current_page": 1,
"next_page": null,
"prev_page": null,
"records": [
{
"segment_uid": "mj54284tyo084",
"name": "test",
"subscribers_count": 18200
}
]
}
}
```
# Get One List Segment
Retrieve the full details of a single segment, including conditions, match type, subscriber count, and creation timestamp. Ideal for viewing dynamic list filters configured for targeted sending.
### π Get One List Segment
Fetch detailed information about a specific segment within a subscriber list using its unique segment UID.
#### πΉ HTTP Request
```http
GET API-URL/segments/SEGMENT-UNIQUE-ID
```
#### πΈ URL Segments
| Segment | Required | Description |
| ------------------- | -------- | -------------------------------------- |
| `SEGMENT-UNIQUE-ID` | Yes | Unique identifier of the list segment. |
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ONE ITEM
$response = $endpoint->getSegment('SEGMENT-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"record": {
"segment_uid": " da862njvwxc05",
"segment_id": "15",
"name": "My USA Segment",
"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": []
}
}
}
```
***
####
# Get All Subscribers
Retrieve paginated subscribers from a specific segment within a list. This endpoint is helpful for filtering contacts based on segment rules and viewing their status and metadata.
### π₯ Get All Subscribers (From List Segment)
Retrieve all subscribers belonging to a specific segment of a list. This helps you filter and access targeted contacts based on segment criteria.
#### πΉ HTTP Request
```http
GET API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID/subscribers
```
#### πΈ URL Segments
| Segment | Required | Description |
| ------------------- | -------- | --------------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the list. |
| `SEGMENT-UNIQUE-ID` | Yes | Unique identifier of the segment in the list. |
#### πΈ Query Parameters
| Parameter | Default | Description |
| ---------- | ------- | ------------------------------- |
| `page` | 1 | Page number to retrieve. |
| `per_page` | 10 | Number of subscribers per page. |
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
// 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>';
***
#### π¦ Sample JSON Response
```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": "vo155s4b0d0ad",
"EMAIL": "ldefew4@dailymail.co.uk",
"FNAME": "",
"LNAME": "",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2021-02-20 17:26:14"
}
]
}
}
```
***
# Create a List Segment
Create a new list segment using custom field conditions, campaign behavior filters, or both. Ideal for targeting subscribers with highly specific criteria for campaigns or automation workflows.
### β Create a List Segment
Create a new segment for a subscriber list based on field conditions, campaign behavior, or a combination of both.
#### πΉ HTTP Request
```http
POST API-URL/lists/LIST-UNIQUE-ID/segments
```
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ------------------------------ |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the list. |
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π POST Parameters
| Parameter | Type | Required | Description |
| --------- | ----- | -------- | ------------------------------------------------------------------------------------------------- |
| `data` | array | Yes | List segment details including `name`, `operator_match`, `conditions`, and `campaign_conditions`. |
***
#### π¦ General Block *(Required)*
| Parameter | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------- |
| `name` | string | Yes | Name of the list segment. |
| `operator_match` | string | Yes | Match operator: `any` or `all`. |
***
#### π¦ Conditions Block *(Optional)*
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------------------------- |
| `field_id` | string | Yes | ID of the custom field (use Get List Fields API). |
| `operator_id` | string | Yes | Condition operator ID (use condition operators API). |
| `value` | string | Yes | Value to compare against. |
***
#### π¦ Campaign Conditions Block *(Optional)*
| Parameter | Type | Required | Description |
| -------------------------- | ------- | -------- | ---------------------------------------------- |
| `action` | string | Yes | Action to filter by: `click` or `open`. |
| `campaign_id` | integer | Yes | Campaign ID to check behavior against. |
| `time_comparison_operator` | string | Yes | Time operator: `lte`, `lt`, `gte`, `gt`, `eq`. |
| `time_value` | integer | Yes | Time value for comparison. |
| `time_unit` | string | Yes | Time unit: `day`, `month`, or `year`. |
***
#### π» PHP Example
```php
// create a new list segment
$response = $endpoint->create('LIST-UNIQUE-ID', [
// required
'name' => 'API Test List segment', // required
'operator_match' => 'any', // required (any/all)
// optional
'conditions' => [
[
'field_id' => '96', // required
'operator_id' => '3', // required (see condition operators endpoint)
'value' => 'example.com', // required
],
[
'field_id' => '95',
'operator_id' => '4',
'value' => 'keyword',
]
],
'campaign_conditions' => [
[
'action' => 'click', // required (click/open)
'campaign_id' => '11', // required
'time_comparison_operator' => 'lte', // required (lte/lt/gte/gt/eq)
'time_value' => '3', // required
'time_unit' => 'day' // required (day/month/year)
],
[
'action' => 'open',
'campaign_id' => '12',
'time_comparison_operator' => 'gte',
'time_value' => '2',
'time_unit' => 'day'
]
],
]);
// and get the response
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
jsonCopyEdit// JSON RESPONSE
{
"status": "success",
"data": {
"record": {
"segment_uid": "mj54284tyo084",
"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": []
}
}
}
```
***
# Update a List Segment
Update an existing list segment using new field or campaign conditions. Only the submitted conditions will be retained; any existing ones not included will be removed.
### βοΈ Update a List Segment
Modify an existing segment of a subscriber list by replacing its conditions, campaign filters, and other attributes.
#### πΉ HTTP Request
```http
PUT API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID
```
#### πΈ URL Segments
| Segment | Type | Required | Description |
| ------------------- | ------ | -------- | --------------------------------- |
| `LIST-UNIQUE-ID` | string | Yes | Unique identifier of the list. |
| `SEGMENT-UNIQUE-ID` | string | Yes | Unique identifier of the segment. |
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
#### π PUT Parameters
| Parameter | Type | Required | Description |
| --------- | ----- | -------- | ------------------------------------------------------------------------------------------------- |
| `data` | array | Yes | List segment details including `name`, `operator_match`, `conditions`, and `campaign_conditions`. |
#### π¦ General Block *(Required)*
| Parameter | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------- |
| `name` | string | Yes | Name of the list segment. |
| `operator_match` | string | Yes | Match operator: `any` or `all`. |
#### π¦ Conditions Block *(Optional)*
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------------------------- |
| `field_id` | string | Yes | ID of the custom field (use Get List Fields API). |
| `operator_id` | string | Yes | Condition operator ID (use condition operators API). |
| `value` | string | Yes | Value to compare against. |
#### π¦ Campaign Conditions Block *(Optional)*
| Parameter | Type | Required | Description |
| -------------------------- | ------- | -------- | ---------------------------------------------- |
| `action` | string | Yes | Action to filter by: `click` or `open`. |
| `campaign_id` | integer | Yes | Campaign ID to check behavior against. |
| `time_comparison_operator` | string | Yes | Time operator: `lte`, `lt`, `gte`, `gt`, `eq`. |
| `time_value` | integer | Yes | Time value for comparison. |
| `time_unit` | string | Yes | Time unit: `day`, `month`, or `year`. |
#### π» PHP Example
```php
// 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 condition operators endpoint)
'value' => 'domain.com', // required
],
[
'field_id' => '95',
'operator_id' => '4',
'value' => 'keyword',
]
],
'campaign_conditions' => [
[
'action' => 'click',
'campaign_id' => '100',
'time_comparison_operator' => 'lte',
'time_value' => '3',
'time_unit' => 'day'
],
[
'action' => 'open',
'campaign_id' => '99',
'time_comparison_operator' => 'gte',
'time_value' => '3',
'time_unit' => 'month'
]
],
]);
// and get the response
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```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": []
}
}
}
```
# Delete a List Segment
Permanently delete a segment from a subscriber list. This action will remove the segment and its conditions from the list.
### ποΈ Delete a List Segment
Remove a segment from a list using its unique segment and list identifiers. This operation is irreversible.
#### πΉ HTTP Request
```http
DELETE API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID
```
#### πΈ URL Segments
| Segment | Required | Description |
| ------------------- | -------- | --------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the list. |
| `SEGMENT-UNIQUE-ID` | Yes | Unique identifier of the segment. |
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
#### π» PHP Example
```php
// Delete SEGMENT
$response = $endpoint->delete('LIST-UNIQUE-ID', 'SEGMENT-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Get All List Segment Condition Operators
### π Get All List Segment Condition Operators
Fetch all supported condition operators to be used in segment filters such as "is", "contains", or "starts with".
#### πΉ HTTP Request
```http
GET API-URL/lists/segments/condition-operators
```
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getConditionOperators();
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```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" }
]
}
}
```
# Subscribers
# Get All Subscribers
Retrieve all subscribers associated with a specific list. This endpoint supports pagination and returns subscriber details such as email, status, and source.
### π Get All Subscribers (From List)
Fetch all subscribers from a specific list with optional pagination parameters.
***
#### πΉ HTTP Request
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ----------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the subscriber list. |
***
#### π Query Parameters
| Parameter | Default | Description |
| ---------- | ------- | ------------------------------- |
| `page` | 1 | Page number to retrieve. |
| `per_page` | 10 | Number of subscribers per page. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"count": "13",
"total_pages": 2,
"current_page": 1,
"next_page": 2,
"prev_page": null,
"records": [
{
"subscriber_uid": "ab123xyzlmn90",
"EMAIL": "alex.weston@examplemail.com",
"FNAME": "",
"LNAME": "",
"status": "unsubscribed",
"source": "import",
"ip_address": "",
"date_added": "2024-11-15 08:20:10"
},
{
"subscriber_uid": "cd456uvtpqr78",
"EMAIL": "rachel.nguyen@demo.org",
"FNAME": "",
"LNAME": "",
"status": "unsubscribed",
"source": "import",
"ip_address": "",
"date_added": "2024-11-15 08:21:03"
},
{
"subscriber_uid": "ef789lkjghi45",
"EMAIL": "daniel.khan@testnow.io",
"FNAME": "",
"LNAME": "",
"status": "unsubscribed",
"source": "import",
"ip_address": "",
"date_added": "2024-11-15 08:21:22"
},
{
"subscriber_uid": "gh012mnopqw34",
"EMAIL": "li.chen@cloudsync.co",
"FNAME": "",
"LNAME": "",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2024-11-15 08:22:01"
},
{
"subscriber_uid": "ij345rstabc67",
"EMAIL": "john.martin@samplehub.net",
"FNAME": "",
"LNAME": "",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2024-11-15 08:22:15"
},
{
"subscriber_uid": "kl678uvwxzy23",
"EMAIL": "emily.davis@sitepoint.dev",
"FNAME": "",
"LNAME": "",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2024-11-15 08:23:07"
},
{
"subscriber_uid": "mn901defghij1",
"EMAIL": "peter.hall@hostdemo.com",
"FNAME": "",
"LNAME": "",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2024-11-15 08:24:12"
},
{
"subscriber_uid": "op234jklmnop9",
"EMAIL": "sophia.taylor@netgenius.io",
"FNAME": "",
"LNAME": "",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2024-11-15 08:25:05"
},
{
"subscriber_uid": "qr567abcduvw3",
"EMAIL": "ryan.patel@marketauth.com",
"FNAME": "",
"LNAME": "",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2024-11-15 08:26:11"
},
{
"subscriber_uid": "st890efghijk2",
"EMAIL": "isabella.ross@formcast.net",
"FNAME": "",
"LNAME": "",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2024-11-15 08:27:14"
}
]
}
}
```
# Get One Subscriber
Retrieve details of a specific subscriber from a list using their unique subscriber UID and list UID. Useful for viewing the subscriber's status, source, and personal information.
### π Get One Subscriber
Fetch a single subscriber's full data by providing their unique identifier and the list they belong to.
***
#### πΉ HTTP Request
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------------- | -------- | ----------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | List unique ID the subscriber belongs to. |
| `SUBSCRIBER-UNIQUE-ID` | Yes | Unique ID of the subscriber to retrieve. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ONE ITEM
$response = $endpoint->getSubscriber('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"subscriber_uid": "st890efghijk2",
"EMAIL": "isabella.ross@formcast.net",
"FNAME": "",
"LNAME": "",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2024-11-15 08:27:14"
}
}
```
# Search Subscriber by Email
Search and retrieve subscriber information from a specific list using the subscriber's email address. This is helpful for quickly locating a contact without knowing their UID.
### π§ Search Subscriber by Email
Look up a subscriber by their email address within a specified list.
***
#### πΉ HTTP Request
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ----------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the subscriber list. |
***
#### π Query Parameters
| Parameter | Required | Description |
| --------- | -------- | -------------------------------- |
| `email` | Yes | Email address of the subscriber. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// SEARCH BY EMAIL
$response = $endpoint->emailSearch('LIST-UNIQUE-ID', 'john.doe@doe.com');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"subscriber_uid": "st890efghijk2",
"status": "confirmed",
"date_added": "2024-11-15 08:27:14"
}
}
```
# Search by Email in All Lists
Search for a subscriber by email across all lists associated with the authenticated account. This is helpful when you donβt know which list a subscriber belongs to.
### π Search by Email in All Lists
Locate a subscriber across all your lists using their email address.
***
#### πΉ HTTP Request
```http
GET API-URL/lists/subscribers/search-by-email-in-all-lists
```
***
#### π Query Parameters
| Parameter | Required | Description |
| --------- | -------- | -------------------------------- |
| `email` | Yes | Email address of the subscriber. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// SEARCH BY EMAIL IN ALL LISTS
$response = $endpoint->emailSearchAllLists('lena.morris@demomail.io');
// DISPLAY RESPONSE
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"subscriber_uid": "uv445mnqsla78",
"EMAIL": "chloe.bennett@mockmail.net",
"FNAME": "",
"LNAME": "",
"status": "unsubscribed",
"source": "import",
"ip_address": "",
"date_added": "2025-03-28 14:10:45"
}
}
```
# Search Subscribers by Status
Search subscribers by their status (e.g., confirmed, unsubscribed, blacklisted) within a specific list. This is useful for filtering active or inactive contacts.
### π Search Subscribers by Status
Retrieve a list of subscribers from a given list filtered by their current status.
***
#### πΉ HTTP Request
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ----------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the subscriber list. |
***
#### π Query Parameters
| Parameter | Required / Default | Description |
| ---------- | ------------------ | ------------------------------------ |
| `status` | Yes | Status of the subscribers to filter. |
| `page` | 1 | Page number to retrieve. |
| `per_page` | 10 | Items per page to retrieve. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// SEARCH BY STATUS
$response = $endpoint->searchByStatus('LIST-UNIQUE-ID', 'confirmed', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"count": "3",
"total_pages": 1,
"current_page": 1,
"next_page": null,
"prev_page": null,
"records": [
{
"subscriber_uid": "gh238lmnqrp01",
"EMAIL": "nathan.jones@freshmail.co",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "confirmed",
"ip_address": "",
"date_added": "2025-04-12 09:15:34"
},
{
"subscriber_uid": "za904wxyekc72",
"EMAIL": "mia.hernandez@smartlist.io",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "confirmed",
"ip_address": "",
"date_added": "2025-04-12 09:15:20"
},
{
"subscriber_uid": "lp563vutneh43",
"EMAIL": "tom.anderson@wavebox.net",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "confirmed",
"ip_address": "",
"date_added": "2025-04-12 09:14:58"
}
]
}
}
```
# Get Blacklisted Subscribers
Retrieve all subscribers marked as blacklisted within a specific list. Useful for list cleanup, suppression handling, or filtering.
### π« Get Blacklisted Subscribers
Fetch subscribers who have been flagged as blacklisted in a given list.
***
#### πΉ HTTP Request
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ----------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the subscriber list. |
***
#### π Query Parameters
| Parameter | Required / Default | Description |
| ---------- | ------------------ | ------------------------------------- |
| `page` | 1 | Page number to retrieve. |
| `per_page` | 10 | Number of subscribers per page. |
| `status` | blacklisted | Filters only blacklisted subscribers. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// Get only the blacklisted subscribers
$response = $endpoint->getBlacklistedSubscribers('LIST-UNIQUE-ID', 'active', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"count": "3",
"total_pages": 1,
"current_page": 1,
"next_page": null,
"prev_page": null,
"records": [
{
"subscriber_uid": "zx784mntplq65",
"EMAIL": "oliver.woods@inboxsync.net",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "blacklisted",
"ip_address": "",
"date_added": "2025-04-14 11:05:22"
},
{
"subscriber_uid": "qa119bdxefc91",
"EMAIL": "ava.richards@postdrive.co",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "blacklisted",
"ip_address": "",
"date_added": "2025-04-14 11:04:59"
},
{
"subscriber_uid": "wv673xsmnzt43",
"EMAIL": "leo.bradley@mailerbase.org",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "blacklisted",
"ip_address": "",
"date_added": "2025-04-14 11:04:33"
}
]
}
}
```
# Get Confirmed Subscribers
Retrieve all subscribers with the status confirmed from a specified list. Useful for targeting active and verified contacts.
### β Get Confirmed Subscribers
Fetch only confirmed subscribers in a list using list UID and optional pagination parameters.
***
#### πΉ HTTP Request
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ----------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the subscriber list. |
***
#### π Query Parameters
| Parameter | Default | Description |
| ---------- | --------- | ----------------------------------- |
| `page` | 1 | Page number to retrieve. |
| `per_page` | 10 | Number of subscribers per page. |
| `status` | confirmed | Filters only confirmed subscribers. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getConfirmedSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"count": "3",
"total_pages": 1,
"current_page": 1,
"next_page": null,
"prev_page": null,
"records": [
{
"subscriber_uid": "mk582trwqln90",
"EMAIL": "zoe.anderson@newmailhub.com",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "confirmed",
"ip_address": "",
"date_added": "2025-04-16 13:42:10"
},
{
"subscriber_uid": "hf790blsdeq33",
"EMAIL": "liam.morris@uptoday.net",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "confirmed",
"ip_address": "",
"date_added": "2025-04-16 13:42:09"
},
{
"subscriber_uid": "rt205cwnxke88",
"EMAIL": "emma.bryant@fastcomm.io",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "confirmed",
"ip_address": "",
"date_added": "2025-04-16 13:42:07"
}
]
}
}
```
# Get Unconfirmed Subscribers
Retrieve all subscribers with the status unconfirmed from a specific list. Ideal for tracking pending or inactive opt-in subscribers.
### β³ Get Unconfirmed Subscribers
Fetch subscribers who have not yet confirmed their subscription within a given list.
***
#### πΉ HTTP Request
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ----------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the subscriber list. |
***
#### π Query Parameters
| Parameter | Default | Description |
| ---------- | ----------- | ------------------------------------- |
| `page` | 1 | Page number to retrieve. |
| `per_page` | 10 | Number of subscribers per page. |
| `status` | unconfirmed | Filters only unconfirmed subscribers. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getUnconfirmedSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"count": "3",
"total_pages": 1,
"current_page": 1,
"next_page": null,
"prev_page": null,
"records": [
{
"subscriber_uid": "gx382plmbqn21",
"EMAIL": "grace.foster@demo.com",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "unconfirmed",
"ip_address": "",
"date_added": "2025-04-17 10:22:14"
},
{
"subscriber_uid": "rk502uyetwl92",
"EMAIL": "jack.miller@abc.org",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "unconfirmed",
"ip_address": "",
"date_added": "2025-04-17 10:22:10"
},
{
"subscriber_uid": "nv817dxwszo65",
"EMAIL": "lucy.davis@domain.com",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "unconfirmed",
"ip_address": "",
"date_added": "2025-04-17 10:22:06"
}
]
}
}
```
# Get Unsubscribed Subscribers
Retrieve all subscribers with the status unsubscribed from a specific list. Useful for managing opt-outs and analyzing churn.
### π Get Unsubscribed Subscribers
Fetch unsubscribed contacts from a list using list UID and pagination options.
***
#### πΉ HTTP Request
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ----------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | Unique identifier of the subscriber list. |
***
#### π Query Parameters
| Parameter | Default | Description |
| ---------- | ------------ | -------------------------------------- |
| `page` | 1 | Page number to retrieve. |
| `per_page` | 10 | Number of subscribers per page. |
| `status` | unsubscribed | Filters only unsubscribed subscribers. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getUnsubscribedSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"count": "3",
"total_pages": 1,
"current_page": 1,
"next_page": null,
"prev_page": null,
"records": [
{
"subscriber_uid": "ty389plsknq01",
"EMAIL": "amy.jackson@demo.com",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "unsubscribed",
"ip_address": "",
"date_added": "2025-04-17 11:03:22"
},
{
"subscriber_uid": "uk472mqwzle19",
"EMAIL": "bruce.harris@abc.org",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "unsubscribed",
"ip_address": "",
"date_added": "2025-04-17 11:03:18"
},
{
"subscriber_uid": "ze604ndxwcu87",
"EMAIL": "nina.collins@domain.com",
"FNAME": "",
"LNAME": "",
"source": "import",
"status": "unsubscribed",
"ip_address": "",
"date_added": "2025-04-17 11:03:14"
}
]
}
}
```
# Create a Subscriber
Create a new subscriber in a specific list by submitting their email and any additional custom fields. A confirmation email will be triggered based on the list configuration.
### π Create a Subscriber
Add a subscriber to your list with custom field data such as email, first name, and last name.
***
#### πΉ HTTP Request
```http
POST API-URL/lists/LIST-UNIQUE-ID/subscribers
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ----------------------- |
| `LIST-UNIQUE-ID` | Yes | List unique identifier. |
***
#### π€ POST Parameters
| Parameter | Type | Required | Description |
| --------- | ----- | -------- | ----------------------------------------------------------- |
| `data` | array | Yes | Associative array with custom fields. `EMAIL` is mandatory. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// ADD SUBSCRIBER
$response = $endpoint->create('LIST-UNIQUE-ID', [
'EMAIL' => 'linda.smith@demo.com', // the confirmation email will be sent!!! Use valid email address
'FNAME' => 'Linda',
'LNAME' => 'Smith'
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"record": {
"subscriber_uid": "xy918k4tvd731",
"email": "linda.smith@demo.com",
"ip_address": "192.168.25.101",
"source": "api",
"date_added": {
"expression": "NOW()",
"params": {}
}
}
}
}
```
# Create Subscribers in Bulk
Create multiple subscribers at once within a specific list using their email and any optional custom fields. Efficient for large list imports or API-driven syncs.
### π₯ Create Subscribers in Bulk
Add multiple subscribers to a list using a single API request.
***
#### πΉ HTTP Request
```http
POST API-URL/lists/LIST-UNIQUE-ID/subscribers/bulk
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------- | -------- | ----------------------- |
| `LIST-UNIQUE-ID` | Yes | List unique identifier. |
***
#### π€ POST Parameters
| Parameter | Type | Required | Description |
| --------- | ----- | -------- | ------------------------------------------------------------------------ |
| `array` | array | Yes | An array of subscriber arrays, each containing at least the `EMAIL` key. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// ADD SUBSCRIBERS IN BULK
$response = $endpoint->createBulk('LIST-UNIQUE-ID', [
[
'EMAIL' => 'alex.doe@demo.com',
'FNAME' => 'Alex',
'LNAME' => 'Doe'
],
[
'EMAIL' => 'mia.stone@abcmail.com',
'FNAME' => 'Mia',
'LNAME' => 'Stone'
],
[
'EMAIL' => 'noah.lee@dummy.org',
'FNAME' => 'Noah',
'LNAME' => 'Lee'
]
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status":"success",
"data": {
"records": [
{
"data": {
"subscriber_uid": "u1x9zr87yq45a",
"EMAIL": "alex.doe@demo.com",
"FNAME": "Alex",
"LNAME": "Doe",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2025-04-17 14:22:10"
}
},
{
"data": {
"subscriber_uid": "v3m0az21xp77k",
"EMAIL": "mia.stone@abcmail.com",
"FNAME": "Mia",
"LNAME": "Stone",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2025-04-17 14:22:10"
}
},
{
"data": {
"subscriber_uid": "n8k2bd54rw93m",
"EMAIL": "noah.lee@dummy.org",
"FNAME": "Noah",
"LNAME": "Lee",
"status": "confirmed",
"source": "import",
"ip_address": "",
"date_added": "2025-04-17 14:22:10"
}
}
]
}
}
```
# Update a Subscriber
Update the details of an existing subscriber in a specific list by using their unique subscriber ID. Useful for correcting or modifying stored subscriber data.
### βοΈ Update a Subscriber
Modify subscriber details such as email, first name, or last name using their unique identifiers.
***
#### πΉ HTTP Request
```http
PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID
```
***
#### πΈ URL Segments
| Parameter | Required | Description |
| ---------------------- | -------- | ---------------------------- |
| `LIST-UNIQUE-ID` | Yes | List unique identifier |
| `SUBSCRIBER-UNIQUE-ID` | Yes | Subscriber unique identifier |
***
#### π§ PUT Parameters
| Parameter | Type | Required | Description |
| --------- | ----- | -------- | ------------------------------------------------------------- |
| `data` | array | Yes | Array with the custom fields `{name => value}` to be updated. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// UPDATE EXISTING SUBSCRIBER
$response = $endpoint->update('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', [
'EMAIL' => 'alex.renner@demo.com',
'FNAME' => 'Alex',
'LNAME' => 'Renner Updated'
]);
// DISPLAY RESPONSE
echo '';
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"record": {
"subscriber_uid": "a9k7dn56qp91x",
"email": "alex.renner@demo.com",
"ip_address": "212.111.104.10",
"source": "api",
"date_added": "2025-04-17 14:25:42"
}
}
}
```
# Update a Subscriber by Email
Update the details of a subscriber by searching with their email address within a specific list. This method is ideal when the subscriber UID is not known in advance.
### π Update a Subscriber by Email
Search for a subscriber using their email, then update their details with a follow-up PUT request.
***
#### πΉ HTTP Request
**Step 1:** Search by email
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email
```
**Step 2:** Update using subscriber UID
```http
PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------------- | -------- | ----------------------------------- |
| `LIST-UNIQUE-ID` | Yes | List unique identifier |
| `SUBSCRIBER-UNIQUE-ID` | Yes | Subscriber UID returned from search |
***
#### π GET/PUT Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------- |
| `EMAIL` | string | Yes | Email address to search |
| `data` | array | Yes | Array of fields `{name => value}` to update |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// UPDATE EXISTING SUBSCRIBER BY EMAIL
$response = $endpoint->updateByEmail('LIST-UNIQUE-ID', 'emma.woods@demo.org', [
'EMAIL' => 'emma.woods@demo.org',
'FNAME' => 'Emma',
'LNAME' => 'Woods Updated'
]);
// DISPLAY RESPONSE
echo '';
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status":"success",
"data": {
"record": {
"subscriber_uid": "xy823cb90q812",
"email": "emma.woods@demo.org",
"ip_address": "192.168.1.88",
"source": "api",
"date_added": "2025-04-17 14:30:42"
}
}
}
```
# Create or Update a Subscriber
Create a new subscriber or update an existing one in a specific list. This unified endpoint handles both creation and update operations based on the email provided.
### π Create or Update a Subscriber
If the subscriber exists, their details will be updated. If not, a new subscriber will be created.
***
#### πΉ HTTP Request
**Step 1 (Search):**
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email
```
**Step 2 (Update if exists):**
```http
PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID
```
**Step 3 (Create if new):**
```http
POST API-URL/lists/LIST-UNIQUE-ID/subscribers
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------------- | -------- | ---------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | List unique identifier |
| `SUBSCRIBER-UNIQUE-ID` | Yes | Subscriber UID if found via email search |
***
#### π GET/PUT/POST Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------- |
| `EMAIL` | string | Yes | Email address used to identify subscriber |
| `data` | array | Yes | Fields to update or insert `{name => value}` |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// CREATE / UPDATE EXISTING SUBSCRIBER
$response = $endpoint->createUpdate('LIST-UNIQUE-ID', [
'EMAIL' => 'sophia.lane@demo.net',
'FNAME' => 'Sophia',
'LNAME' => 'Lane Updated Again'
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status":"success",
"data": {
"record": {
"subscriber_uid": "zl239xm3df771",
"email": "sophia.lane@demo.net",
"ip_address": "192.168.1.100",
"source": "api",
"date_added": "2025-04-17 14:38:00"
}
}
}
```
# Unsubscribe a Subscriber
Silently unsubscribe a subscriber from a list using their unique subscriber and list identifiers. No notification email is sent.
### π€ Unsubscribe a Subscriber
Remove a subscriber from active communication without sending an email notification.
***
#### πΉ HTTP Request
```http
PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID/unsubscribe
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------------- | -------- | ----------------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | List unique ID to which the subscriber belongs. |
| `SUBSCRIBER-UNIQUE-ID` | Yes | Subscriber unique ID to unsubscribe. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// UNSUBSCRIBE existing subscriber, no email is sent, unsubscribe is silent
$response = $endpoint->unsubscribe('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Unsubscribe a Subscriber by Email
Silently unsubscribe a subscriber from a specific list by using their email address. No email notification will be sent.
### π§ Unsubscribe a Subscriber by Email
Locate a subscriber via email and unsubscribe them from the list silently.
***
#### πΉ HTTP Requests
**Step 1: Search by email**
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email
```
**Step 2: Unsubscribe by subscriber UID**
```http
PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID/unsubscribe
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------------- | -------- | ----------------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | List unique ID to which the subscriber belongs. |
| `SUBSCRIBER-UNIQUE-ID` | Yes | Subscriber unique ID to unsubscribe. |
***
#### π Query Parameters
| Parameter | Required | Description |
| --------- | -------- | -------------------------------- |
| `EMAIL` | Yes | Email address of the subscriber. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// UNSUBSCRIBE existing subscriber by email address, no email is sent, unsubscribe is silent
$response = $endpoint->unsubscribeByEmail('LIST-UNIQUE-ID', 'olivia.king@demo.io');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Unsubscribe Subscriber from All Lists
Unsubscribe a subscriber from all lists using their email address. This is a silent operation β no confirmation email is sent.
### π« Unsubscribe Subscriber from All Lists
Automatically remove a subscriber from every list they are part of, identified via email address.
***
#### πΉ HTTP Request
```http
PUT API-URL/lists/subscribers/unsubscribe-by-email-from-all-lists
```
***
#### π PUT Parameters
| Parameter | Required | Description |
| --------- | -------- | -------------------------------- |
| `EMAIL` | Yes | Email address of the subscriber. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// UNSUBSCRIBE existing subscriber from all lists, no email is sent, unsubscribe is silent
$response = $endpoint->unsubscribeByEmailFromAllLists('olivia.king@demo.io');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Delete One Subscriber
Permanently delete a subscriber from a specific list. This operation is silent β no notification email will be sent.
### ποΈ Delete One Subscriber
Remove a subscriber from a specific list using their unique subscriber and list identifiers.
***
#### πΉ HTTP Request
```http
DELETE API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------------- | -------- | ----------------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | List unique ID to which the subscriber belongs. |
| `SUBSCRIBER-UNIQUE-ID` | Yes | Subscriber unique ID to delete. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// DELETE SUBSCRIBER, no email is sent, delete is silent
$response = $endpoint->delete('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Delete Subscriber by Email
Delete a subscriber from a list using their email address. This is a silent operation β no email will be sent to the user.
### π§Ή Delete Subscriber by Email
Search for the subscriber by email within the list, then delete using their unique ID.
***
#### πΉ HTTP Requests
**Step 1: Search by email**
```http
GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email
```
**Step 2: Delete by UID**
```http
DELETE API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------------- | -------- | ----------------------------------------------- |
| `LIST-UNIQUE-ID` | Yes | List unique ID to which the subscriber belongs. |
| `SUBSCRIBER-UNIQUE-ID` | Yes | Subscriber unique ID to delete. |
***
#### π GET Parameters
| Parameter | Required | Description |
| --------- | -------- | -------------------------------- |
| `email` | Yes | Subscriber email to retrieve UID |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// DELETE SUBSCRIBER by email address, no email is sent, delete is silent
$response = $endpoint->deleteByEmail('LIST-UNIQUE-ID', 'olivia.king@demo.io');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Campaigns
# Get All Campaigns
Retrieve a paginated list of all campaigns associated with your SenderWiz account. You can optionally filter campaigns by a specific list UID.
### π Get All Campaigns
List all campaigns created in your account, with support for pagination and optional filtering.
***
#### πΉ HTTP Request
```http
GET API-URL/campaigns
```
***
#### π Query Parameters
| Parameter | Default | Description |
| ---------- | ------- | ---------------------------------------------------------------- |
| `page` | 1 | Current page number to retrieve. |
| `per_page` | 10 | Number of campaigns per page. |
| `list_uid` | | Optional. Return only campaigns belonging to the specified list. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getCampaigns($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo "
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"record": {
"campaign_uid": "ab781xqmvk274",
"campaign_id": "201",
"name": "Demo API Campaign #1",
"type": "regular",
"from_name": "Alice Walker",
"from_email": "alice.walker@demo.com",
"to_name": "[EMAIL]",
"reply_to": "alice.walker@demo.com",
"subject": "π Testing Campaigns via API Integration",
"status": "sent",
"date_added": "2025-04-16T14:55:00",
"send_at": "2025-04-16T14:57:00",
"list": {
"list_uid": "xy5934demo938",
"name": "Demo List 2025",
"subscribers_count": 0
},
"segment": [],
"group": []
}
}
}
```
# Create a Campaign
Create a new campaign using the API. This can be a regular or autoresponder campaign, and allows advanced customization like segments, template content, scheduling, and optional configurations.
### π Create a Campaign
Use this endpoint to create and schedule a campaign using a template and optional features like URL tracking and stats reporting.
***
#### πΉ HTTP Request
```http
POST API-URL/campaigns
```
***
#### π POST Parameters
| Parameter | Type | Required | Description |
| ---------- | ----- | -------- | ---------------------------------- |
| `campaign` | array | Yes | Array containing campaign details. |
***
#### π¦ Campaign Block
| Parameter | Type | Required | Description |
| ------------ | -------- | -------- | ------------------------------------------------------------------ |
| name | string | Yes | Name of the campaign. |
| type | string | No | Type: `regular` or `autoresponder`. Default: `regular`. |
| from\_name | string | Yes | Sender name. |
| from\_email | string | Yes | Sender email. |
| subject | string | Yes | Subject of the email. |
| reply\_to | string | Yes | Email address for replies. |
| send\_at | datetime | Yes | When to send the campaign (Y-m-d H:i:s). Uses customer's timezone. |
| list\_uid | string | Yes | Target list unique ID. |
| segment\_uid | string | No | Optional segment to target a specific audience. |
| options | array | No | Optional settings like tracking, feeds, stats email, etc. |
| template | array | Yes | Content or reference to the email template. |
***
#### ποΈ Template Block
| Parameter | Type | Required | Description |
| ----------------- | -------- | -------- | ----------------------------------------------- |
| archive | filePath | Yes\* | Path to zip archive if using archived template. |
| template\_uid | string | Yes\* | Reference to saved template UID. |
| content | string | Yes\* | HTML content of the campaign. |
| inline\_css | yes/no | Yes | Enable/disable inline CSS. |
| plain\_text | string | No | Manually set plain text version or leave null. |
| auto\_plain\_text | yes/no | Yes | Automatically generate plain text. |
\*At least one of `archive`, `template_uid`, or `content` must be provided.
***
#### βοΈ Options Block
| Parameter | Type | Description |
| --------------------------------- | ------- | --------------------------------------------------- |
| url\_tracking | yes/no | Enable/disable URL tracking. |
| json\_feed | yes/no | Enable/disable JSON feed. |
| xml\_feed | yes/no | Enable/disable XML feed. |
| plain\_text\_email | yes/no | Send email as plain text. |
| email\_stats | string | Optional: Send campaign stats to this email. |
| autoresponder\_event | string | Values: AFTER-SUBSCRIBE, AFTER-CAMPAIGN-OPEN. |
| autoresponder\_time\_unit | string | Time unit: minute, hour, day, etc. |
| autoresponder\_time\_value | integer | Interval value for autoresponder. |
| autoresponder\_open\_campaign\_id | integer | Campaign ID to link with for open-event responders. |
| cronjob | string | Cron syntax for recurring campaigns. |
| cronjob\_enabled | integer | 1 (enabled) or 0 (disabled). |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// CREATE CAMPAIGN
$response = $endpoint->create([
'name' => 'April Campaign via API', // required
'type' => 'regular', // optional: regular or autoresponder
'from_name' => 'Sophie Turner', // required
'from_email' => 'sophie.turner@demo.com', // required
'subject' => 'Hello from the April Campaign (via API)', // required
'reply_to' => 'sophie.turner@demo.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 below:
//'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,
],
// 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 '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"campaign_uid": "xy5934demo938"
}
```
# Update a Campaign
Update an existing campaign's configuration, content, or metadata using its unique campaign UID.
### βοΈ Update a Campaign
Modify an existing campaign by providing updated fields. Only the fields included in the request will be changed.
***
#### πΉ HTTP Request
```http
PUT API-URL/campaigns/CAMPAIGN-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| -------------------- | -------- | ----------------------------- |
| `CAMPAIGN-UNIQUE-ID` | Yes | Campaign unique ID to update. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π₯ PUT Parameters
Same as the parameters used in **Create a Campaign**, but all fields are optional during update.
***
#### π» PHP Example
```php
// UPDATE CAMPAIGN
$response = $endpoint->update('CAMPAIGN-XYZ123456', [
'name' => 'April Promo Campaign - Updated', // optional at update
'from_name' => 'Ethan Clark', // optional at update
'from_email' => 'ethan.clark@demo.org', // optional at update
'subject' => 'Updated Campaign: Explore Whatβs New!', // optional at update
'reply_to' => 'ethan.clark@demo.org', // optional at update
'send_at' => date('Y-m-d H:i:s', strtotime('+1 hour')), //optional at update, this will use the timezone which customer selected
'list_uid' => 'LIST-UID-456XYZ', // optional at update
'segment_uid' => 'SEGMENT-UID-123ABC', // optional, only to narrow down
// optional block, defaults are shown
'options' => [
'url_tracking' => 'no', // yes | no
'json_feed' => 'no', // yes | no
'xml_feed' => 'no', // yes | no
'plain_text_email' => 'yes', // yes | no
'email_stats' => null, // a valid email address where we should send the stats after campaign done
],
// optional block at update, archive or template_uid or content => required.
'template' => [
//'archive' => file_get_contents(__DIR__ . '/template-example.zip'),
//'template_uid' => 'TEMPLATE-UNIQUE-ID',
'content' => file_get_contents(__DIR__ . '/template-example.html'),
'inline_css' => 'no', // yes | no
'plain_text' => null, // leave empty to auto generate
'auto_plain_text' => 'yes', // yes | no
],
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Copy a Campaign
Duplicate an existing campaign using its unique campaign UID. This is useful when reusing previous campaign settings and templates.
### π Copy a Campaign
Create a new campaign by copying the configuration and content of an existing one.
***
#### πΉ HTTP Request
```http
POST API-URL/campaigns/CAMPAIGN-UNIQUE-ID/copy
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| -------------------- | -------- | -------------------------------- |
| `CAMPAIGN-UNIQUE-ID` | Yes | Campaign unique ID to duplicate. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// Copy CAMPAIGN
$response = $endpoint->copy('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"campaign_uid": "ab781xqmvk274"
}
```
# Pause/Unpause a Campaig
Toggle the status of a campaign between "paused" and "sending" using its unique campaign UID.
### βΈοΈ Pause/Unpause a Campaign
Use this endpoint to pause a currently sending campaign or to resume a paused campaign.
***
#### πΉ HTTP Request
```http
PUT API-URL/campaigns/CAMPAIGN-UNIQUE-ID/pause-unpause
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| -------------------- | -------- | ------------------------------------ |
| `CAMPAIGN-UNIQUE-ID` | Yes | Campaign unique ID to pause/unpause. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// Pause/Unpause CAMPAIGN
$response = $endpoint->pauseUnpause('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"campaign": {
"status": "sending"
}
}
```
# Mark a Campaign as SENT
Forcefully mark a campaign as "sent" using its unique identifier. This is useful for testing, debugging, or manually closing campaigns that are stuck.
### β Mark a Campaign as SENT
Change the status of a campaign to `sent`, even if it has not completed its delivery cycle.
***
#### πΉ HTTP Request
```http
PUT API-URL/campaigns/CAMPAIGN-UNIQUE-ID/mark-sent
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| -------------------- | -------- | ----------------------------------- |
| `CAMPAIGN-UNIQUE-ID` | Yes | Campaign unique ID to mark as sent. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// Mark CAMPAIGN as sent
$response = $endpoint->markSent('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"campaign": {
"status": "sent"
}
}
```
# Delete a Campaign
Permanently delete a campaign using its unique campaign UID. This action is irreversible.
### ποΈ Delete a Campaign
Remove a campaign from your account by referencing its unique ID.
***
#### πΉ HTTP Request
```http
DELETE API-URL/campaigns/CAMPAIGN-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| -------------------- | -------- | ----------------------------- |
| `CAMPAIGN-UNIQUE-ID` | Yes | Campaign unique ID to delete. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// Delete CAMPAIGN
$response = $endpoint->delete('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Get Stats of a Campaign
Retrieve in-depth performance metrics and delivery statistics for a specific campaign using its unique identifier.
### π Get Stats of a Campaign
Use this endpoint to fetch delivery, open, click, bounce, and unsubscribe data for any campaign.
***
#### πΉ HTTP Request
```http
GET API-URL/campaigns/CAMPAIGN-UNIQUE-ID/stats
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| -------------------- | -------- | ----------------------------------------- |
| `CAMPAIGN-UNIQUE-ID` | Yes | Campaign unique ID to retrieve stats for. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET STATS
$response = $endpoint->getStats('CAMPAIGN-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"campaign_status": "sent",
"subscribers_count": 500,
"processed_count": 498,
"delivery_success_count": 485,
"delivery_success_rate": 97,
"delivery_error_count": 13,
"delivery_error_rate": 3,
"opens_count": 320,
"opens_rate": 66,
"unique_opens_count": 275,
"unique_opens_rate": 57,
"clicks_count": 145,
"clicks_rate": 30,
"unique_clicks_count": 112,
"unique_clicks_rate": 23,
"unsubscribes_count": 8,
"unsubscribes_rate": 1.6,
"complaints_count": 2,
"complaints_rate": 0.4,
"bounces_count": 13,
"bounces_rate": 2.6,
"hard_bounces_count": 7,
"hard_bounces_rate": 1.4,
"soft_bounces_count": 4,
"soft_bounces_rate": 0.8,
"internal_bounces_count": 2,
"internal_bounces_rate": 0.4
}
}
```
# Reports
# Track Subscriber Click for Campaign
Simulate or log a subscriber's click on a tracked campaign link using the unique campaign, subscriber, and URL hash values.
### π Track Subscriber Click for Campaign
Register a tracked click event by a subscriber for a specific URL inside a campaign.
***
#### πΉ HTTP Request
```http
GET API-URL/campaigns/CAMPAIGN-UNIQUE-ID/track-url/SUBSCRIBER-UNIQUE-ID/URL-HASH
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------------- | -------- | ------------------------------------------- |
| `CAMPAIGN-UNIQUE-ID` | Yes | Unique ID of the campaign. |
| `SUBSCRIBER-UNIQUE-ID` | Yes | Unique ID of the subscriber. |
| `URL-HASH` | Yes | Hashed version of the tracked campaign URL. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// Track subscriber click for campaign
$response = $endpoint->trackUrl('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', 'URL-HASH');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {}
}
```
# Track Subscriber Open
Track when a subscriber opens a campaign email using their unique subscriber and campaign identifiers.
### ποΈ Track Subscriber Open
Use this endpoint to register an open event for a campaign by a specific subscriber.
***
#### πΉ HTTP Request
```http
GET API-URL/campaigns/CAMPAIGN-UNIQUE-ID/track-opening/SUBSCRIBER-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------------- | -------- | ---------------------------- |
| `CAMPAIGN-UNIQUE-ID` | Yes | Unique ID of the campaign. |
| `SUBSCRIBER-UNIQUE-ID` | Yes | Unique ID of the subscriber. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// Track subscriber open for campaign
$response = $endpoint->trackOpening('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {}
}
```
# Track Subscriber Unsubscribe
Log an unsubscribe action from a subscriber for a specific campaign, optionally capturing metadata such as IP address, user agent, and reason.
### π« Track Subscriber Unsubscribe
Use this endpoint to register an unsubscribe event for a specific subscriber from a campaign.
***
#### πΉ HTTP Request
```http
POST API-URL/campaigns/CAMPAIGN-UNIQUE-ID/track-unsubscribe/SUBSCRIBER-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ---------------------- | -------- | ---------------------------- |
| `CAMPAIGN-UNIQUE-ID` | Yes | Unique ID of the campaign. |
| `SUBSCRIBER-UNIQUE-ID` | Yes | Unique ID of the subscriber. |
***
#### π POST Parameters
| Parameter | Required | Description |
| ------------ | -------- | ------------------------------------ |
| `ip_address` | No | IP address of the subscriber. |
| `user_agent` | No | User agent string of the subscriber. |
| `reason` | No | Optional reason for unsubscribing. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// Track subscriber unsubscribe for campaign
$response = $endpoint->trackUnsubscribe('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', [
'ip_address' => '231.134.23.13',
'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 '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {}
}
```
# Bounces
# Get All Bounces
Retrieve all bounce reports (hard and soft) related to a specific campaign using its unique identifier.
### π¬ Get All Bounces
Use this endpoint to fetch the list of bounced emails for a particular campaign.
***
#### πΉ HTTP Request
```http
GET API-URL/campaigns/CAMPAIGN-UNIQUE-ID/bounces
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| -------------------- | -------- | ------------------------------------------- |
| `CAMPAIGN-UNIQUE-ID` | Yes | Campaign unique ID to retrieve the bounces. |
***
#### π§Ύ Query Parameters
| Parameter | Default | Description |
| ---------- | ------- | --------------------------- |
| `page` | 1 | Current page to retrieve. |
| `per_page` | 10 | Items per page to retrieve. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getBounces('CAMPAIGN-UNIQUE-ID', $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo "
";
print_r($response->body);
echo "
";
```
***
#### π¦ Sample JSON Response
```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": "mn382plq98zr7",
"email": "invalid.user@demo.com"
}
}
]
}
}
```
# Create a Campaign Bounce
Manually register a bounce event for a subscriber within a campaign. Useful for syncing external bounce events into SenderWiz.
### π Create a Campaign Bounce
Use this endpoint to create and log a bounce for a subscriber under a specific campaign.
***
#### πΉ HTTP Request
```http
POST API-URL/campaigns/CAMPAIGN-UNIQUE-ID/bounces
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| -------------------- | -------- | -------------------------------------------- |
| `CAMPAIGN-UNIQUE-ID` | Yes | Campaign unique ID to create the bounce for. |
***
#### π POST Parameters
| Parameter | Required | Description |
| ---------------- | -------- | ------------------------------------------- |
| `message` | Yes | Bounce reason (max 250 characters). |
| `bounce_type` | Yes | Bounce type: `hard`, `soft`, or `internal`. |
| `subscriber_uid` | Yes | Subscriber's unique ID (13 characters). |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// 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 '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"record": {
"message": "550 5.1.1 The email account that you tried to reach does not exist.",
"processed": "no",
"bounce_type": "hard",
"subscriber": {
"subscriber_uid": "lk572qwmzv410",
"email": "bounced.user@demo.com"
}
}
}
}
```
# Countries
# Get All Countries
Retrieve the list of all countries supported by SenderWiz, including country name, code, and ID.
### π Get All Countries
Use this endpoint to fetch paginated country data used for company or contact address fields.
***
#### πΉ HTTP Request
```http
GET API-URL/countries
```
***
#### π§Ύ Query Parameters
| Parameter | Default | Description |
| ---------- | ------- | --------------------------- |
| `page` | 1 | Current page to retrieve. |
| `per_page` | 10 | Items per page to retrieve. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getCountries($pageNumber = 23, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"count": "240",
"total_pages": 24,
"current_page": 23,
"next_page": 24,
"prev_page": 22,
"records": [
{
"country_id": "101",
"name": "Tuvalu",
"code": "TV"
},
{
"country_id": "102",
"name": "Uganda",
"code": "UG"
},
{
"country_id": "103",
"name": "Ukraine",
"code": "UA"
},
{
"country_id": "104",
"name": "United Arab Emirates",
"code": "AE"
},
{
"country_id": "105",
"name": "United Kingdom",
"code": "GB"
},
{
"country_id": "106",
"name": "United States",
"code": "US"
},
{
"country_id": "107",
"name": "United States Minor Outlying Islands",
"code": "UM"
},
{
"country_id": "108",
"name": "Uruguay",
"code": "UY"
},
{
"country_id": "109",
"name": "Uzbekistan",
"code": "UZ"
},
{
"country_id": "110",
"name": "Vanuatu",
"code": "VU"
}
]
}
}
```
# Get All Zones of a Country
Retrieve all zones (states/provinces) associated with a specific country by its country ID.
### πΊοΈ Get All Zones of a Country
Use this endpoint to fetch paginated state or region data for a selected country.
***
#### πΉ HTTP Request
```http
GET API-URL/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. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// get country zones
$response = $endpoint->getZones(COUNTRY-ID, $pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"count": "65",
"total_pages": 7,
"current_page": 1,
"next_page": 2,
"prev_page": null,
"records": [
{
"zone_id": "5101",
"name": "Alabama",
"code": "AL"
},
{
"zone_id": "5102",
"name": "Alaska",
"code": "AK"
},
{
"zone_id": "5103",
"name": "American Samoa",
"code": "AS"
},
{
"zone_id": "5104",
"name": "Arizona",
"code": "AZ"
},
{
"zone_id": "5105",
"name": "Arkansas",
"code": "AR"
},
{
"zone_id": "5106",
"name": "Armed Forces Africa",
"code": "AF"
},
{
"zone_id": "5107",
"name": "Armed Forces Americas",
"code": "AA"
},
{
"zone_id": "5108",
"name": "Armed Forces Canada",
"code": "AC"
},
{
"zone_id": "5109",
"name": "Armed Forces Europe",
"code": "AE"
},
{
"zone_id": "5110",
"name": "Armed Forces Middle East",
"code": "AM"
}
]
}
}
```
# Templates
# Get All Templates
Retrieve a paginated list of email templates available for the authenticated customer account.
### πΌοΈ Get All Templates
Use this endpoint to get all templates created or imported under your SenderWiz account.
***
#### πΉ HTTP Request
```http
GET API-URL/templates
```
***
#### π§Ύ Query Parameters
| Parameter | Default | Description |
| ---------- | ------- | --------------------------- |
| `page` | 1 | Current page to retrieve. |
| `per_page` | 10 | Items per page to retrieve. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getTemplates($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"records": [
{
"template_uid": "tpl9847xyz123",
"name": "summer_campaign_template",
"screenshot": "https:\/\/demo.com\/frontend\/assets\/gallery\/tpl9847xyz123\/img_preview.png"
}
]
}
}
```
# Get One Template
Retrieve the full details of a specific email template using its unique template ID.
### π§Ύ Get One Template
Use this endpoint to fetch the name, HTML content, and screenshot of a selected template.
***
#### πΉ HTTP Request
```http
GET API-URL/templates/TEMPLATE-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| -------------------- | -------- | ------------------------------------- |
| `TEMPLATE-UNIQUE-ID` | Yes | Template unique ID which to retrieve. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ONE ITEM
$response = $endpoint->getTemplate('TEMPLATE-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"record": {
"name": "summer_promo_template",
"content": "HTML content...",
"screenshot": "https:\/\/demo.com\/frontend\/assets\/gallery\/tpl9847xyz123\/img_preview.png"
}
}
}
```
# Search Templates
Search email templates based on specific filter criteria like template name.
### π Search Templates
Use this endpoint to search templates by name or other attributes. This is useful for dynamically retrieving matching templates.
***
#### πΉ HTTP Request
```http
GET API-URL/templates
```
***
#### π§Ύ Query Parameters
| Parameter | Type | Default | Required | Description |
| ---------- | ----- | ------- | -------- | ----------------------------------------------------------------- |
| `page` | int | 1 | No | Current page to retrieve. |
| `per_page` | int | 10 | No | Number of items per page. |
| `filters` | array | β | Yes | Indexed array of template attributes to filter by (e.g., `name`). |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// Search ALL ITEMS
$response = $endpoint->searchTemplates($pageNumber = 1, $perPage = 10, [
'name' => 'summer_offer_template'
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"records": [
{
"name": "summer_offer_template",
"content": "HTML content...",
"screenshot": "https:\/\/demo.com\/frontend\/assets\/gallery\/tpl9847xyz123\/img_preview.png"
}
]
}
}
```
# Create a Template
Create a new email template in SenderWiz using HTML content or a zip archive.
### π Create a Template
This endpoint allows you to upload and save a new template either via direct HTML content or using a ZIP archive.
***
#### πΉ HTTP Request
```http
POST API-URL/templates
```
***
#### π POST Parameters
| Parameter | Type | Required | Description |
| ---------- | ----- | -------- | ----------------------------------------- |
| `template` | array | Yes | An array containing the template details. |
**π¦ Data Block (Required)**
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | --------------------------------------------------------- |
| `name` | string | Yes | The template name. |
| `content` | string | Yes | HTML content of the template. |
| `archive` | string | No | File content of a ZIP archive (alternative to `content`). |
| `inline_css` | Yes/No | No | Enable or disable inline CSS (`yes` or `no`). |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// 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 '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"template_uid": "tpl9847xyz123"
}
```
# Update a Template
Update an existing email template in SenderWiz by its unique identifier.
### π Update a Template
This endpoint allows you to modify the details of a template such as its name, content, or CSS preferences.
***
#### πΉ HTTP Request
```http
PUT API-URL/templates/TEMPLATE-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| -------------------- | -------- | ------------------------------------ |
| `TEMPLATE-UNIQUE-ID` | Yes | Unique ID of the template to update. |
***
#### π PUT Parameters
| Parameter | Type | Required | Description |
| --------- | ----- | -------- | ---------------------------------------- |
| `data` | array | Yes | Array with the updated template details. |
> Refer to the **Create Template** documentation for full parameter definitions.
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// 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 '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Delete a Template
Permanently delete a specific email template using its unique identifier in SenderWiz.
### ποΈ Delete a Template
Use this endpoint to remove a template from your account. This action is irreversible.
***
#### πΉ HTTP Request
```http
DELETE API-URL/templates/TEMPLATE-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| -------------------- | -------- | ------------------------------------ |
| `TEMPLATE-UNIQUE-ID` | Yes | Unique ID of the template to delete. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// DELETE TEMPLATE
$response = $endpoint->delete('TEMPLATE-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Subaccounts
# Get All Subaccounts
Retrieve all subaccounts (team members) associated with the current customer account.
### π₯ Get All Subaccounts
This endpoint fetches a list of all active subaccounts (children) under the current logged-in customer.
***
#### πΉ HTTP Request
```http
GET API-URL/children
```
#### π Authorization Header
```http
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```
// GET ALL SUBACCOUNTS
$response = $endpoint->getChildren();
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```
{
"status": "success",
"data": {
"count": 2,
"records": [
{
"child_uid": "6827da91aa67",
"first_name": "Alice",
"last_name": "Brown",
"email": "alice.brown@demo.com",
"status": "active",
"timezone": "Asia/Kolkata",
"date_added": "2025-05-10 13:22:10"
},
{
"child_uid": "5c9adf212ff3",
"first_name": "David",
"last_name": "Morris",
"email": "david.morris@demo.com",
"status": "inactive",
"timezone": "Europe/London",
"date_added": "2025-03-21 10:08:47"
}
]
}
}
```
***
#### π§Ύ Notes
* Only subaccounts under the authenticated customer account will be listed.
* Pagination parameters (if supported) can be added for extended results.
# Create a Subaccount
Create a new subaccount (child user) under the current customer account.
### π Create a Subaccount
Add a new subaccount to your SenderWiz customer account with first name, last name, email, password, and timezone.
***
#### πΉ HTTP Request
```http
POST API-URL/children
```
***
#### π€ POST Parameters
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------- |
| `first_name` | string | β | First name of the subaccount |
| `last_name` | string | β | Last name of the subaccount |
| `email` | string | β | Email address of the subaccount |
| `password` | string | β | Login password |
| `timezone` | string | β | Timezone (e.g., Asia/Kolkata) |
***
#### π Authorization Headers
```http
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// CREATE A SUBACCOUNT
$response = $endpoint->createChild([
'first_name' => 'Sophia',
'last_name' => 'Green',
'email' => 'sophia.green@demo.com',
'password' => 'StrongPass#2025',
'timezone' => 'America/New_York'
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"child_uid": "8e12c91b4a2d1",
"first_name": "Sophia",
"last_name": "Green",
"email": "sophia.green@demo.com",
"timezone": "America/New_York",
"status": "active",
"date_added": "2025-06-04 14:22:11"
}
}
```
***
#### π§Ύ Notes
* Use the returned `child_uid` to perform updates, deletions, or permission management.
* Ensure the email used is unique across the account.
# Update a Subaccount
Update details of an existing subaccount (child user) under your SenderWiz customer account.
### βοΈ Update a Subaccount
Modify the first name, last name, email, password, or timezone of a specific subaccount.
***
#### πΉ HTTP Request
```http
PUT API-URL/children/CHILD-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ----------------- | -------- | ----------------------------------- |
| `CHILD-UNIQUE-ID` | β | Unique identifier of the subaccount |
***
#### π£ POST Parameters
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------- |
| `first_name` | string | No | Updated first name |
| `last_name` | string | No | Updated last name |
| `email` | string | No | Updated email address |
| `password` | string | No | New login password |
| `timezone` | string | No | Updated timezone (e.g., Asia/Kolkata) |
***
#### π Authorization Header
```http
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// UPDATE SUBACCOUNT
$response = $endpoint->updateChild('8e12c91b4a2d1', [
'first_name' => 'Sophia-Updated',
'last_name' => 'Green',
'email' => 'sophia.updated@demo.com',
'timezone' => 'Asia/Kolkata'
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"child_uid": "8e12c91b4a2d1",
"first_name": "Sophia-Updated",
"last_name": "Green",
"email": "sophia.updated@demo.com",
"timezone": "Asia/Kolkata",
"status": "active",
"last_updated": "2025-06-04 15:10:22"
}
}
```
***
#### π Notes
* You only need to pass the fields you want to update.
* Ensure the email address is unique within your account.
# Delete a Subaccount
Delete a subaccount (child user) from your SenderWiz customer account.
### β Delete a Subaccount
Remove a specific subaccount from your SenderWiz customer panel using its unique child UID.
***
#### πΉ HTTP Request
```http
DELETE API-URL/children/CHILD-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ----------------- | -------- | --------------------------------------- |
| `CHILD-UNIQUE-ID` | β | The unique identifier of the subaccount |
***
#### π Authorization Header
```http
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// DELETE A SUBACCOUNT
$response = $endpoint->deleteChild('8e12c91b4a2d1');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"message": "Subaccount successfully deleted."
}
```
***
#### π§Ύ Notes
* Deleting a subaccount is permanent.
* Make sure the `CHILD-UNIQUE-ID` is valid before attempting the delete operation.
# Get Subaccount Permissions
Retrieve the current permission settings of a subaccount (child user) under your SenderWiz account.
### π Get Subaccount Permissions
Fetch the permission configuration for a specific subaccount using their unique ID (CHILD-UNIQUE-ID).
***
#### πΉ HTTP Request
```http
GET API-URL/children/CHILD-UNIQUE-ID/permissions
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ----------------- | -------- | ----------------------------------- |
| `CHILD-UNIQUE-ID` | β | Unique identifier of the subaccount |
***
#### π Authorization Header
```http
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET SUBACCOUNT PERMISSIONS
$response = $endpoint->getChildPermissions('8e12c91b4a2d1');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"permissions": [
{
"type": "menu",
"key": "lists",
"value": "yes"
},
{
"type": "action",
"key": "campaign_send",
"value": "no"
}
]
}
}
```
***
#### π§Ύ Notes
* You can manage subaccount access levels through permissions.
* Combine this with the update permissions endpoint to enable/disable features for team members.
# Update Subaccount Permissions
Update the permission settings for a specific subaccount using its unique child UID.
### βοΈ Update Subaccount Permissions
Modify specific permissions for a given subaccount (child user) in your SenderWiz customer account.
***
#### πΉ HTTP Request
```http
PUT API-URL/children/CHILD-UNIQUE-ID/permissions
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ----------------- | -------- | ------------------------------- |
| `CHILD-UNIQUE-ID` | β | Unique identifier of subaccount |
***
#### π€ PUT Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------------- |
| `type` | string | β | Permission group/type (e.g., campaigns) |
| `key` | string | β | Specific permission name (e.g., create) |
| `value` | string | β | Allowed values: `yes` or `no` |
***
#### π Authorization Header
```http
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// UPDATE SUBACCOUNT PERMISSIONS
$response = $endpoint->updateChildPermissions('8e12c91b4a2d1', [
[
'type' => 'campaigns',
'key' => 'create',
'value' => 'yes'
],
[
'type' => 'lists',
'key' => 'delete',
'value' => 'no'
]
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"message": "Permissions updated successfully."
}
```
***
#### π§Ύ Notes
* Use the exact `CHILD-UNIQUE-ID` from the subaccount creation or listing response.
* You can update multiple permissions by passing multiple objects in the payload array.
# Transactional Emails
# Get All Transactional Emails
Retrieve a paginated list of all transactional emails sent via the SenderWiz platform.
### π¬ Get All Transactional Emails
Use this endpoint to fetch all transactional email records with pagination support.
***
#### πΉ HTTP Request
```http
GET API-URL/transactional-emails
```
***
#### π§Ύ Query Parameters
| Parameter | Default | Description |
| ---------- | ------- | --------------------------- |
| `page` | 1 | Current page to retrieve. |
| `per_page` | 10 | Items per page to retrieve. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// GET ALL ITEMS
$response = $endpoint->getEmails($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"record": {
"email_uid": "em847xqvnlz45",
"customer_id": "102",
"to_email": "lucas.smith@demo.com",
"to_name": "Lucas Smith",
"from_email": "emma.james@demo.com",
"from_name": "Emma James",
"reply_to_email": "emma.james@demo.com",
"reply_to_name": "Emma James",
"subject": "π§ Important Update β Please Review",
"body": "Hello Lucas, please find the attached document for your review.<\/strong>",
"plain_text": "Hello Lucas, please find the attached document for your review.",
"priority": "5",
"retries": "0",
"max_retries": "3",
"send_at": "2025-04-17 11:15:00",
"fallback_system_servers": "no",
"status": "sent",
"date_added": "2025-04-17 11:15:05",
"last_updated": "2025-04-17 11:16:10",
"attachments": [
{
"type": "application/pdf",
"name": "monthly-report-april.pdf",
"data": "Email attachment content blob"
}
]
}
}
}
```
# Create a Transactional Email
Create and schedule a new transactional email, with optional attachments and plain text content.
### βοΈ Create a Transactional Email
Use this endpoint to send or schedule a transactional email to a recipient.
***
#### πΉ HTTP Request
```http
POST API-URL/transactional-emails
```
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π₯ POST Parameters
| Parameter | Type | Required | Description |
| --------- | ----- | -------- | ------------------------ |
| `email` | array | Yes | Array with email details |
**π Data Block - Required**
| Field | Type | Required | Description |
| ----------- | -------- | -------- | ------------------------------------ |
| `to_name` | string | Yes | Recipient name |
| `to_email` | string | Yes | Recipient email |
| `from_name` | string | Yes | Sender name |
| `subject` | string | Yes | Email subject |
| `body` | string | Yes | Email body (HTML) |
| `send_at` | datetime | Yes | UTC datetime in `Y-m-d H:i:s` format |
**π Optional Fields**
| Field | Type | Description |
| ---------------- | ------ | -------------------------------------------- |
| `plain_text` | string | Auto generated if missing |
| `from_email` | string | Sender email address |
| `reply_to_name` | string | Reply-to name |
| `reply_to_email` | string | Reply-to email address |
| `attachments` | array | List of attachments (`type`, `name`, `data`) |
***
#### π» PHP Example
```php
// CREATE A NEW EMAIL
$rand = rand();
$response = $endpoint->create([
'to_name' => 'Lucas Demo',
'to_email' => 'lucas@demo.net',
'from_name' => 'Evelyn Sender',
'from_email' => 'evelyn@demo.net',
'reply_to_name' => 'Evelyn Sender',
'reply_to_email' => 'evelyn@demo.net',
'subject' => 'This is a sample email subject',
'body' => 'Hello from SenderWiz!',
'plain_text' => 'Hello from SenderWiz!',
'send_at' => date('Y-m-d H:i:s'),
'attachments' => [
[
'type' => 'image/png',
'name' => basename(__DIR__ . '/files/image.png'),
'data' => base64_encode((string)file_get_contents(__DIR__ . '/files/image.png')),
],
[
'type' => 'application/pdf',
'name' => basename(__DIR__ . '/files/document.pdf'),
'data' => base64_encode((string)file_get_contents(__DIR__ . '/files/document.pdf')),
],
]
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"email_uid": "te456j4jqn1a1"
}
```
# Delete a Transactional Email
Remove a specific transactional email from the system using its unique email identifier.
### ποΈ Delete a Transactional Email
Delete a transactional email with the given unique identifier. This action is permanent and cannot be undone.
***
#### πΉ HTTP Request
```http
DELETE API-URL/transactional-emails/EMAIL-UNIQUE-ID
```
***
#### πΈ URL Segments
| Segment | Required | Description |
| ----------------- | -------- | -------------------------- |
| `EMAIL-UNIQUE-ID` | Yes | Email unique ID to delete. |
***
#### π Authorization Header
```
X-API-KEY: your-api-key-here
```
***
#### π» PHP Example
```php
// delete email
$response = $endpoint->delete('EMAIL-UNIQUE-ID');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success"
}
```
# Customer
# Get All Customers
Fetch a paginated list of all customers from your SenderWiz account using the Admin API with optional filters.
### π Get All Customers
Retrieve a list of all customers created in your SenderWiz account using the Admin API. This endpoint returns paginated results.
#### πΉ HTTP Request
```html
GET ADMIN-API-URL/customers
```
#### πΈ Query Parameters (Optional)
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------------------- |
| `page` | int | No | The result page number (default is 1) |
| `per_page` | int | No | Number of records per page (default is 10, max is 50) |
| `search` | string | No | Search by name or email |
| `status` | string | No | Search by status 'active' or 'inactive' |
#### π Authorization Header
Include your Admin API key:
`X-ADMIN-API-KEY: your-admin-api-key-here`
#### π» PHP Example
```php
// GET ALL CUSTOMERS
$response = $endpoint->getCustomers([
'page' => 1,
'per_page' => 20,
'search' => 'Smith'
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"current_page": 1,
"per_page": 20,
"total": 48,
"data": [
{
"customer_uid": "ab382plq98zr7",
"first_name": "Emma",
"last_name": "Smith",
"email": "emma.waters@demo.com",
"status": "active",
"group": "Pro-Group"
},
{
"customer_uid": "h3k92mrb7s8qt",
"first_name": "Liam",
"last_name": "Smith",
"email": "liam.smith@demo.com",
"status": "inactive",
"group": "Basic-Group"
}
]
}
```
# Get One Customer
Retrieve a single customerβs full profile details using their unique UID via SenderWiz Admin API.
### π€ Get One Customer
Fetch the full profile details of a single customer from your SenderWiz account using the Admin API.
#### πΉ HTTP Request
```html
GET ADMIN-API-URL/customers/CUSTOMER-UID
```
#### πΈ URL Segments
| Segment | Type | Required | Description |
| -------------- | ------ | -------- | --------------------------------- |
| `CUSTOMER-UID` | string | Yes | Unique identifier of the customer |
#### π Authorization Header
Include your Admin API key:
`X-ADMIN-API-KEY: your-admin-api-key-here`
#### π» PHP Example
```php
// GET ONE CUSTOMER
$response = $endpoint->getCustomer('ab382plq98zr7');
// DISPLAY RESPONSE
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"customer_uid": "hr359dca6g62b"
}
```
# Delete a Customer
Delete an existing customer profile using SenderWiz Admin API safely by first setting their status to 'Pending delete'.
### ποΈ Delete a Customer
Remove a customer and all associated data permanently.\
This operation set the customer's status is set to `Pending delete`. Cleanup job removes data permanently in next scheduled run.
#### πΉ HTTP Request
```html
DELETE ADMIN-API-URL/customers/CUSTOMER-UID
```
#### πΈ URL Segments
| Segment | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------------------- |
| `CUSTOMER-UID` | string | Yes | Unique identifier of the customer to update |
#### π Authorization Header
`X-ADMIN-API-KEY: your-admin-api-key-here`
#### β οΈ Important Note
The delete operation changes the customer's status to **Pending Delete**, allowing the daily cleanup process to permanently remove the customer profile along with all associated data.
#### π» PHP Example
```php
// DELETE CUSTOMER
$response = $endpoint->delete('ab382plq98zr7');
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"message": "Customer scheduled for deletion."
}
```
# Get All Customer Groups
Retrieve a complete list of all customer groups available in your SenderWiz account.
### π Get All Customer Groups
Fetch and display the full list of customer groups created in your SenderWiz account, including group names, customer counts, and timestamps.
***
#### πΉ HTTP Request
```http
GET ADMIN-API-URL/groups
```
***
#### πΈ Query Parameters
| Parameter | Default | Description |
| --------- | ------- | --------------------------- |
| page | 1 | Current page to retrieve. |
| per\_page | 10 | Number of records per page. |
***
#### π Authorization Header
```bash
X-ADMIN-API-KEY: your-admin-api-key-here
```
***
#### π» PHP Example
```php
// GET ALL CUSTOMER GROUPS
$response = $endpoint->getCustomerGroups($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"count": "7",
"total_pages": 1,
"current_page": 1,
"next_page": null,
"prev_page": null,
"records": [
{
"group_uid": "bg8432hl4n8pq",
"name": "Business-Group",
"customers_count": 0,
"date_added": "2023-12-17 20:21:00",
"last_updated": "2025-02-24 09:33:00"
},
{
"group_uid": "eg2187hj7kw37",
"name": "Enterprise Group",
"customers_count": 0,
"date_added": "2024-12-16 11:17:00",
"last_updated": "2025-02-24 09:31:00"
},
{
"group_uid": "ex4598pf4q2op",
"name": "Expired",
"customers_count": 4,
"date_added": "2023-11-05 18:59:00",
"last_updated": "2024-12-05 15:03:00"
},
{
"group_uid": "pg4372rk0os39",
"name": "Pro-Group",
"customers_count": 2,
"date_added": "2022-11-21 22:37:00",
"last_updated": "2025-04-09 22:36:00"
},
{
"group_uid": "sg3128vw4lt75",
"name": "Starter-Group",
"customers_count": 0,
"date_added": "2022-09-20 23:18:00",
"last_updated": "2025-02-24 09:32:00"
},
{
"group_uid": "tr7483as5mp29",
"name": "Trial",
"customers_count": 0,
"date_added": "2023-10-20 14:57:00",
"last_updated": "2025-02-01 23:42:00"
},
{
"group_uid": "ug2398pk7ad84",
"name": "Unlimited-Group",
"customers_count": 1,
"date_added": "2022-11-21 22:38:00",
"last_updated": "2025-03-30 11:07:00"
}
]
}
}
```
***
# Get All Timezones
Retrieve a complete list of supported timezones for your SenderWiz platform using Admin API access.
### π Get All Timezones
Fetch and display the full list of timezones available in your SenderWiz installation via Admin API.
***
#### πΉ HTTP Request
```http
GET ADMIN-API-URL/timezones
```
***
#### πΈ Query Parameters
| Parameter | Default | Description |
| --------- | ------- | --------------------------- |
| page | 1 | Current page to retrieve. |
| per\_page | 10 | Number of records per page. |
***
#### π Authorization Header
```bash
X-ADMIN-KEY: your-admin-api-key-here
```
***
#### π» PHP Example
```php
// GET ALL TIMEZONES
$response = $adminEndpoint->getTimezones($pageNumber = 1, $perPage = 10);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"data": {
"count": "10",
"total_pages": 1,
"current_page": 1,
"next_page": null,
"prev_page": null,
"records": [
{
"timezone_id": "1",
"name": "(GMT-11:00) Pacific/Midway"
},
{
"timezone_id": "2",
"name": "(GMT-11:00) Pacific/Niue"
},
{
"timezone_id": "3",
"name": "(GMT-11:00) Pacific/Pago_Pago"
},
{
"timezone_id": "4",
"name": "(GMT-10:00) Pacific/Honolulu"
},
{
"timezone_id": "5",
"name": "(GMT-10:00) Pacific/Rarotonga"
},
{
"timezone_id": "6",
"name": "(GMT-10:00) Pacific/Tahiti"
},
{
"timezone_id": "7",
"name": "(GMT-09:30) Pacific/Marquesas"
},
{
"timezone_id": "8",
"name": "(GMT-09:00) America/Adak"
},
{
"timezone_id": "9",
"name": "(GMT-09:00) Pacific/Gambier"
},
{
"timezone_id": "10",
"name": "(GMT-08:00) America/Anchorage"
}
]
}
}
```
***
# Get Delivery Report
Retrieve detailed email delivery reports with advanced filters, timezone support, and export in JSON or CSV from your SenderWiz account.
### π Get Delivery Report
Retrieve a list of all campaign delivery logs and status events for each email sent from your SenderWiz account. This endpoint supports advanced filtering, timezone-aware date filters, pagination, and both JSON and CSV output formats.
***
#### **πΉ HTTP Request**
```http
GET ADMIN-API-URL/deliveryreport
```
***
#### **πΈ Query Parameters (Optional)**
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `customer_id` | int | No | Filter by customer ID |
| `campaign_id` | int | No | Filter by campaign ID |
| `date_from` | string | No | Filter by sent date (start). Format: `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` with optional timezone |
| `date_to` | string | No | Filter by sent date (end). Format: `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` with optional timezone |
| `opened` | 0/1 | No | Filter by open status: 1=open, 0=not opened |
| `clicked` | 0/1 | No | Filter by click status: 1=clicked, 0=not clicked |
| `bounced` | 0/1 | No | Filter by bounce status: 1=bounced, 0=not bounced |
| `unsubscribed` | 0/1 | No | Filter by unsubscribe status: 1=unsubscribed, 0=not unsubscribed |
| `complaint` | 0/1 | No | Filter by complaint status: 1=complaint, 0=no complaint |
| `server_name` | string | No | Filter by delivery server name (exact match) |
| `format` | string | No | `json` or `csv` (default is json) |
| `page` | int | No | Results page number (default 1) |
| `page_size` | int | No | Records per page (default 100, max 500) |
***
#### **π Authorization Header**
Include your Admin API key:
```
X-ADMIN-API-KEY: your-admin-api-key-here
```
***
#### **Timezone-Aware Date Filtering**
You can provide timezones in your `date_from` and `date_to` using ISO 8601 offset notation:
* Use `+05:30` for IST (India), `-06:00` for US Central, `+00:00` for UTC, etc.
* **Example:** `2025-07-30 10:00:00+05:30`
* If no timezone is specified, UTC is assumed.
**URL Encoding:**
* For `+`, use `%2B` in URLs: `2025-07-01%2B05:30`
* For `-`, you can use as is: `2025-07-01-06:00`
**Returned data times** (like `delivery_date_time`, `open_time`) will also be shown in the requested timezone.
**πΈ Quick Examples**
* **All output in UTC-6:00 (US Central, no daylight savings):**
```html
GET ADMIN-API-URL/deliveryreport?date_from=2025-01-01-06:00&date_to=2025-06-01-06:00
```
* **All output in UTC+5:30 (India):**
```html
GET ADMIN-API-URL/deliveryreport?date_from=2025-01-01%2B05:30&date_to=2025-06-01%2B05:30
```
***
#### How Date Filters Work
* **Only a date?**
* `2025-07-01` β treated as `2025-07-01 00:00:00`
* `2025-07-31` β treated as `2025-07-31 00:00:00` (midnight of that day, so doesn't include the full day)
* **To include the whole last day:**
* Use `date_to=2025-07-31 23:59:59`
* **All times are either UTC or your requested timezone (see above).**
***
**π» PHP Example**
```php
// GET DELIVERY REPORT
$response = $endpoint->get('deliveryreport', [
'customer_id' => 1,
'date_from' => '2025-07-01',
'date_to' => '2025-07-31',
'opened' => 1,
'clicked' => 1,
'page' => 1,
'page_size' => 100
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
**π¦ Sample Dummy JSON Response**
```json
[
{
"customer_email": "john.doe@example.com",
"campaign": "Summer Sale 2025",
"list": "All Customers",
"subscriber_email": "alice.smith@email.com",
"delivery_server": "SMTP-US-East",
"delivery_status": "success",
"delivery_date_time": "2025-07-12 09:30:25", // Will be in the requested timezone
"open": "Yes",
"open_time": "2025-07-12 09:31:10",
"click": "Yes",
"click_time": "2025-07-12 09:32:00",
"bounce": "No",
"bounce_type": null,
"bounce_time": null,
"unsubscribe": "No",
"unsubscribe_time": null,
"complaint": "No",
"complaint_time": null
},
{
"customer_email": "john.doe@example.com",
"campaign": "Summer Sale 2025",
"list": "All Customers",
"subscriber_email": "bob.jones@email.com",
"delivery_server": "SMTP-US-East",
"delivery_status": "success",
"delivery_date_time": "2025-07-12 09:30:25",
"open": "No",
"open_time": null,
"click": "No",
"click_time": null,
"bounce": "Yes",
"bounce_type": "hard",
"bounce_time": "2025-07-12 09:31:15",
"unsubscribe": "No",
"unsubscribe_time": null,
"complaint": "No",
"complaint_time": null
}
]
```
***
**π Sample CSV Response**
Add `&format=csv` to your request URL.\
The response will be a CSV file with the same columns as above.
***
#### π **Request Examples**
Replace `ADMIN-API-URL` with your actual API endpoint URL.
#### 1. All activity for customer 1 (full date range, JSON)
```
GET ADMIN-API-URL/deliveryreport?customer_id=1
```
#### 2. All activity for customer 1 between July 1β31, 2025 (JSON)
```
GET ADMIN-API-URL/deliveryreport?customer_id=1&date_from=2025-07-01&date_to=2025-07-31
```
#### 3. Only opened emails for customer 1 in July 2025 (JSON)
```
GET ADMIN-API-URL/deliveryreport?customer_id=1&date_from=2025-07-01&date_to=2025-07-31&opened=1
```
#### 4. Only NOT opened emails for customer 1 in July 2025 (JSON)
```
GET ADMIN-API-URL/deliveryreport?customer_id=1&date_from=2025-07-01&date_to=2025-07-31&opened=0
```
#### 5. Opened AND clicked emails for customer 1 in July 2025 (JSON)
```
GET ADMIN-API-URL/deliveryreport?customer_id=1&date_from=2025-07-01&date_to=2025-07-31&opened=1&clicked=1
```
#### 6. Opened but NOT clicked emails for customer 1 in July 2025 (JSON)
```
GET ADMIN-API-URL/deliveryreport?customer_id=1&date_from=2025-07-01&date_to=2025-07-31&opened=1&clicked=0
```
#### 7. Neither opened NOR clicked emails for customer 1 in July 2025 (JSON)
```
GET ADMIN-API-URL/deliveryreport?customer_id=1&date_from=2025-07-01&date_to=2025-07-31&opened=0&clicked=0
```
#### 8. Only unsubscribed for customer 1 in July 2025 (JSON)
```
GET ADMIN-API-URL/deliveryreport?customer_id=1&date_from=2025-07-01&date_to=2025-07-31&unsubscribed=1
```
#### 9. Only bounced emails for customer 1 in July 2025 (JSON)
```
GET ADMIN-API-URL/deliveryreport?customer_id=1&date_from=2025-07-01&date_to=2025-07-31&bounced=1
```
#### 10. All activity for customer 1 in July 2025 as CSV
```
GET ADMIN-API-URL/deliveryreport?customer_id=1&date_from=2025-07-01&date_to=2025-07-31&format=csv
```
#### 11. Only NOT opened emails for customer 1 in July 2025 as CSV
```
GET ADMIN-API-URL/deliveryreport?customer_id=1&date_from=2025-07-01&date_to=2025-07-31&opened=0&format=csv
```
#### 12. Opened AND clicked emails for customer 1 in July 2025 as CSV
```
GET ADMIN-API-URL/deliveryreport?customer_id=1&date_from=2025-07-01&date_to=2025-07-31&opened=1&clicked=1&format=csv
```
***
#### **Tip:**
* Use the `X-ADMIN-API-KEY` header for all requests.
* You can combine filters like `opened`, `clicked`, `bounced`, `unsubscribed`, `complaint`, or `server_name`.
* All date/time fields are returned in the timezone requested in your filter. If no timezone is given, UTC is used.
# Customer Login via Token
Enable seamless customer login to SenderWiz using a secure admin tokenβno password required, session valid for 10 minutes. Acts like SSO integration.
### π Customer Login via Token (Admin Key)
Allow your own application to securely log in customers to SenderWiz without requiring manual entry of email and password on the SenderWiz login screen. This acts as a single sign-on (SSO)-like experience using admin-level API authentication.
With this endpoint, admins can generate a login token for any of their customers and redirect them directly to SenderWiz, bypassing the login form.
***
#### πΉ HTTP Request
```http
POST ADMIN-API-URL/admin-generate-token
```
***
#### πΈ Authorization Header
Include your customer API key:
```
X-ADMIN-API-KEY: your-admin-api-key-here
```
***
πΈ Query Parameters
| Parameter | Required | Description |
| --------- | -------- | ----------------------------- |
| `email` | Yes | Email address of the customer |
#### π Authorization Header
Include your customer API key:
```
X-ADMIN-API-KEY: your-admin-api-key-here
```
***
**π» PHP Example**
```php
// GENERATE LOGIN TOKEN FOR CUSTOMER
$response = $endpoint->generateToken([
'email' => 'emma.waters@demo.com',
]);
// DISPLAY RESPONSE
echo '
';
print_r($response->body);
echo '
';
```
***
#### π¦ Sample JSON Response
```json
{
"status": "success",
"login_url": "https://demo.com/customer/guest/api-login/05530c1914f50d2e07f6318f61c636d7"
}
```
***
#### π Redirection
Once the login URL is generated, you can automatically redirect your customer to that URL. The token is valid for 10 minutes. After expiration, the customer will be redirected back to your own login system.
***
#### β Benefits
* Seamless login experience for your customers
* Works like Single Sign-On (SSO)
* Secure and time-bound access (10-minute token validity)
* No password entry required
***
#### β οΈ Note
* Ensure token-based login URLs are used immediately.
* Do not share login URLs externally. Use them only within secure application redirections.
# Customer Task via Admin API
Allow Admins to perform customer-level tasks securely using their Admin API key and a customer ID header.
### π Perform Customer Tasks via Admin API Key
Allow admins to perform any customer-level operation by reusing existing customer endpoints. This is done securely using `X-ADMIN-API-KEY` and `X-CUSTOMER-ID` headers.
***
#### πΉ How It Works
Admin can call **any customer API endpoint** like `API-URL/lists`, `API-URL/contacts`, etc., by sending:
* `X-ADMIN-API-KEY` in the header (for admin authentication)
* `X-CUSTOMER-ID` in the header (to impersonate customer context)
The system detects these headers, validates them, and routes the request through existing customer workflows.
***
### π₯ Example: Get Contact Lists as Admin
#### πΉ HTTP Request
`GET API-URL/lists`
#### π Authorization Header
| Header | Type | Required | Description |
| ----------------- | ------ | -------- | --------------------------- |
| `X-ADMIN-API-KEY` | string | Yes | Valid admin API key |
| `X-CUSTOMER-ID` | string | Yes | Customer UID to impersonate |
#### π» PHP Example
```php
$response = Http::withHeaders([
'X-ADMIN-API-KEY' => 'admin-abc-123',
'X-CUSTOMER-ID' => 'ab382plq98zr7'
])->get('API-URL/lists');
print_r($response->json());
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"lists": [
{
"uid": "xj35478ymfe15",
"name": "Newsletter Subscribers"
},
{
"uid": "lm451q7h7j3e2",
"name": "Event Attendees"
}
]
}
```
***
### π Example: Create a List as Admin
#### πΉ HTTP Request
`POST API-URL/lists`
#### π Authorization Header
| Header | Type | Required | Description |
| ----------------- | ------ | -------- | --------------------------- |
| `X-ADMIN-API-KEY` | string | Yes | Valid admin API key |
| `X-CUSTOMER-ID` | string | Yes | Customer UID to impersonate |
#### πΈ POST Parameters
| Field | Type | Required | Description |
| ------------- | ------ | -------- | ------------------ |
| `name` | string | Yes | Name of the list |
| `description` | string | No | Optional list note |
#### π» PHP Example
```php
$response = Http::withHeaders([
'X-ADMIN-API-KEY' => 'admin-abc-123',
'X-CUSTOMER-ID' => 'ab382plq98zr7'
])->post('API-URL/lists', [
'name' => 'New Customers List',
'description' => 'Imported from CRM'
]);
print_r($response->json());
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"message": "List created successfully",
"list": {
"uid": "ls35478ymfe15",
"name": "New Customers List"
}
}
```
***
### π Notes
* Works for all HTTP verbs: `GET`, `POST`, `PUT`, `DELETE`
* Admin access is controlled strictly via headers
* Always log admin impersonation actions
***
# Customer API
# Get a Customer API Key
Retrieve a customerβs active API keys securely via Admin API. Useful for integration, validation, or access control tasks.
### π₯ Get Customer API Key(s)
Fetch all active API keys associated with a specific customer account using your Admin-level access.
**πΉ HTTP Request**
`GET ADMIN-API-URL/customers/CUSTOMER-UID/api-keys`
**πΈ URL Segments**
| Segment | Type | Required | Description |
| -------------- | ------ | -------- | --------------------------------- |
| `CUSTOMER-UID` | string | Yes | Unique identifier of the customer |
**π» PHP Example**
```php
$response = $endpoint->getApiKeys('ab382plq98zr7');
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"api_keys": [
{
"key_id": "46",
"key": "96228972e37f2b08f281d2a4db88a54fb3885350",
"name": "My site",
"description": "This key is used on my site",
"ip_whitelist": ["123.123.123.123", "111.111.111.111"],
"ip_blacklist": ["231.231.231.231", "222.222.222.222"],
"created_at": "2025-04-19 10:32:00"
},
{
"key_id": "47",
"key": "67bb0a3627efd012458c3206db8cef86c95c0d47",
"name": "Backend integration",
"description": "API key for backend connection",
"ip_whitelist": [],
"ip_blacklist": [],
"created_at": "2025-04-15 16:20:44"
}
]
}
```
# Create a Customer API Key
Create a customer API key using Admin API. Add IP rules, name, and description for secure integration across systems and platforms.
### π οΈ Create a Customer API Key
Generate a new API key for a customer using your Admin API key. Customize the key with optional IP whitelisting, naming, and descriptions.
#### πΉ HTTP Request
`POST ADMIN-API-URL/customers/CUSTOMER-UID/api-keys`
#### πΈ URL Segments
| Segment | Type | Required | Description |
| -------------- | ------ | -------- | --------------------------------- |
| `CUSTOMER-UID` | string | Yes | Unique identifier of the customer |
#### π Authorization Header
`X-ADMIN-API-KEY: your-admin-api-key-here`
#### π» PHP Example
```php
$response = $endpoint->createApiKey('ab382plq98zr7', [
'name' => 'My site',
'description' => 'This key is used on my site',
'ip_whitelist' => ['123.123.123.123', '111.111.111.111'],
'ip_blacklist' => ['231.231.231.231', '222.222.222.222']
]);
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"api_key": {
"key_id": "31",
"key": "67bb0a3627efd012458c3206db8cef86c95c0d47",
"name": "My site",
"description": "This key is used on my site",
"ip_whitelist": ["123.123.123.123", "111.111.111.111"],
"ip_blacklist": ["231.231.231.231", "222.222.222.222"],
"created_at": "2025-04-19 11:00:00"
}
}
```
# Update a Customer API Key
Update a customer's API key with a new name, description, or IP rules using the Admin API for improved security and management.
### βοΈ Update a Customer API Key
Update an existing API key's details like name, description, or IP restrictions using the Admin API for better access management.
#### πΉ HTTP Request
`PUT ADMIN-API-URL/customers/CUSTOMER-UID/api-keys/KEY-ID`
#### πΈ URL Segments
| Segment | Type | Required | Description |
| -------------- | ------ | -------- | --------------------------------- |
| `CUSTOMER-UID` | string | Yes | Unique identifier of the customer |
| `KEY-ID` | string | Yes | ID of the API key to update |
#### π Authorization Header
`X-ADMIN-API-KEY: your-admin-api-key-here`
#### π Fields Available for Update
| Field | Type | Required | Description |
| ------------- | --------- | -------- | --------------------------------------- |
| name | string | No | A label or title for the API key |
| description | string | No | Short description for internal use |
| ip\_whitelist | string\[] | No | List of IPs allowed to use this key |
| ip\_blacklist | string\[] | No | List of IPs blocked from using this key |
#### π» PHP Example
```php
$response = $endpoint->updateApiKey('ab382plq98zr7', '45', [
'name' => 'Updated Key',
'description' => 'Updated description for the key',
'ip_whitelist' => ['101.101.101.101'],
'ip_blacklist' => ['202.202.202.202']
]);
echo '
';
print_r($response->body);
echo '
';
```
#### π¦ Sample JSON Response
```json
{
"status": "success",
"message": "API key updated successfully.",
"api_key": {
"key_id": "45",
"key": "67bb0a36xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"name": "Updated Key",
"description": "Updated description for the key",
"ip_whitelist": ["101.101.101.101"],
"ip_blacklist": ["202.202.202.202"],
"updated_at": "2025-04-19 14:20:00"
}
}
```
# Delete a Customer API Key
Safely remove a customer API key via Admin API and revoke access tied to the deleted key. Supports fine-grained access control.
### ποΈ Delete a Customer API Key
Remove a specific customer API key using the Admin API key. This revokes access associated with the deleted key.
#### πΉ HTTP Request
`DELETE ADMIN-API-URL/customers/CUSTOMER-UID/api-keys/KEY-ID`
#### πΈ URL Segments
| Segment | Type | Required | Description |
| -------------- | ------ | -------- | --------------------------------- |
| `CUSTOMER-UID` | string | Yes | Unique identifier of the customer |
| `KEY-ID` | string | Yes | ID of the API key to be deleted |
#### π Authorization Header
`X-ADMIN-API-KEY: your-admin-api-key-here`
#### π Fields Available for Update
| Field | Type | Required | Description |
| ------------- | --------- | -------- | --------------------------------------- |
| name | string | No | A label or title for the API key |
| description | string | No | Short description for internal use |
| ip\_whitelist | string\[] | No | List of IPs allowed to use this key |
| ip\_blacklist | string\[] | No | List of IPs blocked from using this key |
#### β JSON Request Payload Example
```json
{
"name": "My site",
"description": "This key is used on my site",
"ip_whitelist": ["123.123.123.123", "111.111.111.111"],
"ip_blacklist": ["231.231.231.231", "222.222.222.222"]
}
```
#### π» PHP Example
```php
$response = $endpoint->deleteApiKey('ab382plq98zr7', '45');
echo '