#17

Product support

Visit this product's website for support.

Categories

  • Marketing

This plugin allows you to create and design fully custom email campaigns and send them to end users. Campaigns can be sent to users who can sign up to mailing lists using a front-end component, or as part of a predefined collection of recipients, for example, all front-end users.

This table describes the moving parts found in this plugin:

Object Description
Campaign A copy of the message sent to the subscriber.
Campaign Template The HTML scaffolding template used by a Campaign.
Subscriber An individual person, their email address and name.
Subscriber List A mailing list that subscribers can opt-in to.
Recipient Group Like a List but emails are generated by the system, for example All registered users.

Launching a campaign

When you create a campaign for the first time, it will ask if you want to generate a default campaign template in the current theme. This will provide some sample content you can use to get started.

After naming your campaign, you are free to populate the message content as many times are you like. You can also preview the message by clicking the Send test message button.

Once you are ready to send the message click the Launch campaign button where you can select which subscribers should receive the campaign message. There are also several launch options available:

  • Delayed launch - If this is checked, a date picker will appear and you can select an exact date and time to send the message. This is good for perfectly timing your campaign.

  • Staggered launch - If this is checked, the campaign subscribers will be divided in to smaller groups depending on the selected time period. Each group will be contacted every hour until all subscribers have been sent the message.

  • Repeating campaign - This option is particularly useful if you are generating the message content dynamically, for example, a message that contains the latest blog posts on your site. If this is checked, the campaign will duplicate itself after it has launched and automatically apply the Delayed launch option to match the repeating frequency. This will continue perpetually until you manually cancel the most recent iteration.

Campaign status meanings

A campaign will have many statuses through its life time, they are described in detail below:

  • Draft - the campaign is still having content added and the design may be changing. This is the only status where content can be modified.

  • Pending - for campaigns that use a delayed launch time, it will stay in this status until the specified launch date has passed. Campaigns in this status are checked every hour.

  • Active - campaign is in progress, there are messages still queued to be sent to the subscribers. Some subscribers may have received the message. Staggered campaigns may stay in this status for some time.

  • Sent - the campaign is complete, all subscribers should have received the message. Information about the subscriber is recorded, such as whether they opened the email or whether they unsubscribed because of this email.

  • Deleted - the campaign has been cancelled while it was active or before it reached the launch date.

  • Archived - the campaign is now old and doesn't need to be seen any more. All recorded about subscriber activity has been deleted.

System requirements

This plugin relies on the system schedule process for running its automated tasks. You should ensure that your cron table is configured correctly for this plugin to work. Alternatively you can manually process the campaign logic by calling php artisan campaign:run and run it every hour.

Implementing front-end subscription form

Use the campaignSignup component to display a subscription form on a page. The component has the following properties:

  • list - a campaign list code to subscribe the person to. Eg: followers
  • confirm - if this is checked, subscribers must confirm their email address before they are added to the list.

Here is some sample markup:

title = "My page"
url = "/mypage"

[campaignSignup]
list = "followers"
confirm = 0
==
<div id="container">
    <form
        data-request="campaignSignup::onSignup"
        data-request-update="'campaignSignup::result': '#container'">

        <!-- Optional first name -->
        <input name="first_name" type="text" placeholder="First name" />

        <!-- Optional last name -->
        <input name="last_name" type="text"  placeholder="Last name" />

        <!-- Required email address -->
        <input name="email" type="text"  placeholder="[email protected]" />

        <button class="btn btn-default" type="submit">Subscribe</button>

    </form>
</div>

Campaign Templates

Campaign Templates are managed in the CMS area and should be designed by a developer. Each template should use the campaignTemplate CMS Component and like any CMS page, they can support using other components for dynamically generating content.

title = "Default template"
url = "/campaign/message/:code"
description = "Campaign with basic fields"

[campaignTemplate]
==
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   "http://www.w3.org/TR/html4/loose.dtd">

    <html lang="en">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <title>Newsletter</title>
    </head>

    <body>
        {richeditor name="body" size="huge"}{/richeditor}
    </body>
</html>

There is a template build syntax, this lets you add form fields inside the template where the content can be added via the Campaign creation process. These tags are supported:

Text

Renders a single line editor field for smaller blocks of text.

{text name="websiteName" label="Website Name"}Our wonderful website{/text}

Textarea

Renders a multiple line editor field for larger blocks of text.

{textarea name="websiteDescription" label="Website Description"}This is our vision for things to come{/textarea}

Rich editor

Renders a WYSIWYG content editor.

{richeditor name="content" label="Main content"}Default text{/checkbox}

Markdown

Renders a Markdown content editor.

{markdown name="content" label="Markdown content"}Default text{/markdown}

File Upload

Renders a file upload editor field, the output value is the full path to the file.

{fileupload name="logo" label="Logo"}http://placehold.it/100x100{/fileupload}

Repeater

Renders a repeating section with other fields inside.

{repeater name="content_sections" prompt="Add another content section"}
    <h2>{text name="title" label="Title"}Title{/text}</h2>
    <p>{textarea name="content" label="Content"}Content{/textarea}</p>
{/repeater}

For more details on syntax fields, see the Parser section of the October documentation.

Creating new recipient groups

Plugins can extend the Campaign plugin with new recipient groups. These are like predefined subscriber lists that list their subscribers dynamically by the system. New groups are registered with the API events triggered by the Campaign plugin. The event handlers should be defined in the boot() method of the plugin registration file. There are three events that should be handled in the plugin.

  • responsiv.campaign.listRecipientGroups event handler should return a list of new recipient groups supported by the plugin.
  • responsiv.campaign.getRecipientsData event handler "resolves" a recipient group information and returns the actual email and name of each subscriber.

The next example shows an event handler registration code for a plugin. The plugin registers two recipient groups. As you can see, the plugin uses the Customer class to handle the events. That's a recommended approach.

public function boot()
{
    Event::listen('responsiv.campaign.listRecipientGroups', function() {
        return [
            'my-plugin-all-customers' => 'All customers',
            'my-plugin-paid-customers' => 'Customers with paid orders',
        ];
    });

    Event::listen('responsiv.campaign.getRecipientsData', function($type) {
        if ($type == 'my-plugin-all-customers')
            return Customer::getAllCustomers();

        if ($type == 'my-plugin-paid-customers')
            return Customer::getPaidCustomers();
    });
}
Registering new recipient groups

New recipient groups can be registered with the responsiv.campaign.listRecipientGroups event handler. The handler should return an associative array with the type codes in indexes and the names in values. It is highly recommended to use the plugin name for the type code, to avoid conflicts with other plugins. For example:

[
    'my-plugin-recipient-type' => 'My plugin recipient type',
]
Returning information about an recipient collection

Plugins should provide detailed information about the supported recipient types with the responsiv.campaign.getRecipientsData event handlers. The handler gets a single parameter - the recipient type code (one of the codes you registered with the responsiv.campaign.listRecipientGroups handler). The handler code must check whether the requested item type code belongs to the plugin. The handler should return an associative array in the following format:

Array (
    [recipients] => Array (
        [email protected]' => ['first_name' => 'Some', 'last_name' => 'Person'],
        [email protected]' => ['first_name' => 'Another', 'last_name' => 'Person'],
        [...]
    )
)
Extending the unsubscribe event

You may hook the responsiv.campaign.beforeUnsubscribe event if you want to use your own logic called when a user unsubscribes. This event can override the default behavior by returning a response, which is then passed to the user's browser.

Event::listen('responsiv.campaign.beforeUnsubscribe', function(
    $component,
    $subscriber,
    $campaign
) {
    // ...
});
  • Found the plugin useful on 19 Aug, 2015

    100$ is nothing for this plugin. It works perfect. Schedules your email campaigns sends them to your subscribers and shows you how many of them opened it or how many people unsubscribe you. It is so detailed project and it definitely worths.

1.1.22

Fixes exception when opening a deleted campaign in the browser.

Jan 25, 2017

1.1.21

Add a processing step to the campaign workflow. This fixes a bug where campaigns are marked as sent prematurely.

Nov 22, 2016

1.1.20

Recipient groups can now be added directly to lists.

Nov 22, 2016

1.1.19

Add event hook called when a user unsubscribes (responsiv.campaign.beforeUnsubscribe).

Oct 28, 2016

1.1.18

Fixes bug when creating a subscriber directly from a list.

Sep 21, 2016

1.1.17

Fixes minor bug preventing users from unsubscribing.

Sep 07, 2016

1.1.16

Subscribers can now be confirmed manually. Added filters to subscribers page.

Aug 19, 2016

1.1.15

The Template component can now specify a custom page for verify and unsubscribe actions.

Aug 16, 2016

1.1.14

Update main menu item to include SVG version.

Aug 14, 2016

1.1.13

Fixes issue where duplicate emails being sent for instant campaigns with large subscribers.

Jul 20, 2016

1.1.12

Fixes bug when sorting list by number of subscribers.

Jul 20, 2016

1.1.11

Compatibility with October stable.

Apr 01, 2016

1.1.10

Fixes subscriber search on list preview screen.

Feb 22, 2016

1.1.9

Add a checkbox to automatically confirm new subscribers in the back-end.

Dec 07, 2015

1.1.8

Subscribers are no longer automatically deleted after 14 days.

Aug 20, 2015

1.1.7

Added back-end permissions for managing campaigns and subscribers.

Aug 19, 2015

1.1.6

User interface improvements.

Aug 12, 2015

1.1.5

Improve caching of message content.

Aug 10, 2015

1.1.4

Subscriptions are now throttled allowing 3 requests every 15 minutes.

Aug 05, 2015

1.1.3

Prevent instances of data loss when the source template no longer exists or has changed.

Jul 27, 2015

1.1.2

Fixes a bug where launching against group subscribers will send to everyone.

Jul 27, 2015

1.1.1

Each campaign message will strictly send once per hour even if the worker is called multiple times.

Jul 24, 2015

1.1.0

Added subscriber import options. Subscriber IP addresses are now logged.

Jul 24, 2015

1.0.8

Staggered launch can now be performed for a fixed amount of messages sent every hour.

Jul 14, 2015

1.0.7

Improve the efficiency of the subscriber list page.

Jul 03, 2015

1.0.6

Fixes bug preventing a list from being deleted.

May 09, 2015

1.0.5

Minor fix for latest build.

Apr 28, 2015

1.0.4

Implement the verification process for new subscribers.

Apr 06, 2015

1.0.3

Seed all database tables

Mar 20, 2015

1.0.2

Set up database tables

Mar 20, 2015

1.0.1

First version of Campaign

Mar 20, 2015