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
  • Base files
  • Define the insertion options
  • Dynamically insert a content common to all receivers
  • Dynamically insert a content based on the receiver
  1. Developers
  2. Making a custom add-on

Insert a dynamic text in an email for WordPress

This step by step guide shows you how to develop your own plugin, allowing you to insert user-based data or data common to all receivers in your emails.

PreviousInsert a custom block in an email for JoomlaNextInsert a custom block in an email for WordPress

Last updated 4 months ago

Sometimes it can be useful to insert texts based on the receiver of a campaign, most commonly their name for example to have a less generic email.

You may want to insert data stored in an other plugin, for example a user birthday, purchased product, booked event, etc...

Here is an example with a user field:

For this step by step guide, we will take two simple examples and make a plugin allowing us to insert:

  • the current month name

  • the WordPress user name

Base files

Before continuing, make sure you created a custom add-on by following this guide:

In the file plugin.php, add the following method to your class:

public function __construct()
{
    parent::__construct();

    $this->pluginDescription->name = 'Example add-on';
    $this->pluginDescription->category = 'Anything';
    $this->pluginDescription->description = '- Insert month and user name in emails';
}

The name set on line 5 will be shown as a new "Dynamic text type"

Define the insertion options

For your integration to be visible in the editor, you will need to add the following method to your plugin.php file:

public function dynamicText($mailId)
{
    return $this->pluginDescription;
}

If you want your integration to only be visible on some types of emails for example, you can use the $mailId variable to test it and return nothing to hide it.

To define the insertion options that will be shown in the "Content to insert" part, you will need to add the following method:

public function textPopup()
{
    $insertionOptions = '<div class="grid-x acym__popup__listing">';
    $insertionOptions .= '<div onclick="setTag(\'{'.$this->name.':month}\', jQuery(this));" class="cell acym__row__no-listing acym__listing__row__popup">Current month</div>';
    $insertionOptions .= '<div onclick="setTag(\'{'.$this->name.':name}\', jQuery(this));" class="cell acym__row__no-listing acym__listing__row__popup">User name</div>';
    $insertionOptions .= '</div>';

    echo $insertionOptions;
}

This method needs to display your insertion options using HTML. It can be however you want, the most important thing is to call the JavaScript function "setTag" with a shortcode containing a unique value for what we want to insert (in this example, "month" and "name").

At this point, your plugin.php file should look like this:

<?php

use AcyMailing\Core\AcymPlugin;

class plgAcymExampleaddon extends AcymPlugin
{
    public function __construct()
    {
        parent::__construct();

        $this->pluginDescription->name = 'Example add-on';
        $this->pluginDescription->category = 'Anything';
        $this->pluginDescription->description = '- Insert month and user name in emails';
    }

    public function dynamicText($mailId)
    {
        return $this->pluginDescription;
    }

    public function textPopup()
    {
        $insertionOptions = '<div class="grid-x acym__popup__listing">';
        $insertionOptions .= '<div onclick="setTag(\'{'.$this->name.':month}\', jQuery(this));" class="cell acym__row__no-listing acym__listing__row__popup">Current month</div>';
        $insertionOptions .= '<div onclick="setTag(\'{'.$this->name.':name}\', jQuery(this));" class="cell acym__row__no-listing acym__listing__row__popup">User name</div>';
        $insertionOptions .= '</div>';
    
        echo $insertionOptions;
    }
}

If you activate your plugin, your insertion options should already be visible in the AcyMailing editor:

Dynamically insert a content common to all receivers

In this example, we chose to insert the current month. Since it will be the same for all receivers, we can use the method "replaceContent" which uses less resources:

public function replaceContent(&$email, $send = true)
{
    $extractedTags = $this->pluginHelper->extractTags($email, $this->name);
    if (empty($extractedTags)) {
        return;
    }

    $tags = [];
    foreach ($extractedTags as $i => $oneTag) {
        if (isset($tags[$i])) {
            continue;
        }
        
        // Your code here
        if ($oneTag->id === 'month') {
            $tags[$i] = date('F');
        }
    }

    $this->pluginHelper->replaceTags($email, $tags);
}

In this example, you just need to modify the loop content near line 14. Note that the $email parameter contains the current email information, and the $send parameter tells you if the email is about to be sent (true) or if we just want to display a preview (false).

You should always set a new value to $tags[$i] to replace the shortcode in the sent email.

At this point, inserting the month should work and a preview should be visible in the blue label. Inserting the user name should display the shortcode instead since we haven't added the code to replace it yet:

Dynamically insert a content based on the receiver

To insert a text based on the receiver, we need to use the method "replaceUserInformation" that is called for every recipient. The current email and the AcyMailing user objects are passed to help you find the data you want to insert:

public function replaceUserInformation(&$email, &$user, $send = true)
{
    $extractedTags = $this->pluginHelper->extractTags($email, $this->name);
    if (empty($extractedTags)) {
        return;
    }

    $wordpressUser = null;

    if (!empty($user->cms_id)) {
        // We store the WordPress user id in cms_id when it exists
        $wordpressUser = acym_loadObject('SELECT * FROM #__users WHERE ID = '.intval($user->cms_id));
    }

    if (empty($wordpressUser)) {
        // We could also try to find the WordPress user by its email address
        $wordpressUser = acym_loadObject('SELECT * FROM #__users WHERE `user_email` = '.acym_escapeDB($user->email));
    }

    $tags = [];
    foreach ($extractedTags as $i => $oneTag) {
        if (isset($tags[$i])) {
            continue;
        }

        $contentToInsert = '';

        if ($oneTag->id === 'name' && !empty($wordpressUser)) {
            $contentToInsert = $wordpressUser->display_name;
        }

        $tags[$i] = $contentToInsert;
    }

    $this->pluginHelper->replaceTags($email, $tags);
}

You should only need to modify lines 28 to 30 and set the value that should be inserted into the variable $contentToInsert.

In this example, lines 8 to 18 we try to get the WordPress user information ahead, to avoid doing it in the loop.

At this point your integration is ready and the WordPress user name should be inserted correctly:

The entire code for plugin.php should look like this:

<?php

use AcyMailing\Core\AcymPlugin;

class plgAcymExampleaddon extends AcymPlugin
{
    public function __construct()
    {
        parent::__construct();

        $this->pluginDescription->name = 'Example add-on';
        $this->pluginDescription->category = 'Anything';
        $this->pluginDescription->description = '- Insert month and user name in emails';
    }

    public function dynamicText($mailId)
    {
        return $this->pluginDescription;
    }

    public function textPopup()
    {
        $insertionOptions = '<div class="grid-x acym__popup__listing">';
        $insertionOptions .= '<div onclick="setTag(\'{'.$this->name.':month}\', jQuery(this));" class="cell acym__row__no-listing acym__listing__row__popup">Current month</div>';
        $insertionOptions .= '<div onclick="setTag(\'{'.$this->name.':name}\', jQuery(this));" class="cell acym__row__no-listing acym__listing__row__popup">User name</div>';
        $insertionOptions .= '</div>';

        echo $insertionOptions;
    }

    public function replaceContent(&$email, $send = true)
    {
        $extractedTags = $this->pluginHelper->extractTags($email, $this->name);
        if (empty($extractedTags)) {
            return;
        }

        $tags = [];
        foreach ($extractedTags as $i => $oneTag) {
            if (isset($tags[$i])) {
                continue;
            }

            // Your code here
            if ($oneTag->id === 'month') {
                $tags[$i] = date('F');
            }
        }

        $this->pluginHelper->replaceTags($email, $tags);
    }

    public function replaceUserInformation(&$email, &$user, $send = true)
    {
        $extractedTags = $this->pluginHelper->extractTags($email, $this->name);
        if (empty($extractedTags)) {
            return;
        }

        $wordpressUser = null;

        if (!empty($user->cms_id)) {
            // We store the WordPress user id in cms_id when it exists
            $wordpressUser = acym_loadObject('SELECT * FROM #__users WHERE ID = '.intval($user->cms_id));
        }

        if (empty($wordpressUser)) {
            // We could also try to find the WordPress user by its email address
            $wordpressUser = acym_loadObject('SELECT * FROM #__users WHERE `user_email` = '.acym_escapeDB($user->email));
        }

        $tags = [];
        foreach ($extractedTags as $i => $oneTag) {
            if (isset($tags[$i])) {
                continue;
            }

            $contentToInsert = '';

            if ($oneTag->id === 'name' && !empty($wordpressUser)) {
                $contentToInsert = $wordpressUser->display_name;
            }

            $tags[$i] = $contentToInsert;
        }

        $this->pluginHelper->replaceTags($email, $tags);
    }
}

Making a custom add-on