iReach Documentation

iReach is a standalone newsletter manager developed in Ruby on Rails (currently only rails version 3.2) with a mailer and simple access control. In the event you want to integrate the Newsletter gem and/or the Mail Manager gem into your existing application, you can access those gems separately.

The documentation below describes one way to get up and running. Of course you may want to do things differently depending on your use case and environment.

Installation

Requirements

  • Rails 3.2.x (currently tested against rails 3.2.21)
  • Ruby 2.1.5
  • Bundler
  • Database (tested against MySQL and PostgreSQL databases).
  • Lynx

Optional Dependencies

  • RVM - How we control our ruby environment
  • Currently we use GitHub for our repository

Install iReach

  • clone the source
     git clone https://github.com/LoneStarInternet/iReach.git
  • go into your application directory
     cd iReach
     bundle install

Configuration

  • set up your database config
    • edit config/database.yml to fit your db
    • You can edit .env.development or copy to .env.production and edit to:
      • set your SERVER_PORT as appropriate for your installation
      • configure ENV variables for your database (user, password, and host)
      • Generate a new MAIL_MANAGER_SECRET:
        • export RAILS_ENV=production
          
          (if you want production instead of development)
          bundle exec rails runner "puts SecureRandom.hex(128).to_s"
        • replace the value in .env.development or .env.production depending on which you are using
  • create the tmp folder
  • set up your config/mail_manager.yml to fit your needs - docs are in file
    • More instructions here
  • set up your config/newsletter.yml to fit your needs - docs are in file
    • More instructions here
  • migrate your database
     bundle exec rake db:migrate
  • precompile your assets if you're in production
     bundle exec rake assets:precompile
  • set up your application's outgoing email settings (edit config/environments/[Rails.env].rb)
    • defaults to sendmail commandline currently
    • NOTE: the user your application runs under may need special permissions to set the RETURN_PATH(where your emails bounce to) if you use sendmail command

Data Initialization

  • Import an example design to start with
     rake newsletter:import_example_design
  • log in with the default user:
  • You can then go to Setup -> Users and change the email/password

Start Services

NOTE: remember to prefix with "RAILS_ENV=production" to run in production

  • Delayed Job https://github.com/collectiveidea/delayed_job(docs)
      bundle exec script/delayed_job start
  • web server (may be different debending on your deployment)
      bundle exec rails s
  • If you deploy new code, don't forget to restart delayed job
    ./script/delayed_job restart

Here are more details about the Newsletter gem and the Mail Manager gem.

Design Guide

  1. Let's start with creating a design for your newsletter.
    Select Setup -> Newsletter Designs.
  2. iReach comes with an example 2 column mobile-friendly newsletter (responsive) design. See 'Data Initialization' above for instructions on how to import the design. If you select [Edit] you will see you have the following options.
    • Name - This is the design name. You will select this name when creating a new Newsletter below.
    • Description - You may enter a description that may help you remember details about the design.
    • Design Filename - The design filename will allow you to use an editor of your choice to make' revisions to the design once it has been created if you prefer.
    • Style Sheet - Add your styles here. Should not include <style> tags. You can include @media rules that will be applied properly in the editor and when creating emails. See the example design for an example.
    • Html text - This is the html code that creates the design. Do not include <head> or <body> tags (those are generated for you). It uses Ruby markup. You will construct the page using html and ruby markup entering the code that would normally appear between the <body> and </body> tags. Keep in mind that email clients don't handle div tags and such as well as browsers, so it is best to research what tags are supported by your target email clients. For each image in your design you will want to include the path to the image which is defined in the installation of iReach and may be referenced as follows:
      <img src="<%= Conf.site_url %>/images_folder/image.jpg">
      Also, for each Area in your design you will want to add a render tag.
      <%= render area_name %>
    • Areas - You will build up a newsletter using elements within Areas. Within each Area you will be able to drag/drop elements to reorder your newsletter content. In the example design, there are left_column and right_column Areas.
    • Unsubscribe - You will usually want to allow your subscribers to unsubscribe from the mailing list. To create an unsubscribe link you'll want to add something like this to the HTML for your newsletter:
      To remove your address from this newsletter list, please click <%= link_to "Link Text Here", '#UNSUBSCRIBE_URL##' %>
  3. Elements are encapsulating snippets of html code which will format each article, or piece of a newsletter. Elements are dragable in the newsletter editor so the html must be encapsulated, you can't have just part of a table in a element or that will break the ability to reorder elements. Elements have an Area and a Design. To access Elements for a Design, select [Manage Elements] at the bottom of the Design editor. This will give you a list of available elements for that Design. Select [New Newsletter Element] to create a new Element or select [Edit] for an Element to edit it. Elements have the following attributes:
    • Name - Descriptive name for the element. You will select this element name from a drop down of available elements when creating your newsletter.
    • Description - You may enter a description that may help you remember details about the element.
    • Element Filename - The element filename will allow you to use an editor of your choice to make revisions to the element once it has been created if you prefer.
    • Html text - This is the html code that creates the element. It uses Ruby markup. When you create fields (more description below), you need to place them in your Element using Ruby markup tags. The most basic tag is:
      <%= field_name %>
      You can see some other tags in the example elements provided, but be aware you can use any valid Ruby markup in the element.
  4. Fields are the content in an Element that varies for each newsletter. For instance you can add a text field called headline to the element. The article body is typically a type of Textarea. You can also add a link, image or attachment as an Inlineasset. NOTE: The application does not resize images, so you will want to properly size the image before uploading it.
  5. Now that we are done with the design, see the User's Manual below for creating a Newsletter.

User's Manual

Newsletters

  1. To create a Newsletter
    Select Newsletters from the navigation menu.
  2. You will be presented with a list of existing newsletters you can 'Publish/Un-Publish', 'Edit', or 'Delete' as well as the 'New Newsletter' button to create a new newsletter.
  3. From the newsletter list at 'Newsletters', you can 'Publish/Un-Publish' your newsletter. Published newsletters are displayed at the url / by default.
  4. When you select the 'New Newsletter' button, you will be presented with a form to select a design to use for this Newsletter, and enter a Name for the Newsletter which you will use to identify the Newsletter when creating a Mailing.
  5. Once you have submitted the initial selections to create a new Newsletter (or have selected 'Edit' for an existing newsletter from the newsletters list) you will be presented with the WYSIWYG interface to compose the Newsletter contents.
  6. There is a dropdown selection of elements for each area in the newsletter design.
  7. Select an Element to add to the Newsletter and click [Add Element]. This will load the form to populate the element. Text type fields will appear as text boxes, Textarea type fields will appear as text areas, and Inlineasset type fields will provide both a text field in which you could enter a url and an upload field where you could browse for an asset. Complete the fields in your Element and click [Submit].
  8. You are then returned to the WYSIWYG Newsletter editor. After you have several Elements in an Area, you may drag the Elements in the interface within the element's area to order them. You will also notice that when you mouse over an Element a top tab will display the Delete and Edit links allowing you to manage the elements composing the newsletter.
  9. You can use the 'Newsletter Window Size' options to see what your newsletter will look like at different email client window sizes. With the latest version we added a 320x568 version that will approximate an iPhone 5 window size.
  10. If you ever want open the email version of the newsletter in a browser you can use the url: http(s)//yourserver.com/newsletters/[newsletter id]/email. Keep in mind there are no <head> or <body> tags in the email version.

Mailings

  1. When you are ready to mail your Newsletter
    Select Mailings -> Mailings.
  2. Here you will be presented with a list of prior Mailings.
    • You may select [Send Test] to send a test message to an email address you enter.
    • If the Mailing has not been sent (Status = pending or scheduled), you may select [Edit] to edit the Mailing or you may select [Schedule] to schedule the Newsletter to be sent at the scheduled time.
    • If the Mailing has been sent, you can select [Messages] to view a list of contacts with various statuses based on the success or failure of the email message sent to them, or you may select [Bounces] to view a list of bounced emails.
  3. When creating or editing a Mailing, a Mailing has the following attributes:
    • Email subject - This will allow you to identify the mailing in the Mailing list.
    • From email address - This sets the from email address when the Newsletter is mailed. This can be in the format: "Some Name" <email@address.com> allowing you to have an alias for the email address. The default value is configured in /config/mail_manager.yml.
    • Select a newsletter - Select your Newsletter name from the list.
    • Send emails at - Select a date and time to send your Newsletter. NOTE: The mailing will initially be created with a status of "pending". It will be necessary to select the [Schedule] button to trigger sending the email at the scheduled time.
    • Send to these mailing lists - Select the checkboxes for the lists you wish to include in your mailing.
right side image
bottom image