Introduction

The Acelle Mail API (version 1.0) is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The first step is to install your Acelle web application. We have Installation & Getting started guidelines (for cPanel or unmanaged server/VPS) included in the guideline/ folder of the software package you download from CodeCanyon. It is in HTML format, you can just go to the guideline/ folder, double click on the index.html file to open it on your browser.

The Acelle Mail API may differ as we release new versions over time. Log in to your installation of Acelle to see the particular version, API base URI and authentication key.

Visit our product page for latest updates.

Not a developer?

Acelle Mail is made for users without software programming experience. Just follow the installation & getting started guideline included in our software package to install the web application to your hosting server which can be either a VPS (Virtual Private Server) or a managed server's environment with a control panel like cPanel or Plesk.

Custom development & integration

Acelle is pre-designed for rebranding, customization and integration. Our Acelle SDK is written in PHP, however, you can use any programming language to interact with Acelle's RESTful API.

Client libraries
PHP
cURL
 
composer require acelle/sdk-php
sudo apt install curl
sdk-phpsdk-curl

Authentication

Acelle Mail API employs simple Token Authentication which is also referred to as Bearer Authentication. That is, every Acelle user account has an authentication token. The token must be sent in either the Authorization HTTP header or in the query string URL when making requests to protected resources:

Authorization: Bearer <token>

Or as a query string parameter in the request URL

https://acelle.com/api/v1?api_token=YOUR_API_TOKEN

Important: using an authentication token in the Bearer header is highly recommended over in a query string, and it should only be used over HTTPS (SSL).

Find your API Token

You will need to first login to your Acelle account to find the API TOKEN which is available in the My Profile > API & Authentication dashboard

API endpoint

Acelle is a self-hosted web platform and every instance of Acelle has its own API endpoint. Remember to replace acelle.com with your own installation's hostname when executing an API call.

One-click Login

Sometimes it is useful to have a one-click login URL so that users can login to their Acelle Mail's dashboard without having to enter their username or password. User can just click on a one-time login link to get logged in to the web UI. It is especially helpful when you use Acelle with another application and you do not want to have your users enter their username or password twice. And you do not want to employ a complicated authentication mechanism like SSO (Single Sign-on). Then using a one-click login URL comes in handy.

It is as simple as making a POST request to /login-token resource to obtain a one-time login token as well as the one-time login URL

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
Authentication
1 2 3 
curl -X POST -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/login-token \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->loginToken();
RESPONSE
{
    "token": "8vunPVPUDBMGYOEk9",
    "url": "http://example.com/login/token/8vunPVPUDBMGYOEk9"
}

Lists

Mail Lists, also referred to as Audience, are at the center of email marketing management systems.
It is designed to help you collect and manage subscribed, non-subscribed, and unsubscribed contacts.
Acelle's List API allows you to create, edit your mail lists as well as manage your lists' contacts.

View Lists

Retrieve all your mail lists as well as every mail list's details like name, description, etc. You can also find every list's UID which is used as reference key for a particular list

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
VIEW LISTS
1 2 3 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/lists \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->list()->all();
RESPONSE
[
    {
        "id": 1,
        "uid": "5fade5c93e42a",
        "name": "My Awesome Campaign",
        "default_subject": "An Awesome Subject",
        "from_email": "support@acelle.com",
        "from_name": "Customer Support",
        "status": null,
        "created_at": "2021-11-13 01:47:53",
        "updated_at": "2021-12-04 07:29:24"
    },
    {
        "id": 2,
        "uid": "5fc9e55410e10",
        "name": "List 1",
        ...
    },
    ...
]

Create List

A mail list is a collection of email addresses used by an individual or an organization to send marketing material to multiple recipients. You can have different lists of different group of contacts

Make a POST request to the /list resource along with your desired list details to create. On success, a unique List UID key is returned for the newly created list, which is used as a reference key for interacting with it.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
name string
List's name
from_email email
Default From email address
from_name string
Default From name
default_subject string
Default email subject
contact[company] string
Company name
contact[state] string
State / Province / Region
contact[address_1] string
Address 1
contact[address_2] string
Address 2
contact[city] string
City
contact[zip] string
Zip / Postal code
contact[phone] string
Phone
contact[country_id] string
Country id
contact[email] email
Email
contact[url] url
Home page
subscribe_confirmation string
Send subscription confirmation email (Double Opt-In)
send_welcome_email string
Send a final welcome email
unsubscribe_notification string
Send unsubscribe notification to subscribers
send_welcome_email string
Send a final welcome email
CREATE NEW LIST
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 
curl -X POST -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/lists \
    -d api_token=*|token_string|* \
    -d name=List+1 \
    -d from_email=admin@abccorp.org \
    -d from_name=ABC+Corp. \
    -d default_subject=Welcome+to+ABC+Corp. \
    -d contact[company]=ABC+Corp. \
    -d contact[state]=Armagh \
    -d contact[address_1]=14+Tottenham+Court+Road+London+England \
    -d contact[address_2]=44-46+Morningside+Road+Edinburgh+Scotland \
    -d contact[city]=Noname \
    -d contact[zip]=80000 \
    -d contact[phone]=123+456+889 \
    -d contact[country_id]=1 \
    -d contact[email]=info@abccorp.org \
    -d contact[url]=http://www.abccorp.org \
    -d subscribe_confirmation=1 \
    -d send_welcome_email=1 \
    -d unsubscribe_notification=1
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->list()->create([
    'name' => 'List+1',
    'from_email' => 'admin@abccorp.org',
    'from_name' => 'ABC+Corp.',
    'default_subject' => 'Welcome+to+ABC+Corp.',
    'contact' => [
        'company' => 'ABC+Corp.',
        'state' => 'Armagh',
        'address_1' => '14+Tottenham+Court+Road+London+England',
        'address_2' => '44-46+Morningside+Road+Edinburgh+Scotland',
        'city' => 'Noname',
        'zip' => '80000',
        'phone' => '123+456+889',
        'country_id' => '1',
        'email' => 'info@abccorp.org',
        'url' => 'http://www.abccorp.org',                
    ],
    'subscribe_confirmation' => '1',
    'send_welcome_email' => '1',
    'unsubscribe_notification' => '1',
]);
RESPONSE
{
    "status": 1,
    "message": "List was successfully created",
    "list_uid": "5fc9e55410e10"
}

Get List Details

Get detailed information of a List identified by a given UID passed to the API call.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
List's uid
FIND LIST
1 2 3 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/lists/{uid} \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->list()->find('*|uid|*');
RESPONSE
{
    "list": {
        "uid": "5fc9e55410e10",
        "name": "List 1",
        "default_subject": "Welcome to ABC Corp.",
        "from_email": "admin@abccorp.org",
        "from_name": "ABC Corp.",
        "remind_message": null,
        "status": null,
        "created_at": [],
        "updated_at": [],
        "fields": [
            {
                "key": "EMAIL",
                "label": "Email",
                "type": "string",
                "tag": "EMAIL",
                "default_value": null,
                "visible": "1",
                "required": true,
                "custom_order": null
            },
            ..
        ]
    },
    "contact": {
        "company": "ABC Corp.",
        "address_1": "14 Tottenham Court Road London England",
        "address_2": "44-46 Morningside Road Edinburgh Scotland EH10 4BF",
        "country": "Afghanistan",
        "state":"Armagh",
        "zip": "80000",
        "phone": "123 456 889",
        "url": "http:\/\/www.abccorp.org",
        "email": "info@abccorp.org",
        "city": "Noname"
    },
    "statistics": {
        "subscriber_count": 0,
        "open_uniq_rate": 0,
        "click_rate": 0,
        "subscribe_rate": 0,
        "unsubscribe_rate": 0,
        "unsubscribe_count": 0,
        "unconfirmed_count": 0
    }
}

Add Custom Field

Beside common fields of a contact like emails, names, addresses, cellphone numbers, etc. You can add customized fields to your mail lists to store more information about your list's contacts such as their preferences, scores, etc. and then you can organize contacts based on specific interest groups within your list/audience.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
type string
Choose one of these types: text, number, datetime.
label string
Field' label
tag string
The tag name may have alpha-numeric characters, as well as dashes and underscores.
default_value string
Default value of the field
VIEW LISTS
1 2 3 4 5 6 7 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/lists/{uid}/add-field \
    -d api_token=*|token_string|* \
    -d type=text \
    -d label=Custom \
    -d tag=CUSTOM_FIELD_1 \
    -d default_value=test
1 2 3 4 5 6 7 8 9 10 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->list()->addCustomField('5fd18406c7b1d', [
    'type' => 'text',
    'label' => 'Custom',
    'tag' => 'CUSTOM_FIELD_1',
    'default_value' => 'test',
]);
RESPONSE
{
    "status": 1,
    "message": "List's field was created",
    "field": {
        "mail_list_id": 2,
        "type": "text",
        "label": "Custom",
        "tag":"CUSTOM_FIELD_1",
        "default_value":"test",
        "uid":"5fcae3cb6298f",
        "updated_at":"2020-12-05 01:35:07",
        "created_at":"2020-12-05 01:35:07","id":7
    }
}

Delete List

Delete a list and completely erase the list's information in the web platform.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
List's uid
DELETE LIST
1 2 3 
curl -X DELETE -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/lists/{uid} \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->list()->delete('e31046fce3d83');
RESPONSE
{
    "status": 1,
    "message": "Deleted"
}

Subscribers

By definition, a subscriber is usually someone who is a member of one or more of your lists.
They may have subscribed themselves to your mail list via a subscription page or web form, or you may have imported their details from another source.
Subscribers are also referred to as Audience in Acelle email marketing web platform

List Subscribers

List all subscribers of a given list identified by a UID

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
list_uid string
List's uid
api_token string
Your API token. You can find it in your API main page when logged in.
open string
default: all; yes - opened some campaigns; no - not opened any campaign
click string
default: all; yes - clicked some campaigns; no - not clicked any campaign
per_page string
Number of subscribers per page. Default: 25
page string
Page number
VIEW SUBSCRIBERS
1 2 3 4 5 6 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/subscribers \
    -d api_token=*|token_string|* \
    -d list_uid=*|list_uid|* \
    -d per_page=20 \
    -d page=1
1 2 3 4 5 6 7 8 9 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->subscriber()->all([
    'list_uid' => '5fade5c93e42a',
    'per_page' => '20',
    'page' => '1',
]);
RESPONSE
[
    {
        "uid": "5fd07b8b65284",
        "email": "nickyu88@gmail.com",
        "status": "subscribed",
        "FIRST_NAME": "Nick",
        "LAST_NAME": "KKu",
        "CUSTOM_FIELD_1": "test"
    },
    ...
]

Add Subscriber

Add a subscriber to a list identified by a UID. Once added, the subscriber's status would be either subscribed / active or pending depending on your list settings (single opt-in or double opt-in)

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
list_uid string
List's uid
EMAIL string
Subscriber's email
tag string
Subscriber's tags, seperated by a comma (,).
[OTHER_FIELDS...] string
All subscriber's other fields: FIRST_NAME (?), LAST_NAME (?),... (depending on the list fields configuration)
ADD SUBSCRIBER
1 2 3 4 5 6 7 
curl -X POST -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/subscribers \
    -d api_token=*|token_string|* \
    -d EMAIL=test@gmail.com \
    -d tag=foo,bar,tag+with+space, \
    -d FIRST_NAME=Marine \
    -d LAST_NAME=Joze
1 2 3 4 5 6 7 8 9 10 11 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->subscriber()->create([
    'list_uid' => '5fade5c93e42a',
    'EMAIL' => 'test@gmail.com',
    'tag' => 'foo,bar,tag+with+space,',
    'FIRST_NAME' => 'Marine',
    'LAST_NAME' => 'Joze',
]);
RESPONSE
{
    "status": 1,
    "message": "Confirmation email sent to the subscriber",
    "subscriber_uid": "5fd07ca421da0"
}

Get Subscriber's Details

Get detailed information of a subscriber identified by an UID code. Notice that a subscriber's UID is globally unique. A contact identified by his/her email address may have more than one UID if he or she is added to more than one list.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
list_uid string
Mail list's uid
uid string
Subsciber's uid
FIND SUBSCRIBER
1 2 3 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/subscribers/{uid} \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->subscriber()->find('e31046fce3d83');
RESPONSE
{
    "subscriber": {
        "uid":"5fd07b8b65284",
        "email":"anna122@gmail.com",
        "status":"subscribed",
        "source":null,
        "ip_address":null,
        "FIRST_NAME":"Ann",
        "LAST_NAME":"Anna",
        "CUSTOM_FIELD_1":"test"
    }
}

Update Subscriber Information

Update a subscriber's details, identified by subscriber UID. Notice that a subscriber's UID is globally unique. A contact identified by his/her email address may have more than one UID if he or she is added to more than one list.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Subsciber's uid
EMAIL string
Subscriber's email
tag string
Subscriber's tags, seperated by a comma (,).
[OTHER_FIELDS...] string
All subscriber's other fields: FIRST_NAME (?), LAST_NAME (?),... (depending on the list fields configuration)
UPDATE SUBSCRIBER
1 2 3 4 5 6 7 
curl -X PATCH -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/subscribers/{uid} \
    -d api_token=*|token_string|* \
    -d EMAIL=test@gmail.com \
    -d tag=foo,bar,tag+with+space \
    -d FIRST_NAME=Marine \
    -d LAST_NAME=Joze
1 2 3 4 5 6 7 8 9 10 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->subscriber()->update('e31046fce3d83', [
    'EMAIL' => 'test2@gmail.com',
    'tag' => 'foo,bar,tag+with+space,',
    'FIRST_NAME' => 'Marine',
    'LAST_NAME' => 'Joze',
]);
RESPONSE
{
    "status": 1,
    "message": "Subscriber was successfully updated",
    "subscriber_uid": "5fd07b8b65284"
}

Find Subscribers by Email

In Acelle platform, a contact is identified by his/her unique email address and he or she may belong to more than one list with different list's specific values. For example, a contact may have different ADDRESS values in different lists

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
email email
Subsciber's email
FIND SUBSCRIBERS
1 2 3 4 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/subscribers/email/{email} \
    -d api_token=*|token_string|* \
    -d email=test22@gmail.com
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->subscriber()->findByEmail('test22@gmail.com');
RESPONSE
{
    "subscribers": [
        {
            "uid":"5fd07b8b65284",
            "list_uid":"5fc9e55410e10",
            "email":"test22@gmail.com",
            "status":"subscribed",
            "source":null,
            "ip_address":null,
            "FIRST_NAME":"Marine",
            "LAST_NAME":"Joze",
            "CUSTOM_FIELD_1":null
        }
    ]
}

Add Tag

Add one or more tags to a given subscriber. Tagging allows you to add custom labels to your subscribers, giving you the ability to reach people based on specific traits.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Subscriber's uid
tag string
Subscriber's tags, seperated by a comma (,).
ADD SUBSCRIBER TAG
1 2 3 4 
curl -X POST -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/subscribers \
    -d api_token=*|token_string|* \
    -d tag=foo,bar,tag+with+space,
1 2 3 4 5 6 7 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->subscriber()->addTag('5fade5c93e42a', [
    'tag' => 'foo,bar,tag+with+space,',
]);
RESPONSE
{
    "status": 1,
    "message": "Tag was added successfully",
    "subscriber_uid": "5fd07ca421da0",
    "tags": ["foo","bar","tag with space"]
}

Subscribe

Add a subscriber to a list identified by a UID. Once added, the subscriber's status would be either pending. This also triggers a confirmation email sending to the subscriber's email address for verification.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
list_uid string
Mail list's uid
uid string
Subsciber's uid
SUBSCRIBE
1 2 3 
curl -X PATCH -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/lists/{list_uid}/subscribers/{uid}/subscribe \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->list()->subscribe($uid = 'e31046fce3d83', $subscriber_uid = '6292e06666859');
RESPONSE
{
    "status": 1,
    "message": "Subscriber was subscribed"
}

Unsubscribe

Unsubscribe a contact from a given list. Notice that the contact is still available in the list but of unsubscribed status and Acelle will no longer send marketing emails to this contact. You can completely delete the contact from the list using the DELETE API method.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
list_uid string
Mail list's uid
uid string
Subsciber's uid
UNSUBSCRIBE
1 2 3 
curl -X PATCH -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/lists/{list_uid}/subscribers/{uid}/unsubscribe \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->list()->unsubscribe($uid = 'e31046fce3d83', $subscriber_uid = '6292e06666859');
RESPONSE
{
    "status": 1,
    "message": "Subscriber was unsubscribed"
}

Remove Subscriber

Remove a subscriber from a list and completely erase the subscriber's information in the web platform.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
list_uid string
Mail list's uid
uid string
Subsciber's uid
DELETE SUBSCRIBER
1 2 3 
curl -X DELETE -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/subscribers/{uid} \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->subscriber()->delete('e31046fce3d83');
RESPONSE
{
    "status": 1,
    "message": "Deleted"
}

Campaigns

An email marketing campaign is a coordinated set of individual email messages that are deployed across a specific period of time with one specific purpose. These specific purposes or calls-to-action (CTAs) can include the following: download a white paper, sign up for a webinar, or make a purchase. Acelle allows you to create a marketing campaign targeting one or more lists of your audience. You can also set up a campaign that targets a segment of a given list, rather than the entire list

IMPORTANT: as of version 1.0, Acelle API for campaigns is limited to READ ONLY methods. For setting up and running a campaign, users will need to login to the web UI.

List Campaigns

List all campaigns including new, running or closed ones.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
VIEW LISTS
1 2 3 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/campaigns \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->campaign()->all();
RESPONSE
[
    {
        "uid":"5fb48ff221b27",
        "name":"My Awesome Campaign",
        "type":"regular",
        "subject":"An Awesome Subject",
        "html":"<!DOCTYPE html>\n<html lang=\"en\">\n...",
            "plain": "One column layout...",
            "from_email": "marketing@acelle.com",
            "from_name":"No Reply",
            "reply_to":"support@acelle.com",
            "status":"new",
            "delivery_at":null,
            "created_at":"2021-11-18 03:07:30",
            "updated_at":"2021-11-18 03:07:41"
    },
    ...
]

Get Campaign's Details

Get detailed information and statistics of a campaign identified by a UID code.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Campaign's uid
FIND CAMPAIGN
1 2 3 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/campaigns/{uid} \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->campaign()->find('5fb48ff221b27');
RESPONSE
{
    "campaign": {
        "uid":"5fb48ff221b27",
        "name":"Untitled",
        "list":"",
        "segment":"",
        "default_subject":null,
        "from_email":"marketing@acelle.com",
        "from_name":"Marketing Department",
        "remind_message":null,
        "status":"new",
        "created_at":[],
        "updated_at":[]
    },
    "statistics": {
        "subscriber_count":4,
        "uniq_open_rate":0,
        "delivered_rate":0,
        "open_count":0,
        "uniq_open_count":0,
        "last_open":"",
        "click_rate":0,
        "click_per_uniq_open":0,
        "click_count":0,
        "abuse_feedback_count":0,
        "last_click":"",
        "bounce_count":0,
        "unsubscribe_count":0,
        "links":[],
        "top_locations":[],
        "top_open_subscribers":[]
    }
}

Pause a Campaign

Pause a running campaign. You can later on run the campaign again to have it resume from where it left off.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Campaign's uid
PAUSE CAMPAIGN
1 2 3 4 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/campaigns/{uid}/pause \
    -d api_token=*|token_string|* \
    -d uid=*|uid|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->campaign()->pause('6006510d1d421');
RESPONSE
{
    "status": "success",
    "message": "The campaign was paused",
    "campaign": {
        "uid": "6006510d1d421",
        "name": "Copy of Untitled",
        "list": "",
        "segment": "",
        ...
    }
}

Notifications

Acelle Notification API is also referred to as Web Hooks, allowing 3rd delivery service or application (like PowerMTA, Postfix, Exim...) to send a delivery or abuse report to Acelle for a given transaction which could be a success / bounce / feedback or abuse report

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
message_id string
Message's id
type string
One of 4 types: sent | bounced | reported | failed
bounce_type string
Required if type is bounced
report_type string
Required if type is reported
description string
Notification message
VIEW SENT NOTIFICATIONS
1 2 3 4 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/notifications \
    -d api_token=*|token_string|* \
    -d type=sent
1 2 3 4 5 6 7 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->notification()->read([
    'type' => 'sent',
    'message_id' => '201637442604422402.6199642caf7f3',
]);
VIEW BOUNCED NOTIFICATIONS
1 2 3 4 5 6 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/notifications \
    -d api_token=*|token_string|* \
    -d type=bounced \
    -d bounced_type=hard \
    -d description=Email+address+does+not+exist
1 2 3 4 5 6 7 8 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->notification()->read([
    'type' => 'bounced',
    'message_id' => '201637442604422402.6199642caf7f3',
    'bounced_type' => 'hard',
]);
VIEW ABUSE NOTIFICATIONS
1 2 3 4 5 6 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/notifications \
    -d api_token=*|token_string|* \
    -d type=abuse \
    -d report_type=hard \
    -d description=Email+address+does+not+exist
1 2 3 4 5 6 7 8 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->notification()->read([
    'type' => 'abuse',
    'message_id' => '201637442604422402.6199642caf7f3',
    'report_type' => 'hard',
]);
RESPONSE
{
    "message": "Comming..."
}

Files

Every user or customer account has its own storage folder in Acelle platform. You can upload assets (images, video, other file types, etc.) to the customer or user's storage via API. These assets will be then added or attached to the user's email content.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
files string
File url(s)
subdirectory string
Custom subdirectory. Default: user root directory
VIEW SENT NOTIFICATIONS
1 2 3 4 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/file/upload \
    -d api_token=*|token_string|* \
    -d files='[{"url":"http://demo.acellemail.com/images/logo_big.svg","subdirectory":"path/to/file"},{"url":"http://demo.acellemail.com/images/logo_big.svg"}]","subdirectory":"path/to/file2"}]'
1 2 3 4 5 6 7 8 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->file()->upload([
    'files' => '[{"url":"http://demo.acellemail.com/images/logo_big.svg","subdirectory":"path/to/file"},{"url":"http://demo.acellemail.com/images/logo_big.svg","subdirectory":"path/to/file2"}]',
]);
RESPONSE
[
    {
        "file": "http:\/\/demo.acellemail.com\/images\/logo_big.svg",
        "status": 1,
        "message": "File uploaded"
    },
    {
        "file": "http:\/\/demo.acellemail.com\/images\/logo_big.svg",
        "status": 1,
        "message": "File uploaded"
    }
]

Understanding of Service Plans and Subscription

Acelle is pre-designed as an SAAS (Software as a service) platform, allowing you to host it under your brand and charge your users for registering and using its features. When you start your hosting reselling business, you should define how you will offer your hosting resources and services to customers. Acelle lets you organize your business by means of service plans and subscriptions.

A service plan is a combination of hosting resources that you sell to your customers. For example, a plan can provide customers with the contacts/lists management service, a maximum of 100,000 contacts stored on the server, and 1 million email sending credits each month.

List Plans

List all plans available

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
FIND PLANS
1 2 3 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/login-token \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->plan()->all();
RESPONSE
[
    {
        "uid":"58bd48f91fcab",
        "name":"Free",
        "price":"0.00",
        "currency_code":"USD",
        "frequency_amount":"1",
        "frequency_unit":"month",
        "options": {
            "email_max":"5000",
            "list_max":"10",
            "subscriber_max":"1000",
            "subscriber_per_list_max":"-1",
            "segment_per_list_max":"3",
            "campaign_max":"20",
            "automation_max":"10",
            "billing_cycle":"monthly",
            "sending_limit":"1000_per_hour",
            "sending_quota":1000,
            "sending_quota_time":1,
            "sending_quota_time_unit":"hour",
            "max_process":"1",
            "all_sending_servers":"yes",
            "max_size_upload_total":"500",
            "max_file_size_upload":"5",
            "unsubscribe_url_required":"yes",
            "access_when_offline":"no",
            "create_sending_domains":"no",
            "sending_servers_max":"-1",
            "sending_domains_max":"-1",
            "all_email_verification_servers":"yes",
            "create_email_verification_servers":"no",
            "email_verification_servers_max":"-1",
            "list_import":"yes","list_export":"yes",
            "all_sending_server_types":"yes",
            "sending_server_types": {
                "amazon-smtp":"yes",
                "amazon-api":"yes",
                "sendgrid-smtp":"yes",
                "sendgrid-api":"yes",
                "mailgun-api":"yes",
                "mailgun-smtp":"yes",
                "elasticemail-api":"yes",
                "elasticemail-smtp":"yes",
                "sparkpost-api":"yes",
                "sparkpost-smtp":"yes",
                "smtp":"yes",
                "sendmail":"yes",
                "php-mail":"yes"
            },
            "sending_server_option":
            "system",
            "sending_server_subaccount_uid":null,
            "api_access":"yes",
            "email_footer_enabled":"yes",
            "email_footer_trial_period_only":"no",
            "html_footer":"",
            "plain_text_footer":"",
            "payment_gateway":""
        },
        "status":"active",
        "color":"#008c6e",
        "quota":null,
        "custom_order":"1",
        "created_at":[],
        "updated_at":[]
    },
    ...
]

Create Plan

Create a service plan and make it available for users to subscribe. You can also specify the plan's quota settings and many attributes at creation time.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
name string
Plan's name
currency_id string
Currency's id
frequency_amount string
Billing recurs every this amount of time
frequency_unit string
Time unit for billing recurs (day, week, month, year, unlimited)
price string
Plan's price
color string
Plan's color (red, blue, #008c6e, #917319,...)
options[...] string
Plan's options...
Show child attributes Hide child attributes
email_max
Email sending credits (number, -1 for unlimited)
list_max
Max lists (number, -1 for unlimited)
subscriber_max
Max subscribers (number, -1 for unlimited)
subscriber_per_list_max
Max subscribers per list (number, -1 for unlimited)
segment_per_list_max
Max segments per list (number, -1 for unlimited)
campaign_max
Max campaigns (number, -1 for unlimited)
automation_max
Max automations (number, -1 for unlimited)
sending_quota
Sending credits (number, -1 for unlimited)
sending_quota_time
Time value (number, -1 for unlimited)
sending_quota_time_unit
Time unit (day|hour|minute)
max_process
Max number of processes (number)
all_sending_servers
Use all sending servers (yes|no)
max_size_upload_total
Maximum size of all files (MB) (number)
max_file_size_upload
Maximum upload size per file (MB) (number)
unsubscribe_url_required
{UNSUBSCRIBE_URL} tag is required (yes|no)
access_when_offline
Access when site is offline (yes|no)
create_sending_domains
Allows customer to add sending domains (yes|no)
sending_servers_max
Max sending servers per customer (number, -1 for unlimited)
sending_domains_max
Max sending domains per customer (number, -1 for unlimited)
all_email_verification_servers
Use all email verification servers (yes|no)
create_email_verification_servers
Allows customer to add email verification servers (yes|no)
email_verification_servers_max
Max email verification servers per customer (number, -1 for unlimited)
list_import
Customer can import list (yes|no)
list_export
Customer can export list (yes|no)
all_sending_server_types
Allow customer to add any sending server type (yes|no)
sending_server_types
(array)
sending_server_option
(system|own|subaccount)
sending_server_subaccount_uid
Sending server's sub-account ID
CREATE NEW LIST
1 2 3 4 5 6 7 8 9 10 11 
curl -X POST -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/login-token \
    -d api_token=*|token_string|* \
    -d name=Advanced \
    -d currency_id=1 \
    -d frequency_amount=1 \
    -d frequency_unit=month \
    -d price=20 \
    -d color=red \
    -d options[sending_server_option]=own \
    -d options[email_max]=10000
1 2 3 4 5 6 7 8 9 10 11 12 13 14 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->plan()->create([
    'name' => 'Advanced',
    'currency_id' => '1',
    'frequency_amount' => '1',
    'frequency_unit' => 'month',
    'price' => '20',
    'color' => 'red',
    'options[sending_server_option]' => 'own',
    'options[email_max]' => '10000',
]);
RESPONSE
{
    "status": 1,
    "message": "Plan was successfully created",
    "plan_uid": "5fd08d2ed4cc8"
}

List Sending Servers

A sending server in Acelle is actually a connection to a sending server or service. Normally, it is an SMTP server which actually delivers marketing emails. You can configure Acelle to sends email through a remote SMTP server or a local mailer program installed in the hosting server itself. Acelle currently does not support creating a sending server via API, you may want to login to the web UI to do it. However, you can list all available sending servers in the system using API.

Parameters
api_token string
User's API token. You can find it in your profile settings page
VIEW SENDING SERVERS
1 2 3 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/sending_servers \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->sending_server()->all();
RESPONSE
[
    {
        "uid":"5fc273b9ded36",
        "name":"Amazon API",
        "created_at":"2020-11-28 15:58:49",
        "updated_at":"2020-11-28 15:58:53"
    }
]

Customers

In Acelle, customers sign up against the web application to create an account and subscribe to a service plan (free, standard, premium... for example) then pay for it in order to use the system's functionality. Acelle API allows you to manage your customers and subscriptions which is helpful when you use Acelle with another application or system.

Create Customer

Create a new customer account. You can later on subscribe the newly created customer to a plan using PLAN api.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
email email
Customer's email
password string
Customer's password
first_name string
Customer's first name
last_name string
Customer's last name
timezone string
Customer's timezone
language_id string
Language id
ADD CUSTOMER
1 2 3 4 5 6 7 8 9 
curl -X POST -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/customers \
    -d api_token=*|token_string|* \
    -d email=user_name@gmail.com \
    -d first_name=Luan \
    -d last_name=Pham \
    -d timezone=America/Godthab \
    -d language_id=1 \
    -d password=123456
1 2 3 4 5 6 7 8 9 10 11 12 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->customer()->create([
            'email' => 'user_namexx@gmail.com',
            'first_name' => 'Luan',
            'last_name' => 'Pham',
            'timezone' => 'America/Godthab',
            'language_id' => '1',
            'password' => '123456',
        ]);
RESPONSE
{
    "status": 1,
    "message": "Customer was successfully created",
    "customer_uid": "5fd093b62ea11",
    "api_token": "fPBMSHhY95mnj8sZBbNALYQe611hSO4CqcOOX4KI0TZSK2Py3gUtVUHYNH8a"
}

Get Customer's Details

Get detailed information of a customer identified by a UID code

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Customer's uid
FIND CUSTOMER
1 2 3 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/customers/{uid} \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->customer()->find('5fd1a0097ce01');
RESPONSE
{
    "customer": {
        "uid": "5fd093b62ea11",
        "first_name": "Luan",
        "last_name": "Pham",
        "image": null,
        "timezone": "America\/Godthab",
        "status": "active",
        "options": [],
        "current_period_ends_at": null
    }
}

Update Customer

Update a customer's attributes, identified by a UID code

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Customer's uid
email email
Customer's email
password string
Customer's password
first_name string
Customer's first name
last_name string
Customer's last name
timezone string
Customer's timezone
language_id string
Language id
UPDATE CUSTOMER
1 2 3 4 5 6 7 8 9 
curl -X PATCH -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/customers/{uid} \
    -d api_token=*|token_string|* \
    -d email=user_name@gmail.com \
    -d first_name=Luan \
    -d last_name=Pham \
    -d timezone=America/Godthab \
    -d language_id=1 \
    -d password=123456
1 2 3 4 5 6 7 8 9 10 11 12 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->customer()->update('5fd1a0097ce01', [
    'email' => 'user_namexx@gmail.com',
    'first_name' => 'Luan',
    'last_name' => 'Pham',
    'timezone' => 'America/Godthab',
    'language_id' => '1',
    'password' => '123456',
]);
RESPONSE
{
    "customer": {
        "uid": "5fd093b62ea11",
        "first_name": "Luan",
        "last_name": "Pham",
        "image": null,
        "timezone": "America\/Godthab",
        "status": "active",
        "options": [],
        "current_period_ends_at": null
    }
}

Enable Customer

Enable a customer if the customer was previously disabled.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Customer's uid
ENABLE CUSTOMER
1 2 3 
curl -X PATCH -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/customers/{uid}/enable \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->customer()->enable('5fd1a0097ce01');
RESPONSE
{
    "status": 1,
    "message": "Customer was enabled",
    "customer_uid": "5fd093b62ea11"
}

Disable Customer

Disable a Customer, preventing the Customer from logging to the application.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Customer's uid
DISABLE CUSTOMER
1 2 3 
curl -X PATCH -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/customers/{uid}/disable \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->customer()->disable('5fd1a0097ce01');
RESPONSE
{
    "status": 1,
    "message": "Customer was disabled",
    "customer_uid": "5fd093b62ea11"
}

Assign Plan

Assign a plan to a customer. In other words, subscribe a user to a plan. Then the customer will then be able to login to the application and proceed with paying for the plan. If the plan is free, then the user is subscribed and can immediately use the features.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Customer's uid
plan_uid string
Plan's uid
disable_billing boolean
Activate the subscription without checking out. Default: false
ASSIGN PLAN
1 2 3 
curl -X POST -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/customers/{uid}/assign-plan/{plan_uid} \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->customer()->assignPlan('5fd1a0097ce01', '5fd1a16fb8f27');
RESPONSE
{
    "status": 1,
    "message": "Customer was assigned to plan",
    "customer_uid": "5fd093b62ea11"
}

Subscriptions

Manage user subscriptions to plans. You can create a new subscription, activate a pending subscription or cancel a subscription.
Normally, users can sign up to the system, subscribe to a plan and proceed with the payment.
The API is helpful in case you want to quickly assign a plan to a user.

Create a subscription

List all subscriptions from application.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
per_page string
Number of subscriptions each page. Default is 25
page string
Page number. Default is 1
SUBSCRIPTIONS
1 2 3 4 5 
curl -X GET -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/subscriptions \
    -d api_token=*|token_string|* \
    -d per_page=20 \
    -d plan_uid=1
1 2 3 4 5 6 7 8 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->subscription()->all([
    'per_page' => '25',
    'page' => '1',
]);
RESPONSE
[
    {
        "id": 1,
        "uid": "5fade5c93e42a",
        "customer_id": "23",
        "plan_id": "8",
        "status": "ended",
        "current_period_ends_at": null,
        "ends_at": "2021-11-13 01:47:53"
    },
    {
        "id": 2,
        "uid": "5fc9e55410e10",
        ...
    },
    ...
]

Create a subscription

Assign a plan to a customer. In other words, subscribe a user to a plan. Then the customer will then be able to login to the application and proceed with paying for the plan. If the plan is free, then the user is subscribed and can immediately use the features.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Customer's uid
plan_uid string
Plan's uid
disable_billing boolean
Activate the subscription without checking out. Default: false
ASSIGN PLAN
1 2 3 
curl -X POST -H "accept:application/json" -G \
    http://acelle.wsl/api/v1/customers/{uid}/assign-plan/{plan_uid} \
    -d api_token=*|token_string|*
1 2 3 4 5 
$client = new Acelle\Client(
    'http://acelle.local/api/v1',
    '*|api_token|*'
);
$client->customer()->assignPlan('5fd1a0097ce01', '5fd1a16fb8f27');
RESPONSE
{
    "status": 1,
    "message": "Customer was assigned to plan",
    "customer_uid": "5fd093b62ea11"
}