Mail Manager Documentation

The mail manager gem is designed to allow developers to integrate an interface to manage mailing lists, schedule email mailings, allow users to subscribe/unsubscribe from lists by contacts, view reports of bounces into their applications.

iReach integrates the Newsletter and Mail Manager gems into a stand alone application.

Installation

The procedure below should be followed if you want to integrate the Mail Manager gem into your existing application. If you want to install the iReach standalone newsletter and mailer follow the instructions here.

  • Edit your Gemfile and add one of the following lines
    gem 'mail_manager', '~>3' # this points to the latest rails stable 3.2.x version
    OR
    gem 'mail_manager', git: 'https://github.com/LoneStarInternet/mail_manager.git', branch: 'rails3.2.x'
    # for the bleeding edge rails 3.2.x version
  • Then bundle install
    bundle install
  • generate and configure the mail manager settings file at config/mail_manager.yml: (replace table prefix with something... or nothing if you don't want to scope it)
    rake mail_manager:default_app_config[table_prefix]
  • generate migrations
    rake mail_manager:import_migrations
  • migrate the database
    rake db:migrate
  • Generate delayed_jobs (this is the only job runner we support right now):
    rails g delayed_job:active_record
  • Create an account on your email server that will receive bounces from your mailings (and allow POP)... configure in the following file:

    Add your routes to config/routes.rb (you can say where with at: '/path')
    mount MailManager::Engine, at: '/admin/mail_manager'

Securing your App

We implemented CanCan. If you'd like to secure your actions to certain users and don't currently have any authorization in your app, you can follow the following steps if you want an easy config.. or you could make it more finely grained.. currently its all or nothing:

If you don't have an app/models/ability.rb (ie. you don't currently use cancan):

    rails g cancan:ability

Next add the mail manager abilities to your file (which should look something like this):

    class Ability
        include CanCan::Ability

        def initialize(user)
          eval MailManager.abilities # this is what you ADD
        end

    end

Next decide whether they just need to log in ... or if they should have a role.

If they need to at least log in, set the following in their config/mail_manager.yml:

 requires_authentication: true

If they need a certain role, the following in their config/mail_manager.yml:

    authorized_roles:
        - admin

If you're using roles, User must either respond to 'roles' or 'role' or you can configure a custom role method on your model and configure it in mail_manager.yml like so:

    roles_method: my_role_names

Configuration

Engine Settings

These settings set important data related to how the application acts.... see below for descriptions. This file is used to configure the mail_manager gem. It works like an older plugin called AppConfig (which I can't find anymore).

  • All environments start with settings from the 'common' section
  • the 'common' settings overridden by the section that matches the environment's name
  • if a file: 'config/mail_manager.local.yml' is created it will override anything in the 'config/mail_manager.yml', so that you can keep development/personal settings out of your source control
  • also ... these files allow the use of erb syntax to set variables with ruby thus allowing ENV variables and such to be used

Initialization/Rebuilding of config file

  • the following rake task will create or update a config/mail_manager.yml file
  • if you already have a file in place it will prefer your settings; but may bring new settings in from an upgraded gem
  • you can use 'spring' in place of bundle exec
  • set 'table_prefix' to what you want to prefix all mail_manager tables with ... or [] for nothing
     bundle exec rake mail_manager:default_app_config[table_prefix_]

Setting Descriptions

(for config/mail_manager.yml)

  • site_url: used in various places to get the url of the site (such as in mailings templates)
  • public_layout: layout used for public facing pages like the unsubscribing and opt-in pages
  • layout: layout used for mail manager administration pages
  • site_path: used in case your rails site is at a sub-path of the site url
  • exception_notification: (grouping for who gets notified of exceptions)
  • to_addresses: an array of recipients for exceptions
  • from_address: who the exception appears to be from
  • requires_authentication: whether the mail manager app requires login
  • authorized_roles: array of role names that can administer the mail manager
  • roles_method: the method that your "current_user" object defines its role names(returns a list of strings)
  • unsubscribe_path: public url for unsubscribing ... this is a prefix and is followed by a message 'guid', defaults to '/listmgr' and routes as '/listmgr/:guid'
  • dont_include_images_domains: a list of domains that won't include images in the email, whether or not the mailing is set to include them
  • sleep_time_between_messages: a timeout between messages to slow the output of emails to your email server; you should probably limit with your mail server itself if possible
  • path_prefix: a prefix to the mail manager routes(defaults to /admin)
  • table_prefix: prefixes all newsletter tables with a string to avoid collisions with your app - should be set BEFORE running migrations
  • default_from_email_address: where any public messages from the app default to for the "FROM:" header
  • secret: a secret for encrypting tokens and guids
  • bounce: (a grouping for 'POP' settings for bounce messages and the RETURN_PATH: header)
  • email_address: the account for POPing bounces and RETURN_PATH
  • login: login for account for POPing
  • password: password for email account for POPing
  • pop_server: POP server
  • port: PORT of pop server
  • ssl: true/false whether you want to enable ssl for pop
  • subscribe_path: public path for double-opt-in 'subscribe' step which sends the email
  • honey_pot_field: used to set a field name which will ignore submissions to the subscribe action if filled
  • double_opt_in_path: path to route the double-opt-in confirmation action to
  • signup_email_address: email address for the FROM: of a double opt in/subscribe email
  • The following 2 might be deprecated soon
    • show_title: can be used in templates/layouts to see whether you should show a title
    • use_show_for_resources: whether to have links to "show" actions - we don't use them really in this app.. and the 'show' actions aren't really currently supported

Development

If you wish to contribute, you should follow these instructions to get up and running:

Clone the repository:

    git clone https://github.com/LoneStarInternet/mail_manager.git

Checkout the rails3.2.x branch:

    cd mail_manager
    git checkout rails3.2.x

Set up your database(currently mysql, sqlite and postgres are supported); you can get an example db file by copying one of the examples:

    cd spec/test_app
    cp config/database.mysql.yml config/database.yml # for mysql
    cp config/database.sqlite.yml config/database.yml # for sqlite

If you'd like to run all the databases, we have a script that does so, but you'll have to set up some additional database(local) configurations:

  cd spec/test_app
  cp config/database.mysql.yml config/database.mysql.local.yml
  cp config/database.postgres.yml config/database.postgres.local.yml
  # then configure those local files to support your settings
  # run the full suite:
  script/full_suite

Please write tests for any new functionality and run the test suite to make sure all tests are passing.

Thanks in advance for your contributions to the project!

right side image
bottom image