DADA::MailingList::Subscribers

NAME

DADA::MailingList::Subscribers - API for the Dada Mailing List Subscribers

SYNOPSIS

 # Import
 use DADA::MailingList::Subscribers; 
  
 # Create a new object
 my $lh = DADA::MailingList::Subscribers->new({-list => 'mylist'}); 
 
 # Check if this can be a valid subscription: 
 
 my ($status, $errors) = $lh->subscription_check(
        {
                -email => 'user@example.com', 
        }
 );
 
 # How about to unsubscribe: 
 
 my ($status, $errors) = $lh->unsubscription_check(
        {
                -email => 'user@example.com', 
        }
  );
 
 # Add
 $lh->add_subscriber(
        {
                -email => 'user@example.com',
                -type  => 'list', 
        }
 );
 
 # Move
 $lh->move_subscriber(
        {
                -email => 'user@example.com',
                -from  => 'list', 
                -to    => 'black_list', 
        }
  );
 
 # Copy
 $lh->copy_subscriber(
        {
                -email => 'user@example.com',
                -from  => 'black_list', 
                -to    => 'list', 
        }
  );
 
 # Remove
 $lh->remove_subscriber(
        {
                -email => 'user@example.com',
                -type  => 'list', 
        }
  );

DESCRIPTION

This module represents the API for Dada Mail's subscriptions lists.

Subscription List Model

Dada Mail's Subscription List system is currently fairly simple:

A subscriber is mostly identified by their email address

Usually, when we talk of a, "Subscriber", we're talking about a email address that has been included in a Dada Mail Subscription List.

The Subscription List is made up of Sublists.

A sublist is a list of subscribers. Each sublist is completely separated from each other sublist.

Each sublist is known because of its type.

The types of sublists are as follows:

A Subscription List can have Profile Fields

The Profile Fields are information that's separate than the email address of a subscriber. Their values are arbitrary and can be set to most anything you'd like.

Internally, the Profile Fields are mapped almost exactly to SQL columns - adding a subscriber field will add a column in an SQL table. Removing a field will remove a column.

Restrictions are enforced by Dada Mail to only allow correct information to be saved in the Subscription List

The most obvious enforcement is that the subscriber has to have a valid email address.

Another enforcement is that a subscriber cannot be subscribed to a sublist twice.

A subscriber can be on more than one sublist at the same time.

Some sublists are used to enforce subscription on other sublists. For example, a subscriber in the black_list sublist will not be allowed to joing the, list sublist.

These enforcements are currently lazy - You can easily break these rules, but you don't want to, and checking the validation of a subscriber is easy. The easiest way to break these rules is to work with the backend that the subscribers are saved in directly.

The Subscription List has various backend options

The Subscription List can either be saved as a series of PlainText files (one file for each type of sublist), or as an SQL table.

Each type of backend has different features that are available. The most notable feature is that the SQL backend supports arbitrary Profile Fields and the PlainText backend does not.

Currently, the following SQL flavors are supported:

Except for being able to change the name of a Subscriber Field in SQLite, every SQL flavor has the same feature set.

Public Methods

Below are the list of Public methods that we recommend using when manipulating a Dada Mail Subscription List:

Every method has its parameters, if required (and when it's stated that they're required, they are), passed as a hashref.

Initializing

new

 my $lh = DADA::MailingList::Subscribers->new({-list => 'mylist'});

new requires you to pass a listshortname in, -list. If you don't, your script will die.

A DADA::MailingList::Subscribers object will be returned.

Add/Get/Edit/Move/Copy/Remove a Subscriber

add_subscriber

 $lh->add_subscriber(
        {
                -email  => 'user@example.com', 
                -type   => 'list',
                -fields => {
                                        # ...
                                   },
        }
);

add_subscriber adds a subscriber to a sublist.

-email is required and should hold a valid email address in form of: user@example.com

-type holds the sublist you want to subscribe the address to, if no sublist is passed, list is used as a default.

-fields holds the subscription fields you'd like associated with the subscription, passed as a hashref.

For example, if you have two fields, first_name and, last_name, you would pass the Profile Fields like this:

 $lh->add_subscriber(
        {
                -email  => 'user@example.com', 
                -type   => 'list',
                -fields => {
                                        first_name => "John", 
                                        last_name  => "Doe", 
                                   },
        }
 );

Passing field values is optional.

Fields that are not actual fields that are being passed will be ignored.

-dupe_check can also be optionally passed. It should contain a hashref with other options. For example:

    $lh->add_subscriber(
        {
                -email  => 'user@example.com', 
                -type   => 'list',
                -fields => {
                                        first_name => "John", 
                                        last_name  => "Doe", 
                                   },
        }, 
        -dupe_check    => {
                -enable  => 1,
                -on_dupe => 'ignore_add',
        },
        
    );

-enable can either be set to, 1 or, 0. 1 enables the check for dupes, right before subscribing an address. 0 ignores the dupe check, so don't set it to 0

-on_dupe may be set to, ignore_add to simply ignore subscribing the address. A warning will be logged in the error log. You may also set this to, error, which will cause the program to die.

Setting this to anything else will cause the program to die. Forgetting to set it will have it default to, ignore_add.

If the Duplicate subscriber check fails, (and -on_dupe is set to, ignore_add this method will return, 0 and not a DADA::MailingList::Subscriber object.

Diagnostics

returns a DADA::MailingList::Subscriber object on success, undef or croaks on failure.

get_subscriber

 my $sub_info = $lh->get_subscriber(
                {
                        -email => 'user@example.com', 
                        -type  => 'list', 
                }
        );

Returns the Profile Fields information in the form of a hashref.

-email is required and should hold a valid email address in form of: user@example.com. The address should also be subscribed and no check is done if the address you passed isn't.

-type holds the sublist you want to work with. If no sublist is passed, list is used as a default.

Diagnostics

edit_subscriber

 $lh->edit_subscriber(
        {
                -email  => 'user@example.com', 
                -type   => 'list', 
                -fields => 
                        {
                                # ...
                        },
                -method => 'writeover',
        }
 );

returns 1 on success.

Internally, this method removes a subscriber and adds the same subscriber again to the same list.

-email is required and should hold a valid email address in form of: user@example.com

-type holds the sublist you want to subscribe the address to, if no sublist is passed, list is used as a default.

-fields holds the subscription fields you'd like associated with the subscription, passed as a hashref.

For example, if you have two fields, first_name and, last_name, you would pass the Profile Fields like this:

 $lh->edit_subscriber(
        {
                -email  => 'user@example.com', 
                -type   => 'list',
                -fields => {
                                        first_name => "Jon", 
                                        last_name  => "Doh", 
                                   },
        }
 );

Passing field values is optional, although you probably would want to, as this is the point of the entire method.

Fields that are not actual fields that are being passed will be ignored.

-method holds the type of editing you want to do. Currently, this can be either, update, or, writeover.

update will only save the fields you pass - any other fields saved for this subscriber will not be erased.

writeover will save only the fields you pass - any other fields will be removed from the subscriber.

If no -method is passed, update is used as a default.

Diagnostics

Internally, the subscriber is first removed, than added, using the add_subscriber and, remove_subscriber methods. Those diagnostics may pop up, if you use this method incorrectly

move_subscriber

 $lh->move_subscriber(
        {
                -email => 'user@example.com', 
                -from  => 'list', 
                -to    => 'black_list',
        }
 );

-email holds the email address of the subscriber you want to move.

-from holds the sublist you're moving from.

-to holds the sublist you're moving to.

All parameters are required. No other parameters will be honored.

This method will die if the subscriber isn't actually subscribed to the sublist set in, -from or, is already subscribed in the sublist set in, -to.

Diagnostics

copy_subscriber

 $lh->copy_subscriber(
        {
                -email => 'user@example.com', 
                -from  => 'list', 
                -to    => 'black_list',
        }
 );

-email holds the email address of the subscriber you want to copy.

-from holds the sublist you're copying from.

-to holds the sublist you're copying to.

All parameters are required. No other parameters will be honored.

This method will die if the subscriber isn't actually subscribed to the sublist set in, -from or, is already subscribed in the sublist set in, -to.

Diagnostics

remove_subscriber

 $lh->remove_subscriber(
        {
                -email => 'user@example.com', 
                -type  => 'list', 
        }
 );

remove_subscriber removes a subscriber from a sublist.

-email is required and should hold a valid email address in form of: user@example.com

-type holds the sublist you want to subscribe the address to - you'll want to always explicitly set the type.

No other parameters are honored.

Diagnostics

Validating a Subscriber

get_list_types

 my $list_types = $lh->get_list_types

Returns a hashref of the allowed sublist types. The keys are the actual sublist types, the value is simply set to, 1, for easy lookup tabling.

Takes no parameters.

The current list of allowed sublist types are:

check_for_double_email

Note! The naming, coding and parameter style is somewhat old and crufty and this method is on the chopping block for a re-write

 my $is_subscribed = $lh->check_for_double_email(
        -Email          => 'user@example.com,
        -Type           => 'list',
        -Match_Type     => 'sublist_centric',
        );

Returns 1 if the email address passed in, -Email is subscribed to the sublist passed in, -Type.

-Email should hold a string that usually is an email address, although can be only a part of an email address.

-Type should hold a valid sublist name.

-Type will default to, list if no -Type is passed.

-Status

-Match_Type controls the behavior of how a email address is looked for and is usualy something you want to override for the, black_list and white_list sublists.

The sublists have different matching behaviors. For example, if, bad is subscribed to the black_list sublist, this will return 1

 my $is_subscribed = $lh->check_for_double_email(
        -Email          => 'bad@example.com,
        -Type           => 'list',
        -Match_Type     => 'sublist_centric',
        );

Since the black list is not simply a list of addresses that are black listed, it's a list of patterns that are black listed.

-Match_Type can also be set to, exact, in which case, this would return, 0

 my $is_subscribed = $lh->check_for_double_email(
        -Email          => 'bad@example.com,
        -Type           => 'list',
        -Match_Type     => 'exact',
        );

-Match_Type will default to, sublist_centric id no -Math_Type is passed.

subscription_check

        my ($status, $errors) =  $lh->subscription_check(
                {
                        -email => 'user@example.com', 
                        -type  => 'list'
                        -skip  => []
                }
        );

-email holds the address you'd like to validate. It is required.

-type holds the sublist you want to work on. If not passed, list will be used as the default.

-skip holds an arrary ref of checks you'd like not to have done. The checks are named the same as the errors.

For example:

 my ($status, $errors) = $lh->subscription_check(
                                                                {
                                -email => 'user@example.com', 
                                                -skip => [qw(black_listed closed_list)],
                                }
                                                        );

This method returns an array with two elements.

The first element is the status of the validation. 1 will be set if the validation was successful, 0 if there was an error.

The second element is a list of the errors that were found when validating, in the form of a hashref, with its name as the name of the error and the value set to, 1 if that error was found.

The errors, which are fairly self-explainitory are as follows:

Unless you have a special case, always use this method to validate an email subscription.

unsubscription_check

 my ($status, $errors) =  $lh->unsubscription_check(
                                                                {
                                                                        -email => 'user@example.com',
                                                                        -type  => 'list', 
                                                                        -skip  => [],
                                                                        
                                                                }
                                                   );

Like the subscription_check method, this method returns a $status and a hashref of $%errors when checking the validity of an unsubscription. The following errors may be returned:

Again, any of these tests can be skipped using the -skp argument.

Add/Get/Edit/Remove a Subscription Field

As noted, Profile Fields are only available in the SQL backends.

It should be also noted that future revisions of Dada Mail may see these types of methods in their own object, ie:

DADA::MailingList::Subscribers::Fields

or, whatever.

filter_subscribers

 my (
        $subscribed, 
        $not_subscribed, 
        $black_listed, 
        $not_white_listed, 
        $invalid
        ) = $lh->filter_subscribers(
                {
                        -emails => [], 
                        -type   => 'list',
                }
        );

This is a very powerful and complex method. There's dragons in the code, but the API is pretty simple.

Used to validated a large amount of addresses at one time. Similar to subscripton_check but is meant for more than one address. It's also meant to be bit faster than looping a list of addresses through subscripton_check.

Accepts two parameters.

-email is an array ref of email addresses .

-type is the sublist we want to validate undef.

Depending on the type of sublist we're working on, validation works slightly different.

Returns a 5 element array, each element contains an array ref of email addresses.

This method also sets the precendence of black listed and white listed addresses, since an address can be a member of both sublists.

The precendence is the same as what's returned:

In other words, if someone is both black listed and white listed, during validation, it'll be returned that they're black listed.

filter_subscribers_w_meta

 my (
        $subscribed, 
        $not_subscribed, 
        $black_listed, 
        $not_white_listed, 
        $invalid
     ) = $lh->filter_subscribers_w_meta(
                {
                        -emails => [], 
                        -type   => 'list',
                }
        );

Similar to filter_subscribers, but allows you to pass the subscriber field information with the email address.

The, -email parameter should hold an arrayref of hashrefs, instead of just an array ref. The hashref itself should have the form of:

 {
        -email => 'user@example.com',
        -fields => { 
                -field1 => 'blah', 
                -field2 => 'blahblah', 
        }
 }

No validation is done on the Profile Fields - they're simply passed through and returned.

Returns a 5 element array of hashrefs, in the same format as what's passed.

add_subscriber_field

 $lh->add_subscriber_field(
        -field          => 'myfield', 
        -fallback_value => 'My Fallback Value', 
 );

add_subscriber_field adds a new subscriber field.

-field Should hold the name of the subscriber field you'd like to add. It is required.

-fallback_value holds what's known as the, fallback value, which is a value used in some instances of Dada Mail, if no value is saved in this field for a particular subscriber. It is optional.

Diagnostics

subscriber_fields

 my $fields = $lh->subscriber_fields;
 
 # or: 
 
 for(@{$lh->subscriber_fields}){
  # ... 
 }

Returns the Profile Fields in the Subscription List, in the form of an array ref.

Takes no arguments... usually.

Internally (and privately), it does accept the, -dotted parameter. This will prepend, 'subscriber.' to every field name.

Diagnostics

None that I can think of.

edit_subscriber_field_name

 $lh->edit_subscriber_field_name(
        { 
                -old_name => 'old', 
                -new_name => 'new', 
                
        }
 );

Changes the name of a Subscriber Field.

Returns 1 on success.

-old_name holds the name of the field you want to rename.

-new_name holds what you'd like to rename the field in -old_name to.

Both parameters are required.

Diagnostics

remove_subscriber_field

 $lh->remove_subscriber_field(
        {
                -field => 'myfield', 
        },
 );

Removes the field specified in, -field. -field is required.

Returns 1 upon success.

Diagnostics

subscriber_field_exists

 my $exists = $lh->subscriber_field_exists(
        {
                -field => 'myfield', 
        }
 );

Checks the existance of a subscriber field name.

Diagnostics

validate_subscriber_field_name

 my ($status, $errors) = $lh->validate_subscriber_field_name(
                                                        {
                                                                -field => $field,
                                                                -skip  => [],
                                                        }
                                                );

Used to validate a subscriber field name and meant to be used before a subscriber field is added.

Returns a two element array,

The first element is either 1 or 0 and is the status of the validation. A status of, 1 means the validation was successful; 0 means the validation had problems.

The second element is a list of the errors that were found when validating, in the form of a hashref, with the name of the error set as the key and the value set to, 1 if this error was found.

-field is required and should be the name of the field you're attempting to validate.

-skip is an optional parameter and is used to list the errors you're not so interested in. It should be set to an array ref.

Subscriber Validation Requirements

Profile Fields are validated mostly to make sure they're also valid SQL column names for all the SQL backends that are supported and also that the fields are not already used for internal SQL fields used by the program for other purposes. Validation is also done sparingly for reserved words.

The entire list of errors that can be reported back are as follows:

validate_remove_subscriber_field_name

 my ($status, $errors) = $lh->validate_remove_subscriber_field_name(
                                                        { 
                                                                -field      => $field,
                                                                -skip       => [],
                                                                -die_for_me => 0, 
                                                        }
                                                );

Similar to, validate_subscriber_field_name is used to validate a subscriber field name and is meant to be used before a subscriber field is removed.

Returns a two element array,

The first element is either 1 or 0 and is the status of the validation. A status of, 1 means the validation was successful; 0 means the validation had problems.

The second element is a list of the errors that were found when validating, in the form of a hashref, with the name of the error set as the key and the value set to, 1 if this error was found.

-field is required and should be the name of the field you're attempting to validate.

-skip is an optional parameter and is used to list the errors you're not so interested in. It should be set to an array ref.

-die_for_me is another optional parameter. If set to, 1, an error found in validation will prove fatal.

The entire list of errors that can be reported back are as follows:

get_all_field_attributes

 my $field_values = $lh->get_all_field_attributes;

Returns the name of every subscriber field and its fallback value in the form of a hashref.

The fallback values are actually saved in the List Settings.

Take no arguments.

_save_field_attributes

 $lh->_save_field_attributes(
                {
                        -field          => $field, 
                        -fallback_value => $fallback_field_value, 
                        -fallback_value => $fallback_value, 
                }
 );

Currently marked as a private method.

Used to save a new fallback field value for the field set in, -field. usually shouldn't be used alone, but there is actually no way to edit a fallback field value, without using this method.

If used on an existing field, make sure to remove the fallback field value first, using, _remove_field_attributes, ala:

 $lh->remove_field_attributes({-field => 'myfield'});
 $lh->save_field_attributes({-field => 'myfield'}, -fallback_value => 'new_value');

Is called internally, when creating a new field via, add_subscriber_field, so make sure not to call it twice.

Diagnostics

remove_field_attributes

 $lh->remove_field_attributes(
                {
                        -field => 'myfield', 
                }
 );

Currently marked as a private method.

Used to remove a fallback field value. Used internally.

Diagnostics

AUTHOR

Justin Simoni https://dadamailproject.com

LICENSE AND COPYRIGHT

Copyright (c) 1999 - 2023 Justin Simoni All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Dada Mail Project

Download

Installation

Support