README

Campaign management for surveys with SMS and email invitations for Craft CMS 5.x.

License

This is a commercial plugin licensed under the Craft License. It will be available on the Craft Plugin Store soon. See LICENSE.md for details.

⚠️ Pre-Release

This plugin is in active development and not yet available on the Craft Plugin Store. Features and APIs may change before the initial public release.

Features

Campaign Management: Create and manage survey campaigns linked to Formie forms
- Multi-site support with site-specific recipients
- Campaign types for organization
- Configurable invitation delay and expiry periods
Recipient Management:
- Import recipients from CSV files
- Add individual recipients manually
- Track invitation status (sent, opened, submitted)
- Unique invitation codes per recipient
- Export recipients to CSV/JSON/Excel
Multi-Channel Invitations:
- SMS invitations via SMS Manager
- Email invitations with customizable templates
- Bitly URL shortening for SMS links
Queue-Based Processing:
- Batch processing for large recipient lists
- Background job execution
- Progress tracking
Analytics Dashboard:
- Overview stats (recipients, invitations, opens, submissions)
- Daily activity charts
- Channel distribution (Email/SMS/Both)
- Engagement tracking over time
- Conversion funnel visualization
- Campaign performance comparison
- Ratings tab (when formie-rating-field is enabled): per-campaign NPS / Star / Emoji rating analytics with rating field picker, distribution chart (donut for NPS, bar for star/emoji), trend chart, and per-campaign breakdown table
- Multi-section export: Excel (multi-sheet: Summary / Per Campaign / Raw Responses), CSV (ZIP of per-section CSVs), JSON (nested with all sections); Raw Responses includes per-recipient detail (campaign, site, send/response dates, rating value)
- Filter by campaign, site, and date range; Ratings tab also supports a "Date based on" filter (Send activity vs. Response date)
- Optional Craft dashboard widgets for analytics summary and campaign performance, with date-range and site filters
Survey Response Tracking:
- Link Formie submissions to recipients
- Track survey completion rates
- Invitation expiry handling
- View responses directly in campaign edit page
User Permissions: Granular access control for campaigns, recipients, analytics, and settings
Logging: Structured logging via Logging Library with configurable levels

Requirements

Craft CMS 5.0 or greater
PHP 8.2 or greater
Formie 3.0 or greater
SMS Manager 5.0 or greater (for SMS invitations)
Logging Library 5.0 or greater (installed automatically)
Plugin Base 5.0 or greater (installed automatically)

Installation

Via Composer (Development)

Until published on Packagist, install directly from the repository:

cd /path/to/project
composer config repositories.campaign-manager vcs https://github.com/LindemannRock/craft-campaign-manager
composer require lindemannrock/craft-campaign-manager:dev-main
./craft plugin/install campaign-manager

Via Composer (Production - Coming Soon)

Once published on Packagist:

cd /path/to/project
composer require lindemannrock/craft-campaign-manager
./craft plugin/install campaign-manager

Via Plugin Store (Future)

Go to the Plugin Store in your Craft control panel
Search for "Campaign Manager"
Click "Install"

Configuration

Settings

Navigate to Campaign Manager → Settings in the control panel to configure:

General Settings:

Plugin Name: Customize the display name in the control panel
Campaign Section Handle: The section handle where campaigns are stored

Bitly Settings:

Bitly API Key: API key for URL shortening (environment variable recommended)

Logging Settings:

Log Level: debug, info, warning, error

Environment Variables

# .env
BITLY_API_KEY=your-bitly-api-key

Config File

Create a config/campaign-manager.php file to override default settings:

<?php
return [
    // Plugin Settings
    'pluginName' => 'Campaign Manager',
    'campaignSectionHandle' => 'campaigns',

    // Logging Settings
    'logLevel' => 'error',

    // Multi-environment support
    'dev' => [
        'logLevel' => 'debug',
    ],
    'production' => [
        'logLevel' => 'error',
    ],
];

Setup

1. Create Campaign Section

Create a Craft section for campaigns with the following fields:

Campaign Type (Dropdown): Type categorization
Form (Formie Form): The survey form
Invitation Delay Period (Text): ISO 8601 duration (e.g., P1D for 1 day)
Invitation Expiry Period (Text): ISO 8601 duration (e.g., P30D for 30 days)
SMS Invitation Message (Plain Text): SMS template with {invitationUrl} and {customer_name} tokens
Email Invitation Subject (Plain Text): Email subject line
Email Invitation Message (Rich Text): Email template with tokens
Sender ID (Text): SMS sender ID handle
Surveys Welcome (Rich Text): Message shown before survey
Surveys Already Responded (Rich Text): Message for completed surveys
Surveys Invitation Expired (Rich Text): Message for expired invitations

2. Configure Plugin Settings

Navigate to Campaign Manager → Settings
Set the Campaign Section Handle to match your section
Configure Bitly API key if using SMS invitations

3. Create Survey Template

Create a template for the survey page (e.g., templates/survey.twig):

{% extends '_layouts/surveys.twig' %}

{% block content %}
    {% set invitationCode = craft.app.request.getQueryParam('code') %}

    {% if invitationCode %}
        {% set recipient = campaignManager.recipients.getRecipientByInvitationCode(invitationCode) %}
        {% set campaign = recipient.getCampaign() %}

        {% if recipient.hasSubmission() %}
            {{ campaign.surveysAlreadyResponded|raw }}
        {% elseif recipient.invitationIsExpired() %}
            {{ campaign.surveysInvitationExpired|raw }}
        {% else %}
            {{ campaign.surveysWelcome|raw }}
            {{ craft.formie.renderForm(campaign.getForm()) }}
        {% endif %}
    {% else %}
        <p>Invalid invitation code.</p>
    {% endif %}
{% endblock %}

Usage

Managing Campaigns

Navigate to Campaign Manager in the control panel
Click New Campaign to create a campaign entry
Configure the campaign settings and associated form
Save the campaign

Adding Recipients

Single Recipient

Navigate to the campaign's recipient list
Click Add → New Recipient
Enter recipient details (name, email, phone, site)
Save

Import from CSV

Navigate to the campaign's recipient list
Click Add → Import from CSV
Upload a CSV file with columns:
- Name (required)
- Email (optional)
- Phone (optional)
- Site (optional: site handle like en, ar or site ID like 1, 2)
Choose whether to send invitations after import
Click Import

CSV Format Example:

Name,Email,Phone,Site
John Doe,john@example.com,96512345678,en
Ahmed Ali,ahmed@example.com,96598765432,ar

Running Campaigns

Single Campaign

Navigate to the campaign's recipient list
Click Run Campaign
Invitations will be queued and sent in batches

All Campaigns

Navigate to Campaign Manager → Campaigns
Click Run All
All campaigns will be processed

Viewing Analytics

Navigate to Campaign Manager → Analytics
Use filters to select campaign, site, and date range
View metrics across four tabs:
- Overview: Key stats and campaign performance table
- Delivery: Daily activity and channel distribution
- Engagement: Open rates over time
- Conversion: Funnel visualization and breakdown
Export data using the Export button

How Responses Are Linked to Recipients

When a recipient submits the form from their invitation link, Campaign Manager links that Formie submission to the recipient. A submission is linked only when all of these are true:

The code in the page URL belongs to a recipient
The submitted form is the form assigned to the recipient's campaign
The submission was made on the recipient's site
The invitation has not expired
The recipient has no linked response yet

The first valid response is kept. Later submissions with the same invitation code never replace it.

Note

Campaign Manager never blocks a Formie submission. When a submission does not meet these conditions, Formie still saves it and still sends its notifications and integrations — it just isn't linked to a recipient or counted as a campaign response.

For headless or custom front ends, keep the code query parameter on the request that submits the form, and submit with the recipient's site.

Viewing Responses

Navigate to a campaign and click Edit
Click the Responses tab
View all recipients who submitted the form
Click "View" to see full submission details in Formie

Exporting Recipients

Navigate to the campaign's recipient list
Click Export
Choose format (CSV, JSON, or Excel)
Download includes all recipient data and status

Template Variables

campaignManager.campaigns

{# Get all campaigns #}
{% set campaigns = campaignManager.campaigns.find().all() %}

{# Get campaign by ID #}
{% set campaign = campaignManager.campaigns.find().id(123).one() %}

{# Get campaigns for a site #}
{% set campaigns = campaignManager.campaigns.find().site('en').all() %}

campaignManager.recipients

{# Get recipient by invitation code #}
{% set recipient = campaignManager.recipients.getRecipientByInvitationCode(code) %}

{# Mark recipient as opened #}
{% do campaignManager.recipients.markAsOpened(recipient) %}

{# Check recipient status #}
{% if recipient.hasSubmission() %}
    {# Already submitted #}
{% elseif recipient.invitationIsExpired() %}
    {# Invitation expired #}
{% endif %}

{# Get recipients with submissions for a campaign #}
{% set respondents = campaignManager.recipients.getWithSubmissions(campaignId, siteId) %}

Console Commands

Campaigns are run through the Control Panel or via the queue worker. There are no dedicated CLI commands for this plugin at this time.

Permissions

Campaign Permissions

Manage campaigns (grants campaign list access)
- Create campaigns
- Edit campaigns
- Delete campaigns
- Run campaigns

Recipient Permissions

Manage recipients (grants recipient list access)
- Add recipients
- Import recipients
- Export recipients
- Delete recipients

Analytics Permissions

View analytics
- Export analytics

Logs Permissions

View logs
- View system logs
  - Download system logs
- View activity logs
  - Download activity logs
  - Clear activity logs

Settings Permissions

Manage settings

Site Access

On a multi-site install, Campaign Manager permissions work together with Craft's own site permissions. A Campaign Manager permission decides what a user can do; Craft's Sites permissions (Edit “Site name”) decide where they can do it.

For example, a user with Edit campaigns and Delete recipients who can only edit the French site can change the French version of a campaign and delete French recipients, but cannot open, change, or run anything on the other sites. Deleting a campaign is different, because a campaign is shared by every site; see below.

This applies everywhere in the control panel:

Campaigns: opening, saving, deleting, and running a campaign require access to the site being worked on. Running without choosing a site queues only the sites the user can edit.
Recipients: lists, the add and import screens, and deletion only reach recipients on sites the user can edit. When a bulk delete includes recipients from other sites, those recipients are left in place and reported as not deleted.
Analytics and responses: "All Sites" means all sites the user can edit, including the Analytics and Responses tabs on a campaign. A user who cannot edit any site sees no campaigns and no numbers.
Dashboard widgets: a widget checks its chosen site every time it loads. If the user loses access to that site, the widget shows No data available until they pick another site in the widget settings.
Activity logs: every log records which sites it covers. A user sees a log only when they can edit every site it covers, so a bulk delete or an export that touched two sites is shown only to users who can edit both. Logs that cover every site (saving or deleting a campaign) and logs written before site coverage was recorded are shown only to users who can edit every site. Clearing the logs removes the logs of every site, so Clear activity logs also requires being able to edit every site.

Users who can edit every site are not affected. To give someone access to a site, grant the matching Edit site permission under Settings → Users → User Groups (or on the user's Permissions tab).

Front-end templates and code that call craft.campaignManager.analytics directly are not tied to a control panel user for the per-campaign statistics: getCampaignStats() and getCampaignDailyTrend() cover every site when no site is given, as before. The control panel passes the user's editable sites to them explicitly.

A campaign exists on every site, the same way a Craft entry can. Saving it on one site also updates the settings that are shared between sites, and deleting it from any site the user can edit deletes the campaign on every site.

Events

use lindemannrock\campaignmanager\services\RecipientsService;
use lindemannrock\campaignmanager\events\RecipientEvent;
use yii\base\Event;

// Before sending invitation
Event::on(
    RecipientsService::class,
    RecipientsService::EVENT_BEFORE_SEND_INVITATION,
    function(RecipientEvent $event) {
        // Access: $event->recipient, $event->campaign
        // Set $event->isValid = false to cancel
    }
);

// After sending invitation
Event::on(
    RecipientsService::class,
    RecipientsService::EVENT_AFTER_SEND_INVITATION,
    function(RecipientEvent $event) {
        // Access: $event->recipient, $event->success
    }
);

Troubleshooting

Invitations Not Sending

Check SMS Manager is configured: Ensure providers and sender IDs are set up
Check Bitly API key: Required for SMS URL shortening
Check queue is running: ./craft queue/run
Check logs: Campaign Manager → Logs

Survey Page Not Loading

Verify invitation code: Check the URL has a valid code parameter
Check recipient exists: The invitation code must match a recipient record
Check campaign has form: The campaign must have a Formie form assigned

Response Saved in Formie but Not Linked to a Recipient

Symptom: A submission appears in Formie, but the recipient still shows no response and the campaign's response count did not change.

Quick checks:

Invitation code: The request that submitted the form must include the recipient's code query parameter. Custom templates and headless front ends need to keep it on the submit request.
Form: The submitted form must be the one assigned to the recipient's campaign.
Site: The submission must be made on the recipient's site.
Expiry: The invitation must not have expired.
Earlier response: A recipient keeps their first linked response. Later submissions with the same code are saved by Formie but not linked.

Fix: For a missing code, wrong form, or wrong site, correct the cause and have the recipient submit again from their invitation link. An expired invitation, or a recipient who already has a linked response, cannot be linked again. With the log level set to Warning, Info, or Debug, Campaign Manager → Logs records why a submission with an invitation code was not linked.

Why: Invitation links are personal, so a response is only counted for the recipient, form, and site it was issued for, and only once.

CSV Import Failing

Check CSV format: Must have Name column at minimum
Check encoding: Use UTF-8 encoding for special characters
Check file size: Large files are processed in batches

Settings Save Shows a Validation Error

Numeric settings such as activity log retention, activity log limits, and items per page must be whole numbers within the allowed range. If a value is invalid, Campaign Manager keeps you on the same settings page and shows the field error inline.

When a setting is overridden in config/campaign-manager.php, the Control Panel field is skipped during save. Change the config file value instead.

Bitly URLs Not Working

Verify API key: Check BITLY_API_KEY environment variable
Check API limits: Bitly has rate limits on free plans
Fallback: If Bitly fails, original URLs are used

Logging

Campaign Manager uses the LindemannRock Logging Library for system logging.

Log Levels

Error: Critical errors only (default)
Warning: Errors and warnings
Info: General information
Debug: Detailed debugging (requires devMode)

Log Files

Location: storage/logs/campaign-manager-YYYY-MM-DD.log
Retention: 30 days (automatic cleanup)
Web Interface: View logs at Campaign Manager → Logs

Support

Documentation: https://github.com/LindemannRock/craft-campaign-manager
Issues: https://github.com/LindemannRock/craft-campaign-manager/issues
Email: support@lindemannrock.com

License

This plugin is licensed under the Craft License. See LICENSE.md for details.

Developed by LindemannRock

lindemannrock / craft-campaign-manager

Package info

Security

Statistics

README

License

⚠️ Pre-Release

Features

Requirements

Installation

Via Composer (Development)

Via Composer (Production - Coming Soon)

Via Plugin Store (Future)

Configuration

Settings

Environment Variables

Config File

Setup

1. Create Campaign Section

2. Configure Plugin Settings

3. Create Survey Template

Usage

Managing Campaigns

Adding Recipients

Single Recipient

Import from CSV

Running Campaigns

Single Campaign

All Campaigns

Viewing Analytics

How Responses Are Linked to Recipients

Viewing Responses

Exporting Recipients

Template Variables

campaignManager.campaigns

campaignManager.recipients

Console Commands

Permissions

Campaign Permissions

Recipient Permissions

Analytics Permissions

Logs Permissions

Settings Permissions

Site Access

Events

Troubleshooting

Invitations Not Sending

Survey Page Not Loading

Response Saved in Formie but Not Linked to a Recipient

CSV Import Failing

Settings Save Shows a Validation Error

Bitly URLs Not Working

Logging

Log Levels

Log Files

Support

License