Developer Documentation

Search…
This page is meant for developers only. It shows how to develop an add-on for AcyMailing and how to use the AcyMailing code for general needs.
Create an AcyMailing plugin to insert content in your emails
Here is an example of AcyMailing plugin you can download, it is fully commented and meant to explain every part of the code. When developing a new add-on, you could also copy an existing one and just change the SQL queries/names in it if you find it easier.
Joomla
WordPress
example.zip
19KB
Binary
example.zip
Don't forget to replace any reference of "example" by your plugin's name, for example "myplugin".
You can upload the folder of your plugin in: administrator / components / com_acym / dynamics /
acymailing-example.zip
25KB
Binary
acymailing-example.zip
Don't forget to replace any reference of "example" by your plugin's name, for example "myplugin".
You can install the plugin in the WordPress plugins section of your site.
Once added, you will see it in the add-ons page of AcyMailing. 
Once your custom add-on is installed in the correct folder, insert a new line in the table xxxx_acym_plugin with folder_name = the add-on's folder name, active = 1, type = ADDON.
Other methods you can use in your plugin
When the user is created
You can use these methods to execute specific actions before/after a user is created
1
 
2
public function onAcymBeforeUserCreate(&$user) {
3
// Your code here
4
}
5
public function onAcymAfterUserCreate(&$user) {
6
// Your code here
7
} 
Copied!
When the user is modified
You can use these methods to execute specific actions before/after a user is modified
1
 
2
public function onAcymBeforeUserModify(&$user) {
3
// Your code here
4
}
5
public function onAcymAfterUserModify(&$user) {
6
// Your code here
7
} 
Copied!
When the user is deleted
You can use these methods to execute specific actions before/after one or several users are deleted
1
 
2
public function onAcymBeforeUserDelete(&$users) {
3
// Your code here, $users is always an array of IDs
4
}
5
public function onAcymAfterUserDelete(&$users) {
6
// Your code here, $users is always an array of IDs
7
} 
Copied!
When the user subscribes to a list
This method is called after the user subscribes to one or several lists
1
 
2
public function onAcymAfterUserSubscribe(&$user, $lists) {
3
// Your code here, $lists is always an array of list IDs
4
} 
Copied!
When the user unsubscribes from a list
This method is called after the user unsubscribes from one or several lists
1
 
2
public function onAcymAfterUserUnsubscribe(&$userID, $lists) {
3
// Your code here, $lists is always an array of list IDs
4
} 
Copied!
Code API for quick integration
Before each of the following examples, please make sure you load the AcyMailing library.
Joomla
WordPress
1
if(!include_once(rtrim(JPATH_ADMINISTRATOR, DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.'components'.DIRECTORY_SEPARATOR.'com_acym'.DIRECTORY_SEPARATOR.'helpers'.DIRECTORY_SEPARATOR.'helper.php')){
2
    echo 'This code can not work without the AcyMailing Component';
3
    return false;
4
} 
Copied!
1
if(!include_once(WP_PLUGIN_DIR.DIRECTORY_SEPARATOR.'acymailing'.DIRECTORY_SEPARATOR.'back'.DIRECTORY_SEPARATOR.'helpers'.DIRECTORY_SEPARATOR.'helper.php')){
2
    echo 'This code can not work without the AcyMailing Component';
3
    return false;
4
}
Copied!
How to load the CMS API
If you want to use the AcyMailing code outside of your site, you will need to load your site's library then the AcyMailing library.
Joomla
WordPress
Add these lines first in your script and don't forget to replace "PATH_TO_YOUR_JOOMLA_SITE_ROOT_FOLDER" by the real value
1
define('_JEXEC', 1);
2
define('DS', DIRECTORY_SEPARATOR);
3
 
4
if (file_exists(dirname(__FILE__) . '/defines.php')) {
5
 include_once dirname(__FILE__) . '/defines.php';
6
}
7
 
8
if (!defined('_JDEFINES')) {
9
 define('JPATH_BASE', 'PATH_TO_YOUR_JOOMLA_SITE_ROOT_FOLDER');
10
 require_once JPATH_BASE.'/includes/defines.php';
11
}
12
 
13
require_once JPATH_BASE.'/includes/framework.php';
14
$app = JFactory::getApplication('site');
Copied!
Add these lines first in your script and don't forget to replace "PATH_TO_YOUR_WORDPRESS_SITE_ROOT_FOLDER" by the real value
1
define('WP_USE_THEMES', false);
2
require('PATH_TO_YOUR_WORDPRESS_SITE_ROOT_FOLDER/wp-load.php');
Copied!
Get the AcyMailing mailing lists
1
use AcyMailing\Classes\ListClass;
2
​
3
$listClass = new ListClass;
4
$allLists = $listClass->getAll();
5
 
6
// You can then do a foreach on this variable (which contains an array of objects) and use ->name
7
// You can get a specific list like this
8
 
9
$myList = $listClass->getOneById(34);
10
 
11
// Or multiple lists like this
12
 
13
$myLists = $listClass->getListsByIds([22, 48]);
Copied!
Insert a user in AcyMailing
1
use AcyMailing\Classes\UserClass;
2
​
3
$myUser = new stdClass();
4
$myUser->email = 'emailaddressoftheuser';
5
$myUser->name = 'myname'; // this information is optional
6
 
7
// If you require a confirmation but don't want the user to have to confirm his subscription, you can set the confirmed field to 1:
8
// $myUser->confirmed = 1;
9
 
10
// You can add as many extra fields as you want if you already created them in AcyMailing
11
$customFields = [];
12
$customFields[custom_field_id] = 'france'; // the custom field id can be found in the Custom fields list of the AcyMailing admin page
13
//...
14
 
15
$userClass = new UserClass();
16
$userClass->sendConf = true; // Or false if you don't want a confirmation email to be sent
17
$userId = $userClass->save($myUser, $customFields); // this function will return you the ID of the user inserted in the AcyMailing table
Copied!
Get a user and / or its subscription
1
use AcyMailing\Classes\UserClass;
2
​
3
$userClass = new UserClass();
4
 
5
// Get the AcyMailing user from his email address
6
$user = $userClass->getOneByEmail($email);
7
 
8
// Or you can get the AcyMailing user from his site user ID
9
$user = $userClass->getOneByCMSId($userID);
10
 
11
// Get subscription
12
$userSubscriptions = $userClass->getUserSubscriptionById($user->id);
13
 
14
// If you need a simpler result, you can use this method
15
$userSubscriptions = $userClass->getSubscriptionStatus($user->id);
Copied!
Subscribe or remove a user from one or several lists
1
use AcyMailing\Classes\UserClass;
2
​
3
$subscribe = [2,4,6]; // Id of the lists you want the user to be subscribed to (can be empty)
4
$unsubscribe = [1,3]; // Id of the lists you want the user to be unsubscribe from (can be empty)
5
$acyUserId = '23'; // you can use the previous example code to get the user by its site user id or its email address
6
 
7
$userClass = new UserClass();
8
 
9
if(!empty($subscribe)){
10
    $userClass->subscribe($acyUserId, $subscribe);
11
}
12
 
13
if(!empty($remove)){
14
    $userClass->unsubscribe($acyUserId, $unsubscribe);
15
}
Copied!
Create a Campaign
1
use AcyMailing\Classes\MailClass;
2
use AcyMailing\Classes\CampaignClass;
3
​
4
// Lists you want to attach the campaign to
5
$listIds = [3,5,8];
6
 
7
// We create the Campaign element that we will save in the database.
8
// You can use all fields from the database the same way we do it with subject and body.
9
 
10
$mail = new stdClass();
11
$mail->subject = 'your subject'; // Subject of your email
12
$mail->name = 'your campaign name'; // Name of the campaign
13
$mail->body = 'Hi folks, we have a big announcement...'; // Body of your email
14
$mail->bcc = '[email protected]'; // BCC for your campaign
15
 
16
$mailClass = new MailClass();
17
$mailId = $mailClass->save($mail);
18
 
19
$campaign = new stdClass();
20
$campaign->draft = 1; // Create as a draft
21
$campaign->mail_id = $mailId;
22
$campaign->sending_type = CampaignClass::SENDING_TYPE_NOW; // Create a standard campaign
23
 
24
$campaignClass = new CampaignClass();
25
$campaignId = $campaignClass->save($campaign);
26
$campaignClass->manageListsToCampaign($listIds, $mailId);
Copied!
Insert an e-mail in the queue
1
use AcyMailing\Classes\QueueClass;
2
use AcyMailing\Classes\MailClass;
3
​
4
// The purpose of this code is to let AcyMailing send an e-mail to a specific user at a specific time.
5
// You just have to add an entry in the queue and AcyMailing will take care of the rest.
6
 
7
$acyUserId = '23';
8
$mailId = '45'; // ID of the email you want to add in the queue
9
$sendDate = time(); //When do you want the e-mail to be sent to this user? you should specify a timestamp here (time() is the current time)
10
 
11
 // If you want to add the email in the queue only for one specific user
12
$queueClass = new QueueClass();
13
$queueClass->addQueue($acyUserId, $mailId, acym_date($sendDate, 'Y-m-d H:i', false));
14
 
15
// If you want to send the email to all the users subscribed to th list the email is attached to, you can use this:
16
$mailClass = new MailClass();
17
$mailToSend = $mailClass->getOneById($mailId);
18
$mailToSend->sending_date = acym_date($sendDate, 'Y-m-d H:i', false);
19
$mailToSend->parent_id = $mailId;
20
$mailToSend->sending_params = [''];
21
$queueClass->queue($mailToSend);
Copied!
Send an email to a single user
Sometimes you want to send a pre-saved email to a single user only...
In that case you should not bother with the queue system and use this code (it will send the email ID 67 to the user "[email protected]"):
The email ID can be found in the xxxx_acym_mail table, this is NOT the campaign ID displayed on the campaigns listing
1
use AcyMailing\Helpers\MailerHelper;
2
​
3
$mailer = new MailerHelper();
4
$mailer->report = true; // set it to true or false if you want Acy to display a confirmation message or not (message successfully sent to...)
5
$mailer->trackEmail = true; // set it to true or false if you want Acy to track the message or not (it will be inserted in the statistics table)
6
$mailer->autoAddUser = false; // set it to true if you want Acy to automatically create the user if it does not exist in AcyMailing
7
$mailer->addParam('var1', 'Value of the variable 1'); // Acy will automatically replace the tag {var1} by the value specified in the second parameter... you can use this function several times to replace tags in your email
8
$mailer->sendOne(67, '[email protected]'); // The first parameter is the ID of the email you want to send
Copied!
Create a list
1
use AcyMailing\Classes\ListClass;
2
​
3
$newList = new stdClass();
4
$newList->name = 'Your list name';
5
$newList->active = 1;
6
$newList->welcome_id = 43; // Optional. This is the Id of the mail you want to send as welcome email
7
$newList->unsubscribe_id = 52; // Optional. This is the Id of the mail you want to send when a user unsubscribes
8
$newList->color = '#3366ff'; // Optional. This is the color of the list
9
 
10
$listClass = new ListClass();
11
$listId = $listClass->save($newList); // This function will create the list and return the ID of the created list
Copied!
Delete a list
1
use AcyMailing\Classes\ListClass;
2
​
3
// This code will detach the list from your campaigns, delete the user subscriptions to that list then delete the list
4
 
5
$listClass = new ListClass();
6
$listClass->delete(43); // You should replace 43 by the ID of the list you want to delete
Copied!