Custom newsletter backend

From GroupScript documentation

Jump to: navigation, search

Since version 4.0 you can send newsletters using Built-in newsletter backend (which is subject to your server limitations and is not recommended if you have very high subscriber count) or MailChimp. If you wish to use another API, you need to create a custom newsletter backend.

Contents

Getting started

1. Create a file called example_newsletter_backend.php . This file must contain a class which is named after the filename. The class should contain at least these three methods (Note: We are using the name example_newsletter_backend.php purely as an example, you have to replace example with real newsletter backend name):

<?php
include_once(APPPATH . '/newsletter_backends/base_newsletter_backend.php');

class Example_newsletter_backend extends Base_newsletter_backend {

    public function name() {
         return _('Example.com');
    }
    
    public function send_test_newsletter($campaign, $email) {
		
	}
    public function send_newsletter($campaign) {
		
	}
  
}

2. Then save the file to your system/application/newsletter_backends/ folder. Note: Class name must start with an uppercase letter and class name and file names must match. In other words, if file name is example_newsletter_backend.php then this is valid:

<?php
class Example_newsletter_backend extends Base_newsletter_backend {

}

This is not valid:

<?php
class example_newsletter_backend extends Base_newsletter_backend {

}

Also, always make sure your class extends the Base_newsletter_backend class and you include base_newsletter_backend.php so that it can inherit all its functions.

Required functions

Your backend must implement at least these three functions.

name()

Returns backend name.
Accepted return type:

string - backend name.

send_test_newsletter($campaign, $email)

It is used to send test newsletters from Backend => Campaigns => Send test newsletter
Parameters:

Array $campaign
  'id' => string 
  'user_id' => string 
  'company_id' => string 
  'ordinary_price' => string 
  'status' => string '
  'type' => string 
  'deal_status' => string 
  'coupon_price' => string 
  'coordinates' => string 
  'start_datetime' => string 'YYYY-MM-DD HH:MM:SS'
  'end_datetime' => string 'YYYY-MM-DD HH:MM:SS'
  'coupon_expire_datetime' => string 'YYYY-MM-DD HH:MM:SS'
  'active' => string 
  'min_coupons' => string 
  'is_global' => string 
  'newsletters_sent' => string
  'max_coupons' => string 
  'max_coupons_per_user' => string 
  'coupons_bought' => string
  'name' => string 
  'description' => string 
  'highlights' => string 
  'coupon_instructions' => string
  'show_in_recent_deals' => string 
  'youtube_video_id' => string 
  'in_side' => string 
  'send_newsletter' => string
  'resend_newsletter' => string 
  'created_datetime' => string 'YYYY-MM-DD HH:MM:SS'
  'image_url' => string 
String $email

Accepted return type:

Boolean - true on success, false on failure

send_newsletter($campaign)

Is called from cronjob - used to send newsletters for one campaign (passed as a parameter).
Must not use die() or any other code that causes script to die.
Parameters:

Doctrine object $campaign
      'id' => string 
      'user_id' => string
      'company_id' => string 
      'ordinary_price' => string 
      'status' => string 
      'type' => string 
      'deal_status' => string 
      'coupon_price' => string 
      'coordinates' => string 
      'start_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'end_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'coupon_expire_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'active' => string
      'min_coupons' => string
      'is_global' => string 
      'newsletters_sent' => string 
      'max_coupons' => string 
      'max_coupons_per_user' => string 
      'coupons_bought' => string 
      'name' => string 
      'description' => string 
      'highlights' => string 
      'coupon_instructions' => string 
      'show_in_recent_deals' => string 
      'youtube_video_id' => string 
      'in_side' => string 
      'send_newsletter' => string 
      'resend_newsletter' => string 
      'created_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'image_url' => string 

Accepted return type:

Boolean - true on success, false on failure

Must return a value - so cronjob can properly mark campaign newsletter status.

Optional functions

You should implement these functions only if your backend API requires them.

subscribe_user($email)

Subscribes single email address to newsletter.
Parameters:

String $email

synchronize_subscribers()

Synchronises all local subscribers with remote list.
Is called from cronjob.
Must not use die() or any other code that causes script to die.

unsubscribe_user($email)

Unsubscribes single email from remote list.
Parameters:

String $email

synchronize_campaigns()

Synchronises all unsent campaigns to remote list.
Is called from cronjob.
Must not use die() or any other code that causes script to die.

update_email($old_email, $new_email)

Updates single remote email address if changed locally by user or administrator.
Parameters:

String $old_email
String $new_email

get_subscriber_count()

Returns remote list subscriber count
It is shown in Backend => Dashboard => Newsletter status => Remote subscribers
Accepted return value:

String/Integer - subscriber count

resync()

Used to manually resync local subscribers/campaigns/any other data to remote list.
Is called from Backend => Dashboard => Newsletter status => resync subscribers button.

Error logging

log_error($campaign, $error_message)

Used to log errors to database - error log can be viewed in Backend => Dashboard => Newsletter status
Required parameters:

Mixed $campaign - array, Doctrine object or null
String $error_message - message you wish to log to database. 

Your backend can also override this function to log errors to a text file, for example.

You can also use error array, to display error messages to admin (after unsuccessful test sending for example). Like this:

<?php
$this->errors[] = $error_message;

Error array can be accessed from outside by using

<?php
$active_backend->get_errors();

get_errors()

Returns error array.
Return type:

Array of strings or null, if there aren't any. 

Useful functions/tips

Base backend default properties

    protected $double_opt_in;    - boolean - true if double opt-in is enabled, false otherwise
    protected $CI;               - reference to CodeIgniter object - used to access CodeIgniter functions from your backend
    protected $telephone;        - string - Company's telephone as configured in backend - can be embedded in email message
    protected $physical_address; - string - Company's physical address as configured in backend - can be embedded in email message
    protected $errors;           - error array - can be accessed with get_errors()

get_active_newsletter_backend()

Returns active newsletter backend.
Return type:

Object - active backend (or false if there aren't any - should not happen)

You can get active newsletter backend object from outside like this:

<?php
<CodeIgniter object>->load->helper('newsletter_backend');
$active_backend = get_active_newsletter_backend();

get_newsletter_subject($campaign)

Returns subject for newsletter. Usage/override optional
Should be called from send_newsletter() and send_test_newsletter().
Parameters:

Doctrine object $campaign
 'id' => string 
      'user_id' => string
      'company_id' => string 
      'ordinary_price' => string 
      'status' => string 
      'type' => string 
      'deal_status' => string 
      'coupon_price' => string 
      'coordinates' => string 
      'start_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'end_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'coupon_expire_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'active' => string
      'min_coupons' => string
      'is_global' => string 
      'newsletters_sent' => string 
      'max_coupons' => string 
      'max_coupons_per_user' => string 
      'coupons_bought' => string 
      'name' => string 
      'description' => string 
      'highlights' => string 
      'coupon_instructions' => string 
      'show_in_recent_deals' => string 
      'youtube_video_id' => string 
      'in_side' => string 
      'send_newsletter' => string 
      'resend_newsletter' => string 
      'created_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'image_url' => string 

Return type:

String - newsletter subject

get_newsletter_content($campaign, $email=null)

Gets content for newsletter body. Usage/override optional.
By default renders template from:
system/application/themes/<theme>/templates/newsletters.php
Should be called from send_newsletter() and send_test_newsletter().
Parameters:

Doctrine object $campaign
      'id' => string 
      'user_id' => string
      'company_id' => string 
      'ordinary_price' => string 
      'status' => string 
      'type' => string 
      'deal_status' => string 
      'coupon_price' => string 
      'coordinates' => string 
      'start_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'end_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'coupon_expire_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'active' => string
      'min_coupons' => string
      'is_global' => string 
      'newsletters_sent' => string 
      'max_coupons' => string 
      'max_coupons_per_user' => string 
      'coupons_bought' => string 
      'name' => string 
      'description' => string 
      'highlights' => string 
      'coupon_instructions' => string 
      'show_in_recent_deals' => string 
      'youtube_video_id' => string 
      'in_side' => string 
      'send_newsletter' => string 
      'resend_newsletter' => string 
      'created_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'image_url' => string 
String $email - optional - by default used to generate unsubscribe links.

Return type:

String - newsletter content

How to

Get all subscribers

Doctrine_Core::getTable('NewsletterSubscriber')->getAllSubscribers();

Gets all subscribers with confirmed email addresses as array.
Return:

Array of newsletter subscribers.
Contents:
'username' - username for registered users - empty string for unregistered 
'email' - subscriber's email
'name' - real name for registered users - empty string for unregistered 
'surname' - real surname for registered users - empty string for unregistered 
'city_name' - subscriber's city name

Get single subscriber's data by email

Doctrine_Core::getTable('NewsletterSubscriber')->getSubscriberData($email);

Parameters:

String $email

Return:

Array
'username' - username for registered users - empty string for unregistered 
'email' - subscriber's email
'name' - real name for registered users - empty string for unregistered 
'surname' - real surname for registered users - empty string for unregistered 
'city_name' - subscriber's city name

Get subscribers for single campaign

Doctrine_Core::getTable('NewsletterSubscriber')->getSubscribers($campaign_id) Parameters:

String $campaign_id;

Return:

Array of newsletter subscribers.
Contents:
'username' - username for registered users - empty string for unregistered 
'email' - subscriber's email
'name' - real name for registered users - empty string for unregistered 
'surname' - real surname for registered users - empty string for unregistered 
'city_name' - subscriber's city name

Get all unsent campaigns

Doctrine_Core::getTable('Campaign')->getCampaignsNotSent();

Return:

Array of Doctrine objects
Contents:
      'id' => string 
      'user_id' => string
      'company_id' => string 
      'ordinary_price' => string 
      'status' => string 
      'type' => string 
      'deal_status' => string 
      'coupon_price' => string 
      'coordinates' => string 
      'start_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'end_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'coupon_expire_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'active' => string
      'min_coupons' => string
      'is_global' => string 
      'newsletters_sent' => string 
      'max_coupons' => string 
      'max_coupons_per_user' => string 
      'coupons_bought' => string 
      'name' => string 
      'description' => string 
      'highlights' => string 
      'coupon_instructions' => string 
      'show_in_recent_deals' => string 
      'youtube_video_id' => string 
      'in_side' => string 
      'send_newsletter' => string 
      'resend_newsletter' => string 
      'created_datetime' => string 'YYYY-MM-DD HH:MM:SS'
      'image_url' => string 
Personal tools

Groupon Clone