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.
- Rails 3.2.x (currently tested against rails 3.2.21)
- Ruby 2.1.5
- Database (tested against MySQL and PostgreSQL databases).
- RVM - How we control our ruby environment
- Currently we use GitHub for our repository
NOTE: remember to prefix with "RAILS_ENV=production" to run in production
Here are more details about the Newsletter gem and the Mail Manager gem.
- Let's start with creating a design for your newsletter.
Select Setup -> Newsletter Designs.
- 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##' %>
- 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.
- 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.
- Now that we are done with the design, see the User's Manual below for creating a Newsletter.
- To create a Newsletter
Select Newsletters from the navigation menu.
- 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.
- From the newsletter list at 'Newsletters', you can 'Publish/Un-Publish' your newsletter. Published
newsletters are displayed at the url / by default.
- 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.
- 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.
- There is a dropdown selection of elements for each area in the newsletter design.
- 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].
- 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.
- 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.
- 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.
- When you are ready to mail your Newsletter
Select Mailings -> Mailings.
- 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.
- 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" <firstname.lastname@example.org>
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.