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.
Create a newsletter tag
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 :
You can then modify the installed file plugins/acymailing/example.php and plugins/acymailing/example.xml to meet your needs.
Functions are called if they exist, you don't have to define them all. If you don't want to display interface but simply want to modify the content, then don't add the acymailing_getPluginType() function.
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;
}
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.
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 a Newsletter is added to the queue
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 or remove a user from one or several lists
$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);
Create a Newsletter
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();
Send a Newsletter to a single user
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: