Subscription Cookbook

Subscription Cookbook

How to Subscribe an Email Address to a Mailing List

A challenge people face is trying to tie Dada Mail's subscription system with another system, like a checkout part of a shopping cart, boards/forum, blog or CMS software.

RESTful API

Dada Mail has an, EXPERIMENTAL RESTful API.

POST a request to your Dada Mail URL, with the following path:

http://example.com/cgi-bin/dada/mail.cgi/json/subscribe

(/json/subscribe is the PATH INFO you need)

Your POST Data will need to be in JSON, and have the following two fields, and an optional third:

Here's an example of data in JSON to subscribe, user@example.com to a list, mylist:

        {
           "email" : "user@example.com",
           "list" : "mylist"
        }

Here's an example, with two Profile Fields, first_name and last_name:

        {
           "email" : "user@example.com",
           "fields" : {
              "last_name" : "Example",
              "first_name" : "Jason"
           },
           "list" : "mylist"
        }

Results will also come back as JSON. For example, a successful request will return the following JSON document:

        {
           "email" : "user@example.com",
           "redirect" : {
              "query" : "list=mylist&email=user%40example.com&status=1&rm=sub_confirm",
              "using_with_query" : 1,
              "url" : "http://example.com/alt_url_sub_confirm_success.html",
              "using" : 1
           },
           "status" : 1,
           "success_message" : "<h1>Request Successful, Check Your Email!</h1> [...]",
           "list" : "mylist"
        }

Situations That Require Additional User Input

There are some cases where a redirect back to Dada Mail will be required, to handle the request correctly.

For example, Dada Mail can be set up to limit the amount of subscription requests made, per a particular email address, to a particular mailing list.

So if > 1 request is made, rather than try to handle it twice, Dada Mail will instead return with a failure. When handled by Dada Mail itself, the user would then be presented with the option to resend a subscription request, after a CAPTCHA is filled out.

This isn't something you can do, purely with the RESTful API, but you can see if you need to point the user to Dada Mail.

For example, say this is the second request to subscribe:

        {
           "email" : "user@example.com",
           "list" : "mylist"
        }

Rather than a succesful request, the following JSON will be returned:

        {
           "email" : "user@example.com",
           "redirect" : {
              "query" : "list=dadatest&email=user%40example.com&status=0&rm=sub_confirm&errors[]=already_sent_sub_confirmation",
              "using_with_query" : 1,
              "url" : "http://example.com/cgi-bin/dada/mail.cgi?flavor=show_error&email=user%40example.com&list=dadatest&error=already_sent_sub_confirmation",
              "using" : 1
           },
           "errors" : {
              "already_sent_sub_confirmation" : 1
           },
           "status" : 0,
           "redirect_required" : "subscription_requires_captcha",
           "error_descriptions" : {
              "already_sent_sub_confirmation" : "use redirect"
           },
           "list" : "mylist"
        }

The errror, already_sent_sub_confirmation will have an associated error_description with a value of, use redirect. The redirect array will have a key, url, whose value will be the URL you'll need to redirect your user to, to complete the request.

JSONP

This API also supports sending a request using JSONP.

If using JSONP, make sure to append the PATH INFO, with the query string, setting the name of your callback, like this:

http://example.com/cgi-bin/dada/mail.cgi/json/subscribe?callback=mycustomcallback

Sending data over via POST is not supported in JSONP, in general, so you'll want to send over the fields you usually would send as a JSON payload, in the query string, as well.

Along with the usual fields, list, email, etc, you'll want to send another field called, _method with a value of, GET. This is to tell Dada Mail you're sending a, JSONP request.

The entire query string could look like this:

http://example.com/cgi-bin/dada/mail.cgi/json/subscribe?callback=mycustomcallback&_method=GET&list=mylist&email=user@example.com&first_name=Jason&last_name=Example

The JSONP document will be returned, encapsulated by the callback function name:

        mycustomcallback({
           "email" : "test@example.com",
           "status" : 1,                
           "list" : "mylist"         
           [ ... ]
        });

When calling via JSONP, the Content-Type will be send back as, application/javascript, rather than, application/json

Example Implementations

JavaScript/jQuery

The following is a bare-bones example on how to use the JSONP API to send a subscription request using jQuery - but it still supports custom redirects, as well as any needed redirects for additional user input:

        $.ajax({
                url: 'http://example.com/cgi-bin/dada/mail.cgi/json/subscribe',
                type: "GET",
                dataType: "jsonp",
                cache: false,
                data: {
                _method: 'GET', 
                        list:  'mylist',
                        email: 'test@example.com',
                        first_name: 'Jason', 
                        last_name: 'Example'
                },
            contentType: "application/json; charset=UTF-8",
                success: function(data) {
                        console.log('data:' + JSON.stringify(data)); 
                        var html = ''; 
                        if(data.status === 0){                                                                                          
                                $.each(data.errors, function(index, value) {
                                        console.log(index + ': ' + value);
                                });
                                $.each(data.error_descriptions, function(index, value) {
                                        html += value;
                                });
                        }
                        else { 
                                html += data.success_message;
                        }
                        if(typeof data.redirect_required === 'undefined') {
                                if(data.redirect.using === 1) {
                                        if(data.redirect.using_with_query === 1){ 
                                                window.location.href = data.redirect.url + '?' + data.redirect.query; 
                                        }
                                        else { 
                                                window.location.href = data.redirect.url;
                                        }
                                }
                                else { 
                                                /* Display "html" */
                                        }); 
                                }
                        }
                        else { 
                                /* Success, or Error: it may not be something we can work with: */
                                //alert(data.redirect_required); 
                                window.location.href = data.redirect.url;
                        }
                },
                error: function(xhr, ajaxOptions, thrownError) {
                        console.log('status: ' + xhr.status);
                        console.log('thrownError:' + thrownError);
                        /* Uh oh... */
                }
        });

Perl

The following is a bare-bones example on how to use the JSON API to send a subscription request, using Perl:

        #!/usr/bin/perl 
        
        use JSON;
        use HTTP::Request;
        use HTTP::Request::Common;
        use LWP::UserAgent;
        use Data::Dumper;
        
        my $ua = LWP::UserAgent->new;
        
        my $json = JSON->new->allow_nonref;
        my $data = $json->utf8->encode(
            {
                list  => 'mylist',
                email => 'test@example.com',
            }
        );
        
        my $response = $ua->request(
            POST 'http://example.com/cgi-bin/dada/mail.cgi/json/subscribe',
            'Content-Type' => 'application/json',
            Content        => $data
        );
        
        if ( $response->is_success ) {
        
            my $r = $json->utf8->decode( $response->decoded_content );
                
            print Dumper($r);
                
            if ( $r->{status} == 1 ) {
                print "Success!\n";
            }
            else {
                print "Problems!\n";
            }
        }
        else {
            die $response->decoded_content;
        }

PHP

If you can, please contribute an example!

Python

If you can, please contribute an example!

Ruby

If you can, please contribute an example!

jQuery Plugin

Dada Mail comes with a jQuery Plugin, that can be used to create a subscription form on a webpage, handle the request and show the results in a modal window, only redirecting the user if additional steps are required. The plugin uses the RESTful API, described above.

To use the jQuery plugin, you'll first need to load the plugin's .js file, along with other .js files it requires, in the head of your document:

        <script src="http://example.com/dada_mail_support_files/static/javascripts/vendor/jquery-3.6.0.min.js"></script>
        
        <link rel="stylesheet" href="http://example.com/dada_mail_support_files/static/css/vendor/colorbox/colorbox.css">
        <script src="http://example.com/dada_mail_support_files/static/javascripts/vendor/jquery/colorbox/jquery.colorbox-min.js"></script>
        
        <script src="http://example.com/dada_mail_support_files/static/javascripts/jquery.dadamail.js"></script>

jquery.dadamail.js is the jQuery plugin itself, but it does require jQuery to be loaded (in our case, it's called, jquery-3.6.0.min.js), as well the Colorbox jQuery plugin (http://www.jacklmoore.com/colorbox/).

All these are bundled with Dada Mail, but you may use your own copies, if you'd like. To change the design of the modal window that pops up, you'll want to work with Colorbox's own .css file.

The jQuery plugin has two "methods" you may use.

CreateSubscribeForm

        $(document).ready(function() {
        
                var targetDiv = '#mydiv';
        
                /* Initialize: */
                if($(targetDiv).length) { 
                $(targetDiv).DadaMail(
                        {
                                DadaMailURL: 'http://example.com/cgi-bin/dada/mail.cgi', 
                                list: 'yourlist', 
                                modal: 1
                        }
                )
        
                /* Create the form: */
                $(targetDiv).DadaMail('CreateSubscribeForm');
                }
        });

CreateSubscribeForm will place a subscription form in a div with the id of, mydiv

Initialization Paramaters

To work correctly you'll need to pass the following paramaters:

Optionally, the following paramaters may also be passed:

The Modal method will allow you to have a Dada Mail subscription form already present on your webpage controlled by this plugin:

JavaScript:

        $(document).ready(function() {
        
                var targetDiv = '#mydiv';
                
                /* Initialize: */
                if($(targetDiv).length) { 
            $(targetDiv).DadaMail(
                        {
                                targetForm: 'myForm'
                        }       
                );
                
                /* Control the form: */
                $(targetDiv).DadaMail('Modal');
                }
        });

Your Subscription Form:

        <div id="mydiv">
                <form action="http://example.com/cgi-bin/dada/mail.cgi"  id="myForm">
                        <input type="hidden" name="flavor" value="subscribe" />
                        <input type="hidden" name="list" value="mylist" />
                        <input type="text" name="email" value="" />
                        <input type="submit" value="Subscribe" />
                </form>
        </div>

The subscription form with the id of, "myForm" will now show its results in a modal window. This method only has one, required paramater:

The subscription form itself needs to have the following form fields, which are the same form fields used for any Dada Mail mailing list subscription form:

The action of the form also should be the URL to your Dada Mail (http://example.com/cgi-bin/dada/mail.cgi). If done correctly, the form alone should make a successful request to your Dada Mail install, thus working even if JavaScript has been disabled.

Shared Optional Paramaters

Both these two methods may pass these optional paramaters during initialization:

Perl API

You may use Dada Mail's own modules in your own app, see:

https://dadamailproject.com/d/App_Subscriptions.pm.html

Command Line Utility - subscribe_email.pl

Find a copy of subscribe_email.pl in the Dada Mail distro at:

dada/extras/scripts/subscribe/subscribe_email.pl

Arguments

Run subscribe_email.pl as a shell script, like this:

 prompt>perl ./subscribe_email.pl --list mylist --email user@example.com

--list should hold the listshortname of the list you want to subscribe to.

--email should hold the email address you want to subscribe.

--verbose is optional. If set to, 1, you will get a small report on the request.

You can also pass Profile Fields for the subscriber, just use the, -fields parameter:

 prompt>perl ./subscribe_email.pl --list mylist --email user@example.com ---fields first_name=John --fields last_name=Doe

subscribe_email.pl can also be called from within another script using something like Perl's, exec function.

PHP Example

Here's an example for a php script, that uses php's shell_exec function (make sure to change the permissions of subscribe_email.pl to, 755):

        <?php
                var $email = 'user@example.com'; 
                var $list  = 'mylist'; 
                shell_exec("/home1/zazarazz/public_html/dadamail/extras/scripts/subscribe/subscribe_email.pl --list $list --email $email");
        ?>

To make things easier while testing, you may wish to disable Dada Mail's feature of limiting Subscription Confirmations. This feature disallows someone to continually attempt to subscribe the same email address. In testing, this may be exactly what you'd like to do.

In, Mailing List - Options

Uncheck the option, Limit Subscription Confirmation Sending. Once done testing, you may want to re-enable this option.

 Limit Subscription Confirmation Sending

Other examples

FormMail Integration

See the sourcecode to FormMail to see how we integrated Dada Mail subscription capabilities in this simple form handler:

https://dadamailproject.com/d/Dada-ized_FormMail_README.pod.html

TFmail Integration

See the sourcecode to TFmail to see how we integrated Dada Mail subscription capabilities in this simple form handler:

https://dadamailproject.com/d/Dada-ized_TFMail_README.pod.html

Dada Mail Project

Download

Installation

Support