Loading

Bridge - Discussion Lists and Email Sending from your Mail Reader

Bridge

Description

Bridge is one of the most powerful plugins that comes with Dada Mail. Once installed and configured, Bridge allows you to both send Announce Only messages from your mail reader, as well as set up a Discussion Lists, where all members of your mailing list can join in and start talking to each other via email.

Bridge also allows you to set up your mailing list as an email discussion list: Each member of your mailing list may send messages to the List Email, which will then be sent to the entire mailing list.

Messages are received by sending to the List Email. The List Email will need to be set up manually for each mailing list you will want to use Bridge and can be either a regular POP3 email account, which Bridge will log into on a schedule, or an Email Forward, which will forward the message directly to the plugin itself.

User Guide

The below documentation goes into detail on how to install and configure Bridge. A user guide for Bridge is available in the Dada Mail Manual chapter, Using Bridge:

http://dadamailproject.com/pro_dada/using_bridge.html

For more information on Pro Dada/Dada Mail Manual:

http://dadamailproject.com/purchase/pro.html

Obtaining The Plugin

Bridge is located in the, dada/plugins directory of the Dada Mail distribution, under the name: bridge.cgi

Installation

This plugin can be installed during a Dada Mail install/upgrade, using the included installer that comes with Dada Mail. Under, Plugins/Extensions, check, Bridge.

Manual installation isn't recommended, but is outlined later in this doc.

Mailing List Configuration

Once you've installed Bridge, you may access it via the List Control Panel. Bridge is located in the left hand menu, under, Plugins.

Before you can start using Bridge for your mailing list, there's two things that will have to be done: the first is to enable the plugin; the second is to configure your List Email.

Enable Bridge

In Bridge's control panel, under, General, uncheck the option, Disable sending using this method. Save your changes.

List Email Configuration

The List Email is the address that you will be sending your email messages, to be broadcasted to your entire mailing list.

There's a few constraints you want to keep in mind when creating the List Email. Most likely, the address is going to be on the same domain that you install Dada Mail and it's going to be an address that you're not already using; either somewhere else in Dada Mail, or as another general email address.

The List Email can either be a normal POP3 email account, or a Mail Forward.

A POP3 account is fairly easy to set up, as its similar to setting up any mail reader - and Bridge basically acts as a mail reader, while checking messages sent to this account. It does require you to set up an additional cronjob (scheduled task), to check this account on a regular schedule; for example: every 5 minutes.

A Mail Forward does not need this additional cronjob created, but may be slightly trickier to set up on the mail forward side of things. Before attempting, make sure that you can set up a mail forward that can Pipe to a Program, and not simply forward to another email address.

Setup As: POP3 Account

Toggle the radio buttons labeled, Setup As to, POP3 Account.

Create a new POP3 Account. This email account will be the email address you will send messages to. Additional fields should be shown, where you may plug in the POP3 Login information for this email address ( POP3 Server, POP3 Username, POP3 Password, etc.). You may test that the login credentials are working by clicking the button labeled, Test POP3 Login Information....

Once the login information works with Bridge, Save your changes.

Set the cronjob

Once you've saved your POP3 login info, set the cronjob for Bridge. An example of a cronjob that should work, can be found in the textbox labeled, cronjob command using curl (example). We recommend setting the cronjob to run every 5 minutes, or less.

Other options for cronjobs exist and are detailed, below, if the provided example doesn't work.

Setup As: Mail Forward

Toggle the radio buttons labeled, Setup As to, Email Forward. An example of the command you'll need to work with Bridge will be shown.

Create a new Mail Forward, and use the example shown as a starting point for the piped command. Here's an example,

 |/home/youraccount/public_html/cgi-bin/dada/plugins/bridge.cgi --inject --list yourlist

If you're setting the command in cPanel (or something similar) and it asks you to, "enter a path relative to your home directory", you may need to simply remove the "pipe" | and the path to your home directory /home/youraccount, plugging in this, instead:

        public_html/cgi-bin/dada/plugins/bridge.cgi --inject --list yourlist

Testing Bridge.

Once you've enabled Bridge, and set up the List Email, it's time to test the plugin. Simply send a message to your List Email. To make things easier, make sure to send the message from the List Owner's email address, which is allowed to send to both announce-only and discussion type mailing lists. If a message is sent out to your entire mailing list, congratulations: Bridge is working.

Additional Mailing List Configuration

In Bridge's List Control Panel and below, List Email Configuration section, are additional settings you may customize, depending on how you'd like your mailing list to function.

Advanced Topics

Plugin Configuration Settings

The below settings are available to you, if you wish to further configure Bridge. These settings can be configured inside your .dada_config file.

First, search and see if the following lines are present in your .dada_config file:

 # start cut for plugin configs
 =cut

 =cut
 # end cut for plugin configs

If they are present, remove them.

You can then configure the plugin variables on these lines:

        Bridge => {
        
                Plugin_Name                         => undef,
                Plugin_URL                          => undef,
                Allow_Manual_Run                    => undef,
                Manual_Run_Passcode                 => undef,
                MessagesAtOnce                      => undef,
                Soft_Max_Size_Of_Any_Message        => undef,
                Max_Size_Of_Any_Message             => undef,
                Allow_Open_Discussion_List          => undef,
                Room_For_One_More_Check             => undef,
                Enable_POP3_File_Locking            => undef,
                Check_List_Owner_Return_Path_Header => undef,
                Check_Multiple_Return_Path_Headers  => undef,
        
        },

Plugin_Name

The name of the plugin. By default, Bridge.

Plugin_URL

Sometimes, the plugin has a hard time guessing what its own URL is. If this is happening, you can manually set the URL of the plugin in Plugin_URL.

Allow_Manual_Run

Allows you to invoke the plugin to check and send awaiting messages via a URL.

Manual_Run_Passcode

Allows you to set a passcode if you want to allow manually running the plugin.

MessagesAtOnce

You can specify how many messages you want to have the program actually handle per execution of the script by changing the, MessagesAtOnce variable. By default, it's set conservatively to, 1.

Max_Size_Of_Any_Message

Sets a hard limit on how large a single message can actually be, before you won't allow the message to be processed. If a message is too large, it'll be simple deleted. A warning will be written in the error log, but the original sender will not be notified.

Soft_Max_Size_Of_Any_Message

Like its brethren, Max_Size_Of_Any_Message Soft_Max_Size_Of_Any_Message sets the maximum size of a message that's accepted, but If the message falls between, Soft_Max_Size_Of_Any_Message and, Max_Size_Of_Any_Message a, "Your email message is too big!" email message will be sent to the original poster.

Set the size in octects.

Allow_Open_Discussion_List

If set to, 1 a new option will be available in Bridge's list control panel to allow you to have a discussion list that anyone can send messages to.

Room_For_One_More_Check

Room_For_One_More_Check looks to see how many mass mailings are currently in the mass mailing queue. If its at or above the limit set in $MAILOUT_AT_ONCE_LIMIT, Bridge will not attempt to look for and (possibly) create another mass mailing to join the queue.

Enable_POP3_File_Locking

When set to, 1, Bridge will use a simple lockfile scheme to make sure that it does not check the same POP3 account at the same time another copy of the plugin is doing the exact same thing, saving you from potentially sending out multiple copies of the same message.

Sometimes, the simple POPp3 lock in Dada Mail gets stale, and a deadlock happens. Setting this configuration to, 0 disables lockfiles. Stale locks will be deleted by the app after a day of being stale.

Check_List_Owner_Return_Path_Header

When testing the validity of a received message, Dada Mail will look to see if the, Return-Path header matches what's set in the, From header. If they do not match, this test fails and the message will be rejected. Setting, Check_List_Owner_Return_Path_Header to, 0 will disable this test.

Check_Multiple_Return_Path_Headers

Check_Multiple_Return_Path_Headers is another validity test for received messages. This time, the message is looked to see if it has more than one Return-Path header. If it does, it is rejected. If you set, Check_Multiple_Return_Path_Headers to, 0, this test will be disabled.

Advanced Cronjobs

A cronjob will need to be set for Bridge, if you have a mailing list that uses a POP3 account for its List Email. If you are using Mail Forwards only, no cronjob needs to be set.

Generally, setting the cronjob to have Bridge run automatically just means that you have to have a cronjob access a specific URL. The URL looks something like this:

 http://example.com/cgi-bin/dada/plugins/bridge.cgi?run=1&verbose=1

Where, http://example.com/cgi-bin/dada/plugins/bridge.cgi is the URL to your copy of bridge.cgi

You'll see the specific URL used for your installation of Dada Mail in the web-based control panel for Bridge, under the label, Manual Run URL:

This should work for most Cpanel-based hosting accounts.

Here's the entire cronjob explained:

In this example, I'll be running the script every 5 minutes ( */5 * * * * ) - tailor to your taste.

        */5 * * * * /usr/local/bin/curl -s --get --data run=1\;verbose=0\; --url http://example.com/cgi-bin/dada/plugins/bridge.cgi

Disallowing running Bridge manually (via URL)

If you DO NOT want to use this way of invoking the program to check awaiting messages and send them out, make sure to set the plugin config variable (which we'll cover below) Allow_Manual_Run to, 0.

Security Concerns "Manual_Run_Passcode"

If you'd like, you can set up a simple Passcode, to have some semblence of security over who runs the program. Do this by setting the, plugin config, Manual_Run_Passcode to a password-like string:

        Manual_Run_Passcode                 => 'sneaky',

In this example, you'll then have to change the URL in these examples to:

 http://example.com/cgi-bin/dada/plugins/bridge.cgi?run=1&passcode=sneaky

Additional Options

You can control quite a few things by setting variables right in the query string:

Notes on Setting the Cronjob for curl

You may want to check your version of curl and see if there's a speific way to pass a query string. For example, this:

 */5 * * * * /usr/local/bin/curl -s http://example.com/cgi-bin/dada/plugins/bridge.cgi?run=1&passcode=sneaky

Doesn't work for me.

I have to use the --get and --data flags, like this:

 */5 * * * * /usr/local/bin/curl -s --get --data run=1\;passcode=sneaky --url http://example.com/cgi-bin/dada/plugins/bridge.cgi

my query string is this part:

 run=1\;passcode=sneaky

And also note I had to escape the, ; character. You'll probably have to do the same for the & character.

Finally, I also had to pass the actual URL of the plugin using the --url flag.

Command Line Interface

This plugin can also be invoked in a command line interface.

To use Bridge via the command line, first change into the directory that Bridge resides in, and issue the command:

 ./bridge.cgi --help

Command Line Interface for Cronjobs:

You can also invoke bridge.cgi from the command line interface for cronjobs. The secret is to actually have two commands in one. The first command changes into the same directory as the bridge.cgi script, the second invokes the script with the parameters you'd like.

For example:

 */5 * * * * cd /home/myaccount/cgi-bin/dada/plugins; /usr/bin/perl ./bridge.cgi  >/dev/null 2>&1

Where, /home/myaccount/cgi-bin/dada/plugins is the full path to the directory the bridge.cgi script is located.

Manual Installation

Configuring Bridge's Plugin Side

#1 Change the permissions of the, bridge.cgi script to, "755"

Find the bridge.cgi script in your dada/plugins directory. Change its permissions to, 755

#2 Configure your outside config file (.dada_config)

You'll most likely want to edit your outside config file (.dada_config) so that it shows Bridge in the left-hand menu, under the, Plugins heading.

First, see if the following lines are present in your .dada_config file:

 # start cut for list control panel menu
 =cut

 =cut
 # end cut for list control panel menu

If they are, remove them.

Then, find these lines:

 #                                      {-Title      => 'Discussion Lists',
 #                                       -Title_URL  => $PLUGIN_URL."/bridge.cgi",
 #                                       -Function   => 'bridge',
 #                                       -Activated  => 1,
 #                                      },

Uncomment the lines, by taking off the, "#"'s:

                                        {-Title      => 'Discussion Lists',
                                         -Title_URL  => $PLUGIN_URL."/bridge.cgi",
                                         -Function   => 'bridge',
                                         -Activated  => 1,
                                        },

Save your .dada_config file.

You can now log into your List Control Panel and under the, plugins heading you should now see a link entitled, "Bridge". Clicking that link will allow you to set up Bridge.

Debugging

Debugging your POP3 account information

The easiest way to debug your POP3 account info is to actually test it out.

If you have a command line, drop into it and connect to your POP3 server, like so:

 prompt:]telnet pop3.example.com 110
 Trying 12.123.123.123...
 Connected to pop3.example.com.
 Escape character is '^]'.
 +OK <37892.1178250885@hedwig.summersault.com>
 user user%example.com
 +OK 
 pass sneaky
 +OK 
 list

In the above example, pop3.example.com is your POP3 server. You'll be typing in:

  user user%example.com

and:

  pass sneaky

(changing them to their real values) when prompted. This is basically what bridge.cgi does itself.

If you don't have a command line, try adding an account in a desktop mail reader. If these credentials work there, they'll most likely work for bridge.cgi.

If your account information is correct and also logs in when you test the pop3 login information through bridge.cgi yourself, check to see if there isn't an email filter attached the account that looks at messages before they're delivered to the POP3 Mailbox and outright deletes messages because it triggered a flag.

This could be the cause of mysterious occurences of messages never reaching the POP3 Mailbox.

COPYRIGHT

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

LICENSE

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