Newsletter Documentation

The newsletter gem is designed to allow developers to integrate an interface to design and compose email correspondence into their applications. The design interface allows a competent HTML developer to design a newsletter template and elements. A user then can utilize the design in the wysiwyg interface to create newsletters, news-releases, product announcements, etc ...

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


The procedure below should be followed if you want to integrate the Newsletter 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 'newsletter', '~>3' # this points to the latest rails stable 3.2.x version
    gem 'newsletter', git: '', branch: 'rails3.2.x'
    # for the bleeding edge rails 3.2.x version
  • Then bundle install
    bundle install
  • generate and configure the newsletter settings file at config/newsletter.yml: (replace table prefix with something... or nothing if you don't want to scope it)
    rake newsletter:default_app_config[table_prefix]
  • generate migrations
    rake newsletter:import_migrations
  • migrate the database
    rake db:migrate

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 Newsletter.abilities # this is what you ADD


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

If they need to at least log in to MANAGE designs/newsletters, set the following in their config/newsletter.yml:

    designs_require_authentication: true
    newsletters_require_authentication: true

If they need a certain role to MANAGE designs/newsletters, the following in their config/newsletter.yml:

    - admin
    - designer
    - 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


Engine Settings

These settings set important data related to how the application acts.... see below for descriptions. This file is used to configure the newsletter 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/newsletter.local.yml' is created it will override anything in the 'config/newsletter.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/newsletter.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 newsletter tables with ... or [] for nothing
     bundle exec rake newsletter:default_app_config[table_prefix_]

Setting Descriptions

(for config/newsletter.yml)

  • site_url: used in various places to get the url of the site (such as in mailings templates)
  • archive_layout: layout used for public facing pages like the archive
  • layout: layout used for newsletter administration pages
  • site_path: used in case your rails site is at a sub-path of the site url
  • designs_require_authentication: whether you need to log in to manage designs (recommended)
  • design_authorized_roles: array of role names that can manage designs
  • newsletters_require_authentication: whether you need to log in to manage newsletters(everyone can currently see them.. devise your own abilities if you want to require login for these)
  • newsletter_authorized_roles: array of role names that can manage newsletters
  • roles_method: the method which gives a list of role names for the 'current_user' of the app, if it answers with an array of names as strings with 'roles' or a string with 'role' this doesn't have to be set
  • designs_path: path from your rails root where design templates are saved
  • asset_path: where your newsletter assets are saved(images, pdfs, etc for newsletter instances-uploaded with carrier_wave)
  • table_prefix: prefixes all newsletter tables with a string to avoid collisions with your app - should be set BEFORE running migrations
  • 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


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

Clone the repository:

    git clone

Checkout the rails3.2.x branch:

    cd newsletter
    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:

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