Subscription Cookbook

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:

list

list holds the list shortname you would like to make the subscription to
email

email holds the email address you would like the subscription for
fields

Optional: fields holds the Profile Fields you would like to pass.

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"
        }

email

email holds the email address you passed.
list

list holds the list short name you passed.
status

status tells you if the request worked, or not.

A value of 1 means success, a value of, 0 means failure.

If a request is successful, the following will also be returned:
- success_message
  
  success_message holds the success message, for this particular request in HTML.
If a request comes back as failing, the following will also be returned:
- errors
  
  Problems with a request be listed in the, errors array. The following errors may be returned:
  - invalid_list
  - invalid_email
  - subscribed
  - invite_only_list
  - closed_list
  - mx_lookup_failed
  - black_listed
  - not_white_listed
  - over_subscription_quota
  - already_sent_sub_confirmation
  - settings_possibly_corrupted
  For example, sending a request with an invalid email address,
```
        {
           "email" : "invalid email",
           "list" : "mylist"
        }
```
  Will return a JSON document, like this:
```
        {
           "email" : "",
           "redirect" : {
              "query" : "list=mylist&email=&status=0&rm=sub_confirm&errors[]=invalid_email",
              "using_with_query" : 1,
              "url" : "http://example.com/alt_url_sub_confirm_failed.html",
              "using" : 1
           },
           "errors" : {
              "invalid_email" : 1
           },
           "status" : 0,
           "error_descriptions" : {
              "invalid_email" : "<h1>Double Check Your Email Address</h1> [...]"
           },
           "list" : "mylist"
        }
```
  email and, list will be returned as you sent them, status will have a value of, 0 (meaning there was a problem), and the error array will have one entry in it, with a key of, invalid_email (the error), and a value of, 1.
- error_descriptions
  
  Also on failure, another array named, error_descriptions will also be returned. This holds a description of any errors produced. Keys will be named the same as the errors, but the values will be a description of what the error means, in HTML.
Make sure your requests are made with the list and email params set in your POST DATA, and set the Content-Type to application/json. The returned JSON will be sent with a Content-Type of, application/json

Dada Mail supports custom URL redirects, for many of its subscription request functions, and these custom redirect settings are also passed to you in the return JSON document.
redirect

Both successful and failed requests may also pass a redirect array, with the following:
- url
  
  url holds the URL used to redirect, for the particular request made.
- query
  
  query holds a query string you may append to the URL, if you would like to pass information to the redirect URL.
- using
  
  using is set to, 1 if the mailing list settings say that this redirect is enabled.
- using_w_qa
  
  using_w_qa is set to, 1 if the mailing list settings say that this redirect is enabled, and using the query string.
All these parameters are passed to you, but it is your choice on whether you want to use or ignore them.

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?f=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/jquery-1.8.2.min.js"></script>
        
        <link rel="stylesheet" href="http://example.com/dada_mail_support_files/static/css/colorbox/colorbox.css">
        <script src="http://example.com/dada_mail_support_files/static/javascripts/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-1.8.2.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: */
                $(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:

DadaMailURL

DadaMailURL should hold the URL to your Dada Mail

Optionally, the following paramaters may also be passed:

list

list should hold a list short name of the list you want your subscription form to be for. If no list parameter is passed, the subscripton form made will have a dropdown widget to allow your user to select which mailing list they would like to subscribe to.
modal

modal (default: 1) allows you to set if the results of requests submitted from the form are shown in a modal window, or if results are shown in the entire browser window, by redirecting directly to Dada Mail.

To show in the modal window, modal should be set to, 1, to redirect, modal should be set to, 0

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: */
                $(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:

targetForm

This should hold the id of the form you would like this plugin to control.

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:

flavor

Set to, subscribe
list

list holds the list short name of the mailing list you want to subscribe to
email

email is the form field used by your user, to type in their email address in.

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:

mode

mode may be set to either, json to send a json request, or jsonp to send a jsonp request. By default, this paramater is set to, jsonp.

jsonp will need to be used when you want to use a subscription for across different domains.
LoadingMessage

LoadingMessage holds HTML text, that's then shown as a, "loading..." message, while the request is sent to Dada Mail.
LoadingError

LoadingError holds HTML text, that's then shown if there's a communication problem with Dada Mail.

Perl API

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

http://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, Your 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:

http://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:

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

Subscription Cookbook

Subscription Cookbook

RESTful API

Situations That Require Additional User Input

JSONP

Example Implementations

JavaScript/jQuery

Perl

PHP

Python

Ruby

jQuery Plugin

CreateSubscribeForm

Initialization Paramaters

Shared Optional Paramaters

Perl API

Command Line Utility - subscribe_email.pl

Arguments

PHP Example

Other examples

FormMail Integration

TFmail Integration

Dada Mail Project

Download

Installation

Support

Subscription Cookbook

Subscription Cookbook

How to Subscribe an Email Address to a Mailing List

RESTful API

Situations That Require Additional User Input

JSONP

Example Implementations

JavaScript/jQuery

Perl

PHP

Python

Ruby

jQuery Plugin

CreateSubscribeForm

Initialization Paramaters

Modal

Shared Optional Paramaters

Perl API

Command Line Utility - subscribe_email.pl

Arguments

PHP Example

Other examples

FormMail Integration

TFmail Integration

Dada Mail Project

Download

Installation

Support