Extension - Mailer - obsolete

This page is mostly a duplicate of How To Use The Mailer Extension which I just updated with the repository change, and some other mostly minor editing. This page should be retired.

The Mailer Extension is responsible for an enormous amount of traffic on the Radiant mailing list. People ask questions from installation to usage, from not being able to configure it properly to not being able to send e-mails.

The source of all evil is the lack of documentation of the Mailer Extension, being the README and the topics on the mailing list the only ones available. But, searching the mailing list and reading all the topics related to the Mailer Extension to find the answers you want can be very tiresome (believe me, I’ve done this). So, I thought I could help the community and put together the most common information about the Mailer Extension.

As I’m using the Mental branch, all the information here will be related to this version. Enough talking, let’s get our hands dirty :)

Installation

The way to get the Mailer Extension is by subversion. So, from the Radiant root directory do as follow:

cd vendor/extensions
sudo svn co http://svn.radiantcms.org/radiant/trunk/extensions/mailer

(The

rake db:migrate:extensions

command is not necessary for the Mailer extension because it doesn’t have anything to add to the database.)

The Mailer Extension is installed, now it’s time to make it work.

Configuration

The Mailer Extension is built upon the ActionMailer framework, so we need to configure Radiant to use it.

This can be done in the

config/environment.rb

file in the

config/environments/

directory. I prefer doing so in the

config/environment.rb

file, so I can use it from production, test or development environmets.

Edit the

config/environmemt.rb

and find the line that reads

# Skip frameworks you're not going to use
config.frameworks -= [ :action_web_service, :action_mailer ]  

remove

:action_mailer

from the list

# Skip frameworks you're not going to use
config.frameworks -= [ :action_web_service ]

now, add the following configuration parameters (I put it at the end of the file, just before the line that reads

require "status"

# Configure ActionMailer for Mailer extension
ActionMailer::Base.smtp_settings = {
  :address => "your.smtp.server",
  :port => 25,
  :domain => "your.domain" 

the code above is based on my own configuration. For a complete list of parameters have a look at the ActionMailer::Base Configuration Options.

That would be enough to make the Mailer Extension work, but after configuring the

ActionMailer::Base

as above, for some strange reason, it was still not sending e-mails. Everything was fine, the Mailer Extension was working, no errors, but no e-mails. So I thought I could figure out what was happening adding another line of configuration to the

ActionMailer::Base

on the

config/environment.rb

file

ActionMailer::Base.raise_delivery_errors = true

After I put down this line, e-mails started to be sent (I really don’t know why, any clue?), but as it has made the Mailer Extension work I’ll keep it.

Now, restart your server and let’s create our mailer form.

Using Mailer

1. Create a new page;
2. On the page created, select "Mailer" from the page type dropdown list;
3. Create two new page parts "config" and "email" (you may use "email_html" instead, in order to send hml e-mails).

The config page part

The config page part is where the Mailer configuration parameters are set, for example:

mailers:
  contact:
    subject: my subject
    from: myemail@mydomain
    redirect_to: /where/you/want/visitors/to/go/after/sending/the/email
    recipients: 
      - recipient#1@domain
      - recipient#2@domain

On the second line,

contact

is actualy the name of your Mailer form (more to come), whatever you name your Mailer form, substitute

contact

by it. This is because you can have many Mailer forms on the same page, so the Mailer Extension needs to know which one you’re talking about.

The next lines are self explanatory, I think :)

Warning: config is a YAML formated file, so INDENTATION MATTERS!

The body page part

The boby page part is where we code our Mailer form. The example below is based on a test form I was doing:

<r:mailer:form name="contact">
    Name:<br />
    <r:mailer:text name="name" /><br />
    E-mail:<br />
    <r:mailer:text name="email" /><br />
    Subject:<br />
    <r:mailer:text name="subject" /><br />
    Message:<br />
    <r:mailer:textarea name="body" /><br />
   <r:mailer:submit value="Send" />
</r:mailer:form>

As you can see, there is a subject field. The text entered on this field will replace the one on the

config

part. I’ll let other experimentations to you ;)

The tags available for building the form are listed on the Mailer Extension README.

The email page part

The email page part is where we build our e-mail template. For example, based on the previous Mailer form, we could have an e-mail template like this:

Name: <r:mailer:get name="name"/>
E-mail: <r:mailer:get name="email"/>
Subject: <r:mailer:get name="subject"/>
Message: <r:mailer:get name="body"/>

The

<r:mailer:get name="fieldname" />

is used the get the values entered by the user on the Mailer form.

The End

This is not an extensive tutorial about using the Mailer Extension, but I think it covers the basics. I hope this may help someone in anyway.