AcyMailing 5 Developer Documentation

Dear developer,

Joomla! is not only the best CMS because of its core team; Joomla! is empowered by all the third-party extensions, professional or not, which add so many functionalities to any website. Based on this success, we decided to open AcyMailing to any addition using a the powerful Joomla Plugin system.

AcyMailing uses the Joomla Plugin system to handle its tag system.

So the first thing you have to do is to create a standard Joomla plugin with the group "acymailing" and install it on Joomla. We recommend you to download and install our fully commented example plugin :

22KB

plg_acymailing_example2.zip

acymailing_getPluginType()

This function enables AcyMailing to display your tag on our tag system (on the interface after you click on the button "Tag"). If you don't want your tag to have an user interface simply don't add this function (for example, the AcyMailing statistics plugin does not need any user interface so this function is not included in it).

If you want to have a tag interface, you have to return us an object with :

name : Name of your plugin (this name is only useful on the user interface, it can be anything you want)
function : Name of the function AcyMailing should trigger on the user interface. On the tag interface, if the user clicks on your tag name, AcyMailing has to trigger your plugin and your plugin only. For that you have to tell us a name of function. Please make sure this name is unique!
help : This argument is only useful if you plan to send us a documentation about how the user can use your plugin. If you specify the help attribute, AcyMailing will display an help button on your tag interface to give the user the possibility to read the documentation.

function acymailing_getPluginType(){
    $onePlugin = new stdClass();
    $onePlugin->name = 'Tab title for the tag interface';
    $onePlugin->function = 'acymailingMyUniqueNameFunction';
    $onePlugin->help = 'plugin-mypluginname';
    return $onePlugin;
}

Your own function name

Using the function acymailing_getPluginType, you returned to AcyMailing a name and an unique function name to call. You should create this function on your own plugin which will be triggered if the user clicks on your tag name on our interface. For the time plugin, this function is called acymailingtagtime_show but it could be anything else, it just has to be unique.

On the following screenshot, we called it acymailingMyUniqueNameFunction.

    //This is the function name I specified in the previous 
    $onePlugin->function argument. 
    //This function will be triggered if my tab is selected on the interface 
    //If you don't want an interface on the tag system, just remove this function 
    function acymailingMyUniqueNameFunction(){ 
        //In this file you can use the javascript function setTag('your tag'); and insertTag(); which will set the tag and insert it in your Newsletter. 
        //Please only use insertTag() if you want the tag to be direclty inserted but if you use only setTag('your tag') then the user will be able to see it and click on the insert button. 
        //Your content will be inserted inside a form, you can add a submit button or whatever you want, it will do the job (if you want to add a search option). 
        echo '<div onclick="setTag(\'{myowntag}\');insertTag();">Click here to insert my tag</div>';
    }

You don't have to return anything. This function is called so that you can display anything you want on your tag interface. For example, on the AcyMailing time plugin, we give to the user the choice to insert different kind of time.

AcyMailing makes your life easier and handles the tag insertion. You can use two javascript function to do that:

setTag(yourtag) : this function will set the tag in AcyMailing. You have first to call this function if you want the tag to be inserted in the Newsletter. If you call this function, a button "add the tag" will be automatically displayed on your interface and the user will be able to click on it to insert your tag.
insertTag() : you may want to add this function after calling the setTag function to directly include your tag in the Newsletter.

Please don't add a form on your tag interface, AcyMailing already did it so you can directly add some submit button if you want to give the possibility to the user to search or sort your columns.

This function enables you to replace your global tags.

What we call global tags is a tag which does not depend on the user information. So this tag is the same for all users.

AcyMailing will trigger this function during the preview and only one time during the send process.

There are two parameters for this function:

$email which is an object with the:
- body : body of the Newsletter in HTML
- altbody : body of the Newsletter in plain text version
- subject : subject of the Newsletter
$send indicates if the Newsletter will be sent (set to true) or displayed on the browser (set to false)

You don't have to return anything, simply directly modify the Newsletter the way you want.

function acymailing_replacetags(&$email,$send=true){
    $email->body = $email->body.' I just added this text to the html version';
    $email->altbody = $email->altbody.' and this text to the text version';
    $email->subject = 'Hello, the subject is : '.$email->subject;
    if(!$send){
        $email->body .= 'This Newsletter is displayed on the browser';
    }
}

This function enables you to replace your personal tags.

AcyMailing will trigger this function each time an e-mail is sent or displayed (on the archive version for example) for each user.

The last parameter $send enables you to know if the Newsletter will be sent (set to true) or displayed on the browser (set to false)

function acymailing_replaceusertags(&$email,&$user,$send = true){
    $email->body .= '<br/>this e-mail is for '.$user->name;
    $email->body .= ' (ID: '.$user->subid.'; email:'.$user->email.')';
    if($send){
        $email->subject .= ' this message is sent';
    }
}

acymailing_generateautonews(&$email)

This function enables you to accept or block a Newsletter generation from our Smart-Newsletters feature. For example, this function is used in our Joomla content plugin to check if there are new articles created since the last generated date. If not, we will stop the Newsletter generation.

You can use the email object and you can access the latest generated date with $email->params['lastgenerateddate'] (this value is a timestamp but won't exist if you trigger this function from somewhere else)

You should return an object with:

status : TRUE / FALSE True: your plugin allows the Newsletter to be generated False: your plugin will block the Newsletter generation
message : In case of you block the Newsletter generation, you can specify a message which will be displayed on the interface and recorded in the log.

function acymailing_generateautonews(&$email){
    $return = new stdClass();
    $return->status = true;
    $return->message = '';
    if(...){
        //If don't want the Newsletter to be generated (because there is no new element for example)
        $return->status = false;
        $return->message = 'Newsletter blocked because...';
    }
    //You need to return an object with the status and message (reason) in case of the status is set to false.
    return $return;
}

Create a filter

You can add your own filters to our filter interface.

onAcyDisplayFilters(&$type)

This function enables you to add a new filter type on our filter interface.

You should return a string which will be displayed on the filtering interface and add a new type in $type variable.

Then if your filter is selected, the function onAcyProcessFilter_YOURTYPE(&$query,$filter,$num) will be triggered.

Please have a look at our existing plugins (tagsubscription or tagsubscriber to have an example).

Create an action

You can add your own actions to our filter interface.

onAcyDisplayActions(&$type)

This function enables you to add a new action type on our filter interface.

You should return a string which will be displayed on the filtering interface and add a new type in $type variable.

Then if your filter is selected, the function onAcyProcessAction_YOURTYPE(&$query,$action,$num) will be triggered.

Please have a look at our existing plugins (tagsubscription or tagsubscriber to have an example).

Create a new custom field type

Please download this example plugin to create your own custom field type. This example plugin is fully self-documented.

15KB

plg_acymailing_exampleCF.zip

Other plugin triggers

When the user is created

When the user is created, the function onAcyUserCreate($subscriber) is triggered.

When the user is modified

When the user is modified, the function onAcyUserModify($subscriber) is triggered.

When the user is deleted

When the user is deleted, the function onAcyBeforeSubscriberDelete($subscriber) is triggered.

When the user subscribes to a list

When the user subscribes to a list, the function onAcySubscribe($subid,$listids) is triggered.

When the user unsubscribes from a list

When the user unsubscribes from a list, the function onAcyUnsubscribe($subid,$listids) is triggered.

When the Newsletter is added to the queue (just after adding it to the queue), just before the send process starts, the function onAcySendNewsletter($mailid) is triggered

When a list is created

Just before a list is created, the function onAcyBeforeListCreate($list) is triggered

When a list is modified

Just before a list is modified, the function onAcyBeforeListModify($list) is triggered

When a list is deleted

Just before a list is deleted, the function onAcyBeforeListDelete($elements) is triggered $elements is an array of list IDs.

When the user clicks on a link

Just before the user is redirected to the final url, the function onAcyClickLink($subid,$mailid,$urlid) is triggered $subid is the ID of the user from the acymailing_subscriber table. $mailid is the ID of the Newsletter. $urlid is the ID of the clicked link.

Cron trigger

Using our commercial version (if you created your cron task), AcyMailing will trigger the function onAcyCronTrigger every day automatically.

So you can create a Joomla plugin type AcyMailing with this function and it will be automatically triggered once a day (only once a day even if your cron has a 15 minutes frequency).

There is no argument for this function but you can return a string which will be automatically included in the cron report.

API

Get the AcyMailing mailing lists

if(!include_once(rtrim(JPATH_ADMINISTRATOR,DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.'components'.DIRECTORY_SEPARATOR.'com_acymailing'.DIRECTORY_SEPARATOR.'helpers'.DIRECTORY_SEPARATOR.'helper.php')){
    echo 'This code can not work without the AcyMailing Component'
    return false;
}
$listClass = acymailing_get('class.list');
$allLists = $listClass->getLists();//You can then do a foreach on this variable (which contains an array of objects) and use ->name

Insert a user in AcyMailing

if(!include_once(rtrim(JPATH_ADMINISTRATOR,DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.'components'.DIRECTORY_SEPARATOR.'com_acymailing'.DIRECTORY_SEPARATOR.'helpers'.DIRECTORY_SEPARATOR.'helper.php')){
    echo 'This code can not work without the AcyMailing Component';
    return false;
}
$myUser = new stdClass();
$myUser->email = 'emailaddressoftheuser';
$myUser->name = 'myname'; //this information is optional
//If you require a confirmation but don't want the user to have to confirm his subscription via the API, you can set the confirmed field to 1:
//$myUser->confirmed = 1;
//You can add as many extra fields as you want if you already created them in AcyMailing
//$myUser->country = 'france';
//$myUser->phone = '064872754';
//...

$subscriberClass = acymailing_get('class.subscriber');
$subid = $subscriberClass->save($myUser); //this function will return you the ID of the user inserted in the AcyMailing table

Get a user subscription

if(!include_once(rtrim(JPATH_ADMINISTRATOR,DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.'components'.DIRECTORY_SEPARATOR.'com_acymailing'.DIRECTORY_SEPARATOR.'helpers'.DIRECTORY_SEPARATOR.'helper.php')){
    echo 'This code can not work without the AcyMailing Component';
    return false;
}
// Get the subscriber ID (ID of the AcyMailing user) from his email address or his Joomla user ID
$userClass = acymailing_get('class.subscriber');
$subid = $userClass->subid($emailOrUserID);
// Get subscription
$listsubClass = acymailing_get('class.listsub');
$userSubscriptions = $listsubClass->getSubscription($subid);

$subscribe = array(2,4,6); //Id of the lists you want the user to be subscribed to (can be empty) 
$remove = array(1,3); //Id of the lists you want the user to be removed from (can be empty) 
$memberid = '23'; //ID of the Joomla User or user e-mail (this code supposes that the user is already inserted in AcyMailing!) 

if(!include_once(rtrim(JPATH_ADMINISTRATOR,DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.'components'.DIRECTORY_SEPARATOR.'com_acymailing'.DIRECTORY_SEPARATOR.'helpers'.DIRECTORY_SEPARATOR.'helper.php')){ 
    echo 'This code can not work without the AcyMailing Component'; 
    return false; 
} 
$userClass = acymailing_get('class.subscriber'); 
$newSubscription = array(); 
if(!empty($subscribe)){ 
    foreach($subscribe as $listId){ 
        $newList = array(); 
        $newList['status'] = 1; 
        $newSubscription[$listId] = $newList; 
    } 
} 
if(!empty($remove)){ 
    foreach($remove as $listId){ 
        $newList = array(); 
        $newList['status'] = 0; 
        $newSubscription[$listId] = $newList; 
    } 
} 

if(empty($newSubscription)) return; //there is nothing to do... 
$subid = $userClass->subid($memberid); //this function returns the ID of the user stored in the AcyMailing table from a Joomla User ID or an e-mail address 
if(empty($subid)) return false; //we didn't find the user in the AcyMailing tables 
$userClass->saveSubscription($subid,$newSubscription);

if(!include_once(rtrim(JPATH_ADMINISTRATOR,DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.'components'.DIRECTORY_SEPARATOR.'com_acymailing'.DIRECTORY_SEPARATOR.'helpers'.DIRECTORY_SEPARATOR.'helper.php')){ 
    echo 'This code can not work without the AcyMailing Component'; 
    return false; 
}
//We create the Newsletter element that we will save in the database.
//You can use all fields from the database the same way we do it with subject and body.
$mail = new stdClass();
//Subject of your Newsletter 
$mail->subject = 'your subject...';
//Body of your Newsletter... the text version will be automatically generated from this html version. 
$mail->body = 'your body...';
//ID of the template attached to this Newsletter so the CSS defined in that AcyMailing template will be applied to your Newsletter.
$mail->tempid = 4;
$mailClass = acymailing_get('class.mail');
//the save function returns you the ID of the inserted Newsletter so you can then use it to insert e-mails in the queue.
$mailid = $mailClass->save($mail);

Insert an e-mail in the queue

//The purpose of this code is to let AcyMailing send an e-mail to a specific user at a specific time.
//You just have to add an entry in the queue and AcyMailing will take care of the rest.
$memberid = '23'; //ID of the Joomla User or user e-mail (this code supposes that the user is already inserted in AcyMailing!)
$mailid = '45'; //ID of the Newsletter you want to add in the queue
$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)
if(!include_once(rtrim(JPATH_ADMINISTRATOR,DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.'components'.DIRECTORY_SEPARATOR.'com_acymailing'.DIRECTORY_SEPARATOR.'helpers'.DIRECTORY_SEPARATOR.'helper.php')){ 
    echo 'This code can not work without the AcyMailing Component'; 
    return false; 
}
$userClass = acymailing_get('class.subscriber');
$subid = $userClass->subid($memberid); //this function returns the ID of the user stored in the AcyMailing table from a Joomla User ID or an e-mail address 
if(empty($subid)) return false; //we didn't find the user in the AcyMailing tables
$db= JFactory::getDBO();
$db->setQuery('INSERT IGNORE INTO #__acymailing_queue (`subid`,`mailid`,`senddate`,`priority`) VALUES ('.$db->Quote($subid).','.$db->Quote($mailid).','.$db->Quote($senddate).',1)');
$db->query();

Sometimes you want to send a pre-saved Newsletter to a single user only... In that case you should not bother with the queue system and use this code (it will send the Newsletter ID 67 to the user "user@example.com"):

if(!include_once(rtrim(JPATH_ADMINISTRATOR,DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.'components'.DIRECTORY_SEPARATOR.'com_acymailing'.DIRECTORY_SEPARATOR.'helpers'.DIRECTORY_SEPARATOR.'helper.php')){ 
    echo 'This code can not work without the AcyMailing Component'; 
    return false; 
}
$mailer = acymailing_get('helper.mailer');
$mailer->report = true; //set it to true or false if you want Acy to display a confirmation message or not (message successfully sent to...)
$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)
$mailer->autoAddUser = false; //set it to true if you want Acy to automatically create the user if it does not exist in AcyMailing
$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 message.
$mailer->sendOne(67,'user@example.com'); //The first parameter is the ID of the Newsletter you want to send or its namekey

Create a list

$newlist = new stdClass();
$newlist->name = 'Your list name';
$newlist->description = 'Your list description'; //this parameter is optional
if(!include_once(rtrim(JPATH_ADMINISTRATOR,DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.'components'.DIRECTORY_SEPARATOR.'com_acymailing'.DIRECTORY_SEPARATOR.'helpers'.DIRECTORY_SEPARATOR.'helper.php')){ 
    echo 'This code can not work without the AcyMailing Component'; 
    return false; 
}
$listClass = acymailing_get('class.list');
$listid = $listClass->save($newlist); //This function will create the list and return the ID of the created list

Delete a list

//This code will not only delete a list but all elements related to that list (it won't delete users or newsletters, but only the fact a Newsletter is attached to that list or a subscriber subscribed to that list)
if(!include_once(rtrim(JPATH_ADMINISTRATOR,DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.'components'.DIRECTORY_SEPARATOR.'com_acymailing'.DIRECTORY_SEPARATOR.'helpers'.DIRECTORY_SEPARATOR.'helper.php')){ 
    echo 'This code can not work without the AcyMailing Component'; 
    return false; 
}
$listClass = acymailing_get('class.list');
$listClass->delete(LIST_ID); //You should replace LIST_ID by the ID of the list you want to delete

How to load the Joomla API

If you want to use the Acymailing API without Joomla, you first need to include the Joomla API. Please add these lines first in your script and don't forget to replace "PATH_TO_YOUR_JOOMLA_SITE_ROOT_FOLDER" by the real value:

define('_JEXEC', 1);
define('DS', DIRECTORY_SEPARATOR);
if (file_exists(dirname(__FILE__) . '/defines.php')) { 
    include_once dirname(__FILE__) . '/defines.php';
}
if (!defined('_JDEFINES')) { 
    define('JPATH_BASE', 'PATH_TO_YOUR_JOOMLA_SITE_ROOT_FOLDER'); 
    require_once JPATH_BASE.'/includes/defines.php';
}
require_once JPATH_BASE.'/includes/framework.php';
$app = JFactory::getApplication('site');

Last updated 4 years ago

Create a newsletter tag