AcyMailing
Our siteForumBlog
Latest version
Latest version
  • AcyMailing documentation
  • How to renew AcyMailing license?
  • How to switch AcyMailing license plan?
  • Setup AcyMailing
    • Update from AcyMailing 5
    • Installation
      • Download AcyMailing
      • Install AcyMailing
      • Update AcyMailing
      • Switching from Starter to a paid version
      • Uninstall AcyMailing
    • Move AcyMailing between websites
      • Migrate between Joomla! and WordPress
      • Move between two WordPress websites
      • Switch from Joomla 3 to Joomla 4/5
    • Configuration
      • License
      • Mail settings
        • Set up your DKIM : DomainKeys Identified Mail
        • Set up Oauth 2.0
      • Queue process
      • Configure your send process
      • Subscription
      • Bounce handling
      • Data collection
      • Security
      • Languages
    • Step by step guide
    • Multilingual websites
      • Translate AcyMailing
      • Custom translation
    • Subscription to your lists
      • Subscription form - Joomla
      • Subscription form - WordPress
      • Other subscription methods
      • RSForm!Pro integration
  • External sending methods
    • AcyMailing Sending Service
    • Amazon SES
    • ElasticEmail
    • Mailgun
    • Postmark
    • SendGrid
    • Brevo SMTP Relay
    • Brevo / Sendinblue (Legacy)
  • Main pages
    • Dashboard
    • Subscription forms
      • Subscription Form
      • Header
      • Footer
      • Popup
      • Shortcode (Wordpress)
    • Subscribers
      • Create a subscriber
      • Import subscribers
      • Export subscribers
    • Custom fields
      • Create Custom Field
      • Examples
    • Lists
      • Create a list
    • Segment
      • Edition
    • Emails
      • Creation of a campaign
        • Choose a template
        • Edit email
        • Recipients
        • Segment
        • Send settings
        • Tests
        • Summary
      • A/B testing
      • Automatic campaigns
      • Follow-up
        • Trigger
        • Condition
        • Emails
        • Summary
      • Special mails
    • The email editor
      • Tenor integration
      • Unsplash integration
    • Templates
      • Create a template
      • Import a template
    • Email overrides
      • Edition
    • Automations
      • Information
      • Conditions
      • Actions
      • Action targets
      • Summary
    • Scenario
      • Create a new Scenario
      • Performances
    • Queue
    • Statistics
      • Overview
      • Detailed Statistics
      • Click map
      • Links details
      • User click details
      • Statistics per list
    • Add-ons
    • Mailbox actions
      • Mailbox actions
        • Edition
      • Bounce rules
        • Configuration
        • Listing
        • Create bounce rules
  • Advanced
    • Send follow-up messages based on subscription
    • Let site users use AcyMailing
      • List management
      • User management
      • Campaigns management
    • Show an archive of the sent newsletters
    • Show a profile edition form on your site
    • Partner platform
      • Log in
      • Dashboard
      • Single domain details
  • Integrations
    • Settings
    • Joomla add-ons
      • Joomla articles
      • CB Subscriptions
      • Community Builder
      • Community Quiz
      • Community Surveys
      • Contacts
      • Dashboard Quick icon
      • Docman
      • DPCalendar
      • EasyBlog
      • EasyProfile
      • EasySocial
      • Event Booking
      • FLEXIcontent
      • HikaShop
      • iCagenda
      • JCal Pro
      • jDownloads
      • JEvents
      • JSW CRM
      • JTicketing
      • K2 Content
      • Membership Pro
      • Module
      • PayPlans
      • Phoca Download
      • RSEvents!Pro
      • Seblod
      • Shika
      • VirtueMart
      • Zoo
    • WordPress add-ons
      • WordPress posts and pages
      • Advanced Custom Fields (ACF)
      • Business Directory
      • Contact Form 7
      • Easy Digital Downloads
      • EventON
      • Events Manager
      • Gravity Forms
      • Learndash
      • MemberPress
      • Modern Events Calendar
      • The events calendar
      • Ultimate Member
      • Uncanny Automator
      • WooCommerce
    • All websites add-ons
      • Articles, posts and pages from WordPress and Joomla
      • Automation - export action
      • Create user
      • Custom headers
      • RSS and Atom feeds
      • Table of contents generator
      • Universal filter
    • Zapier
  • Developers
    • Developer Documentation
    • Making a custom add-on
      • Execute custom script on specific AcyMailing actions
      • Insert a dynamic text in an email for Joomla
      • Insert a custom block in an email for Joomla
      • Insert a dynamic text in an email for WordPress
      • Insert a custom block in an email for WordPress
    • Custom script using our code
    • Create a page override
    • Joomla quickstart package with AcyMailing
    • Customise inserted content
  • FAQ
    • Could not instantiate mail function - AcyMailing
    • Spam issue
    • Your send process is slow?
    • Compatibility issues
    • Mail archive not displaying special characters
Powered by GitBook
On this page
  • Before using our code
  • Making sure your CMS is loaded
  • Load the AcyMailing library
  • Subscribers
  • Create a new subscriber
  • Get a subscriber and / or its subscriptions
  • Lists
  • Create a list
  • Get the lists
  • Delete a list
  • Subscriptions
  • Subscribe or remove a user from one or several lists
  • Campaigns
  • Create a campaign
  • Sending a campaign to its lists
  • Sending emails
  • Insert an e-mail in the queue
  • Send an email to a single user
  1. Developers

Custom script using our code

This documentation shows you examples of PHP code you can use to perform actions in AcyMailing

PreviousInsert a custom block in an email for WordPressNextCreate a page override

Last updated 4 months ago

Before using our code

Making sure your CMS is loaded

If you want to use the AcyMailing code outside of your site, you will need to load your site's library then .

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');

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';

$container = \Joomla\CMS\Factory::getContainer();
$container->alias(\Joomla\Session\SessionInterface::class, 'session.web.site');
$app = $container->get(\Joomla\CMS\Application\SiteApplication::class);

Add these lines first in your script and don't forget to replace PATH_TO_YOUR_JOOMLA_SITE_ROOT_FOLDER by the real value, and to change $context if needed.

// site, administrator or cli, it depends on the way the script is called
$context = 'site';

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';

$contextConfig = [
    'site' => [
        'session' => 'session.web.site',
        'applicationClass' => \Joomla\CMS\Application\SiteApplication::class
    ],
    'administrator' => [
        'session' => 'session.web.administrator',
        'applicationClass' => \Joomla\CMS\Application\AdministratorApplication::class
    ],
    'cli' => [
        'session' => 'session.cli',
        'applicationClass' => \Joomla\Console\Application::class
    ]
];

$container = \Joomla\CMS\Factory::getContainer();
$container->alias('session', $contextConfig[$context]['session'])
          ->alias('JSession', $contextConfig[$context]['session'])
          ->alias(\Joomla\CMS\Session\Session::class, $contextConfig[$context]['session'])
          ->alias(\Joomla\Session\Session::class, $contextConfig[$context]['session'])
          ->alias(\Joomla\Session\SessionInterface::class, $contextConfig[$context]['session']);
          
          
$app = $container->get($contextConfig[$context]['applicationClass']);
\Joomla\CMS\Factory::$application = $app;

Add these lines first in your script and don't forget to replace PATH_TO_YOUR_WORDPRESS_SITE_ROOT_FOLDER by the real value

define('WP_USE_THEMES', false);
require('PATH_TO_YOUR_WORDPRESS_SITE_ROOT_FOLDER/wp-load.php');

Load the AcyMailing library

Before each of the following examples, please make sure the AcyMailing library is loaded.

$ds = DIRECTORY_SEPARATOR;
$initFile = rtrim(JPATH_ADMINISTRATOR, $ds).$ds.'components'.$ds.'com_acym'.$ds.'Core'.$ds.'init.php';
if (!include_once($initFile)) {
    echo 'This code can not work without the AcyMailing Component';
    return false;
}
$ds = DIRECTORY_SEPARATOR;
$initFile = WP_PLUGIN_DIR.$ds.'acymailing'.$ds.'back'.$ds.'Core'.$ds.'init.php';
if (!include_once($initFile)) {
    echo 'This code can not work without the AcyMailing plugin';
    return false;
}

Subscribers

Create a new subscriber

use AcyMailing\Classes\UserClass;

$myUser = new stdClass();
$myUser->email = 'address@example.com';
$myUser->name = 'example name'; // this information is optional
 
// 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:
// $myUser->confirmed = 1;
 
// You can add as many extra fields as you want if you already created them in AcyMailing
$customFields = [];
$customFields[custom_field_id] = 'france'; // the custom field id can be found in the Custom fields list of the AcyMailing admin page
//...
 
$userClass = new UserClass();
$userClass->sendConf = true; // Or false if you don't want a confirmation email to be sent
$userId = $userClass->save($myUser, $customFields); // this function will return you the ID of the user inserted in the AcyMailing table

Get a subscriber and / or its subscriptions

use AcyMailing\Classes\UserClass;

$userClass = new UserClass();
 
// Get the AcyMailing user from his email address
$user = $userClass->getOneByEmail($email);
 
// Or you can get the AcyMailing user from his site user ID
$user = $userClass->getOneByCMSId($userID);
 
// Get subscription
$userSubscriptions = $userClass->getUserSubscriptionById($user->id);
 
// If you need a simpler result, you can use this method
$userSubscriptions = $userClass->getSubscriptionStatus($user->id);

Lists

Create a list

use AcyMailing\Classes\ListClass;

$newList = new stdClass();
$newList->name = 'Your list name';
$newList->active = 1;
$newList->welcome_id = 43; // Optional. This is the Id of the mail you want to send as welcome email
$newList->unsubscribe_id = 52; // Optional. This is the Id of the mail you want to send when a user unsubscribes
$newList->color = '#3366ff'; // Optional. This is the color of the list
 
$listClass = new ListClass();
$listId = $listClass->save($newList); // This function will create the list and return the ID of the created list

Get the lists

use AcyMailing\Classes\ListClass;

$listClass = new ListClass;
$allLists = $listClass->getAll();
 
// You can then do a foreach on this variable (which contains an array of objects) and use ->name
// You can get a specific list like this
 
$myList = $listClass->getOneById(34);
 
// Or multiple lists like this
 
$myLists = $listClass->getListsByIds([22, 48]);

Delete a list

use AcyMailing\Classes\ListClass;

// This code will detach the list from your campaigns, delete the user subscriptions to that list then delete the list
 
$listClass = new ListClass();
$listClass->delete(43); // You should replace 43 by the ID of the list you want to delete

Subscriptions

Subscribe or remove a user from one or several lists

use AcyMailing\Classes\UserClass;

$subscribe = [2,4,6]; // Id of the lists you want the user to be subscribed to (can be empty)
$unsubscribe = [1,3]; // Id of the lists you want the user to be unsubscribe from (can be empty)
$acyUserId = '23'; // you can use the previous example code to get the user by its site user id or its email address
 
$userClass = new UserClass();
 
if(!empty($subscribe)){
    // The last two parameters are are to make sure to send the welcome email 
    $userClass->subscribe($acyUserId, $subscribe, true, true);
}
 
if(!empty($unsubscribe)){
    $userClass->unsubscribe($acyUserId, $unsubscribe);
}

Campaigns

Create a campaign

use AcyMailing\Classes\MailClass;
use AcyMailing\Classes\CampaignClass;

// Lists you want to attach the campaign to
$listIds = [3,5,8];
 
// We create the Campaign 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();
$mail->subject = 'your subject'; // Subject of your email
$mail->name = 'your campaign name'; // Name of the campaign
$mail->body = 'Hi folks, we have a big announcement...'; // Body of your email
$mail->bcc = 'example@test.com'; // BCC for your campaign
$mail->type = MailClass::TYPE_STANDARD; // Type of email
 
$mailClass = new MailClass();
$mailId = $mailClass->save($mail);
 
$campaign = new stdClass();
$campaign->draft = 1; // Create as a draft
$campaign->mail_id = $mailId;
$campaign->sending_type = CampaignClass::SENDING_TYPE_NOW; // Create a standard campaign
 
$campaignClass = new CampaignClass();
$campaignId = $campaignClass->save($campaign);
$campaignClass->manageListsToCampaign($listIds, $mailId);

Sending a campaign to its lists

use AcyMailing\Classes\CampaignClass;

$campaignClass = new CampaignClass();
$campaignId = $campaignClass->send($campaignId);

Sending emails

Insert an e-mail in the queue

use AcyMailing\Classes\QueueClass;
use AcyMailing\Classes\MailClass;

// 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.
 
$acyUserId = '23';
$mailId = '45'; // ID of the email 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 you want to add the email in the queue only for one specific user
$queueClass = new QueueClass();
$queueClass->addQueue($acyUserId, $mailId, acym_date($sendDate, 'Y-m-d H:i', false));
 
// If you want to send the email to all the users subscribed to the list the email is attached to, you can use this:
$mailClass = new MailClass();
$mailToSend = $mailClass->getOneById($mailId);
$mailToSend->sending_date = acym_date($sendDate, 'Y-m-d H:i', false);
$mailToSend->parent_id = $mailId;
$mailToSend->sending_params = [''];
$queueClass->queue($mailToSend);

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 "user@example.com"):

The email ID can be found in the xxxx_acym_mail table, this is NOT the campaign ID displayed on the campaigns listing

use AcyMailing\Helpers\MailerHelper;

$mailer = new MailerHelper();
$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 email
$mailer->sendOne(67, 'user@example.com'); // The first parameter is the ID of the email you want to send
the AcyMailing library