<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Class: ActionMailer::Base</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="classHeader">
<table class="header-table">
<tr class="top-aligned-row">
<td><strong>Class</strong></td>
<td class="class-name-in-header">ActionMailer::Base</td>
</tr>
<tr class="top-aligned-row">
<td><strong>In:</strong></td>
<td>
<a href="../../files/lib/action_mailer/base_rb.html">
lib/action_mailer/base.rb
</a>
<br />
</td>
</tr>
<tr class="top-aligned-row">
<td><strong>Parent:</strong></td>
<td>
Object
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
<div id="description">
<p>
Action Mailer allows you to send email from your application using a mailer
model and views.
</p>
<h1>Mailer Models</h1>
<p>
To use Action Mailer, you need to create a mailer model.
</p>
<pre>
$ script/generate mailer Notifier
</pre>
<p>
The generated model inherits from <a
href="Base.html">ActionMailer::Base</a>. Emails are defined by creating
methods within the model which are then used to set variables to be used in
the mail template, to change options on the mail, or to add attachments.
</p>
<p>
Examples:
</p>
<pre>
class Notifier < ActionMailer::Base
def signup_notification(recipient)
recipients recipient.email_address_with_name
bcc ["bcc@example.com", "Order Watcher <watcher@example.com>"]
from "system@example.com"
subject "New account information"
body :account => recipient
end
end
</pre>
<p>
Mailer methods have the following configuration methods available.
</p>
<ul>
<li><tt>recipients</tt> - Takes one or more email addresses. These addresses
are where your email will be delivered to. Sets the <tt>To:</tt> header.
</li>
<li><tt>subject</tt> - The subject of your email. Sets the <tt>Subject:</tt>
header.
</li>
<li><tt>from</tt> - Who the email you are sending is from. Sets the
<tt>From:</tt> header.
</li>
<li><tt>cc</tt> - Takes one or more email addresses. These addresses will <a
href="Base.html#M000364">receive</a> a carbon copy of your email. Sets the
<tt>Cc:</tt> header.
</li>
<li><tt>bcc</tt> - Takes one or more email addresses. These addresses will <a
href="Base.html#M000364">receive</a> a blind carbon copy of your email.
Sets the <tt>Bcc:</tt> header.
</li>
<li><tt>reply_to</tt> - Takes one or more email addresses. These addresses will
be listed as the default recipients when replying to your email. Sets the
<tt>Reply-To:</tt> header.
</li>
<li><tt>sent_on</tt> - The date on which the message was sent. If not set, the
header wil be set by the delivery agent.
</li>
<li><tt>content_type</tt> - Specify the content type of the message. Defaults
to <tt>text/plain</tt>.
</li>
<li><tt>headers</tt> - Specify additional headers to be set for the message,
e.g. <tt>headers ‘X-Mail-Count’ => 107370</tt>.
</li>
</ul>
<p>
When a <tt>headers ‘return-path‘</tt> is specified, that value
will be used as the ‘envelope from’ address. Setting this is
useful when you want delivery notifications sent to a different address
than the one in <tt>from</tt>.
</p>
<p>
The <tt>body</tt> method has special behavior. It takes a hash which
generates an instance variable named after each key in the hash containing
the value that that key points to.
</p>
<p>
So, for example, <tt>body :account => recipient</tt> would result in an
instance variable <tt>@account</tt> with the value of <tt>recipient</tt>
being accessible in the view.
</p>
<h1>Mailer views</h1>
<p>
Like Action Controller, each mailer class has a corresponding view
directory in which each method of the class looks for a template with its
name. To define a template to be used with a mailing, create an
<tt>.erb</tt> file with the same name as the method in your mailer model.
For example, in the mailer defined above, the template at
<tt>app/views/notifier/signup_notification.erb</tt> would be used to
generate the email.
</p>
<p>
Variables defined in the model are accessible as instance variables in the
view.
</p>
<p>
Emails by default are sent in plain text, so a sample view for our model
example might look like this:
</p>
<pre>
Hi <%= @account.name %>,
Thanks for joining our service! Please check back often.
</pre>
<p>
You can even use Action Pack helpers in these views. For example:
</p>
<pre>
You got a new note!
<%= truncate(note.body, 25) %>
</pre>
<h1>Generating URLs</h1>
<p>
URLs can be generated in mailer views using <tt>url_for</tt> or named
routes. Unlike controllers from Action Pack, the mailer instance
doesn‘t have any context about the incoming request, so you‘ll
need to provide all of the details needed to generate a URL.
</p>
<p>
When using <tt>url_for</tt> you‘ll need to provide the
<tt>:host</tt>, <tt>:controller</tt>, and <tt>:action</tt>:
</p>
<pre>
<%= url_for(:host => "example.com", :controller => "welcome", :action => "greeting") %>
</pre>
<p>
When using named routes you only need to supply the <tt>:host</tt>:
</p>
<pre>
<%= users_url(:host => "example.com") %>
</pre>
<p>
You will want to avoid using the <tt>name_of_route_path</tt> form of named
routes because it doesn‘t make sense to generate relative URLs in
email messages.
</p>
<p>
It is also possible to set a default host that will be used in all mailers
by setting the <tt>:host</tt> option in the
<tt>ActionMailer::Base.default_url_options</tt> hash as follows:
</p>
<pre>
ActionMailer::Base.default_url_options[:host] = "example.com"
</pre>
<p>
This can also be set as a configuration option in
<tt>config/environment.rb</tt>:
</p>
<pre>
config.action_mailer.default_url_options = { :host => "example.com" }
</pre>
<p>
If you do decide to set a default <tt>:host</tt> for your mailers you will
want to use the <tt>:only_path => false</tt> option when using
<tt>url_for</tt>. This will ensure that absolute URLs are generated because
the <tt>url_for</tt> view helper will, by default, generate relative URLs
when a <tt>:host</tt> option isn‘t explicitly provided.
</p>
<h1>Sending mail</h1>
<p>
Once a mailer action and template are defined, you can <a
href="Base.html#M000365">deliver</a> your message or create it and save it
for delivery later:
</p>
<pre>
Notifier.deliver_signup_notification(david) # sends the email
mail = Notifier.create_signup_notification(david) # => a tmail object
Notifier.deliver(mail)
</pre>
<p>
You never instantiate your mailer class. Rather, your delivery instance
methods are automatically wrapped in class methods that start with the word
<tt>deliver_</tt> followed by the name of the mailer method that you would
like to <a href="Base.html#M000365">deliver</a>. The
<tt>signup_notification</tt> method defined above is delivered by invoking
<tt>Notifier.deliver_signup_notification</tt>.
</p>
<h1>HTML email</h1>
<p>
To send mail as HTML, make sure your view (the <tt>.erb</tt> file)
generates HTML and set the content type to html.
</p>
<pre>
class MyMailer < ActionMailer::Base
def signup_notification(recipient)
recipients recipient.email_address_with_name
subject "New account information"
from "system@example.com"
body :account => recipient
content_type "text/html"
end
end
</pre>
<h1>Multipart email</h1>
<p>
You can explicitly specify multipart messages:
</p>
<pre>
class ApplicationMailer < ActionMailer::Base
def signup_notification(recipient)
recipients recipient.email_address_with_name
subject "New account information"
from "system@example.com"
content_type "multipart/alternative"
part :content_type => "text/html",
:body => render_message("signup-as-html", :account => recipient)
part "text/plain" do |p|
p.body = render_message("signup-as-plain", :account => recipient)
p.transfer_encoding = "base64"
end
end
end
</pre>
<p>
Multipart messages can also be used implicitly because Action Mailer will
automatically detect and use multipart templates, where each template is
named after the name of the action, followed by the content type. Each such
detected template will be added as separate part to the message.
</p>
<p>
For example, if the following templates existed:
</p>
<ul>
<li>signup_notification.text.plain.erb
</li>
<li>signup_notification.text.html.erb
</li>
<li>signup_notification.text.xml.builder
</li>
<li>signup_notification.text.x-yaml.erb
</li>
</ul>
<p>
Each would be rendered and added as a separate part to the message, with
the corresponding content type. The content type for the entire message is
automatically set to <tt>multipart/alternative</tt>, which indicates that
the email contains multiple different representations of the same email
body. The same body hash is passed to each template.
</p>
<p>
Implicit template rendering is not performed if any attachments or parts
have been added to the email. This means that you‘ll have to manually
add each part to the email and set the content type of the email to
<tt>multipart/alternative</tt>.
</p>
<h1>Attachments</h1>
<p>
Attachments can be added by using the <tt>attachment</tt> method.
</p>
<p>
Example:
</p>
<pre>
class ApplicationMailer < ActionMailer::Base
# attachments
def signup_notification(recipient)
recipients recipient.email_address_with_name
subject "New account information"
from "system@example.com"
attachment :content_type => "image/jpeg",
:body => File.read("an-image.jpg")
attachment "application/pdf" do |a|
a.body = generate_your_pdf_here()
end
end
end
</pre>
<h1>Configuration options</h1>
<p>
These options are specified on the class level, like <tt><a
href="Base.html#M000366">ActionMailer::Base.template_root</a> =
"/my/templates"</tt>
</p>
<ul>
<li><tt><a href="Base.html#M000366">template_root</a></tt> - Determines the
base from which template references will be made.
</li>
<li><tt>logger</tt> - the logger is used for generating information on the
mailing run if available. Can be set to nil for no logging. Compatible with
both Ruby‘s own Logger and Log4r loggers.
</li>
<li><tt>smtp_settings</tt> - Allows detailed configuration for <tt>:smtp</tt>
delivery method:
<ul>
<li><tt>:address</tt> - Allows you to use a remote mail server. Just change it
from its default "localhost" setting.
</li>
<li><tt>:port</tt> - On the off chance that your mail server doesn‘t run
on port 25, you can change it.
</li>
<li><tt>:domain</tt> - If you need to specify a HELO domain, you can do it
here.
</li>
<li><tt>:user_name</tt> - If your mail server requires authentication, set the
username in this setting.
</li>
<li><tt>:password</tt> - If your mail server requires authentication, set the
password in this setting.
</li>
<li><tt>:authentication</tt> - If your mail server requires authentication, you
need to specify the authentication type here. This is a symbol and one of
<tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>.
</li>
<li><tt>:enable_starttls_auto</tt> - When set to true, detects if STARTTLS is
enabled in your SMTP server and starts to use it. It works only on Ruby
>= 1.8.7 and Ruby >= 1.9. Default is true.
</li>
</ul>
</li>
<li><tt>sendmail_settings</tt> - Allows you to override options for the
<tt>:sendmail</tt> delivery method.
<ul>
<li><tt>:location</tt> - The location of the sendmail executable. Defaults to
<tt>/usr/sbin/sendmail</tt>.
</li>
<li><tt>:arguments</tt> - The command line arguments. Defaults to <tt>-i
-t</tt>.
</li>
</ul>
</li>
<li><tt>raise_delivery_errors</tt> - Whether or not errors should be raised if
the email fails to be delivered.
</li>
<li><tt>delivery_method</tt> - Defines a delivery method. Possible values are
<tt>:smtp</tt> (default), <tt>:sendmail</tt>, and <tt>:test</tt>.
</li>
<li><tt>perform_deliveries</tt> - Determines whether <tt>deliver_*</tt> methods
are actually carried out. By default they are, but this can be turned off
to help functional testing.
</li>
<li><tt>deliveries</tt> - Keeps an array of all the emails sent out through the
Action Mailer with <tt>delivery_method :test</tt>. Most useful for unit and
functional testing.
</li>
<li><tt>default_charset</tt> - The default charset used for the body and to
encode the subject. Defaults to UTF-8. You can also pick a different
charset from inside a method with <tt>charset</tt>.
</li>
<li><tt>default_content_type</tt> - The default content type used for the main
part of the message. Defaults to "text/plain". You can also pick
a different content type from inside a method with <tt>content_type</tt>.
</li>
<li><tt>default_mime_version</tt> - The default mime version used for the
message. Defaults to <tt>1.0</tt>. You can also pick a different value from
inside a method with <tt>mime_version</tt>.
</li>
<li><tt>default_implicit_parts_order</tt> - When a message is built implicitly
(i.e. multiple parts are assembled from templates which specify the content
type in their filenames) this variable controls how the parts are ordered.
Defaults to <tt>["text/html", "text/enriched",
"text/plain"]</tt>. Items that appear first in the array have
higher priority in the mail client and appear last in the mime encoded
message. You can also pick a different order from inside a method with
<tt>implicit_parts_order</tt>.
</li>
</ul>
</div>
</div>
<div id="method-list">
<h3 class="section-bar">Methods</h3>
<div class="name-list">
<a href="#M000362">controller_name</a>
<a href="#M000363">controller_path</a>
<a href="#M000365">deliver</a>
<a href="#M000368">deliver!</a>
<a href="#M000361">mailer_name</a>
<a href="#M000359">mailer_name</a>
<a href="#M000360">mailer_name=</a>
<a href="#M000364">receive</a>
<a href="#M000366">template_root</a>
<a href="#M000367">template_root=</a>
</div>
</div>
</div>
<!-- if includes -->
<div id="includes">
<h3 class="section-bar">Included Modules</h3>
<div id="includes-list">
<span class="include-name">AdvAttrAccessor</span>
<span class="include-name"><a href="PartContainer.html">PartContainer</a></span>
<span class="include-name">Quoting</span>
<span class="include-name">Utils</span>
<span class="include-name">ActionController::UrlWriter</span>
<span class="include-name">ActionController::Layout</span>
</div>
</div>
<div id="section">
<div id="attribute-list">
<h3 class="section-bar">Attributes</h3>
<div class="name-list">
<table>
<tr class="top-aligned-row context-row">
<td class="context-item-name">action_name</td>
<td class="context-item-value"> [R] </td>
<td class="context-item-desc"></td>
</tr>
<tr class="top-aligned-row context-row">
<td class="context-item-name">default_template_name</td>
<td class="context-item-value"> [R] </td>
<td class="context-item-desc"></td>
</tr>
<tr class="top-aligned-row context-row">
<td class="context-item-name">mail</td>
<td class="context-item-value"> [R] </td>
<td class="context-item-desc">
The mail object instance referenced by this mailer.
</td>
</tr>
<tr class="top-aligned-row context-row">
<td class="context-item-name">mailer_name</td>
<td class="context-item-value"> [W] </td>
<td class="context-item-desc"></td>
</tr>
<tr class="top-aligned-row context-row">
<td class="context-item-name">template_name</td>
<td class="context-item-value"> [R] </td>
<td class="context-item-desc"></td>
</tr>
</table>
</div>
</div>
<!-- if method_list -->
<div id="methods">
<h3 class="section-bar">Public Class methods</h3>
<div id="method-M000365" class="method-detail">
<a name="M000365"></a>
<div class="method-heading">
<a href="Base.src/M000365.html" target="Code" class="method-signature"
onclick="popupCode('Base.src/M000365.html');return false;">
<span class="method-name">deliver</span><span class="method-args">(mail)</span>
</a>
</div>
<div class="method-description">
<p>
Deliver the given mail object directly. This can be used to <a
href="Base.html#M000365">deliver</a> a preconstructed mail object, like:
</p>
<pre>
email = MyMailer.create_some_mail(parameters)
email.set_some_obscure_header "frobnicate"
MyMailer.deliver(email)
</pre>
</div>
</div>
<div id="method-M000361" class="method-detail">
<a name="M000361"></a>
<div class="method-heading">
<a href="Base.src/M000361.html" target="Code" class="method-signature"
onclick="popupCode('Base.src/M000361.html');return false;">
<span class="method-name">mailer_name</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<div id="method-M000364" class="method-detail">
<a name="M000364"></a>
<div class="method-heading">
<a href="Base.src/M000364.html" target="Code" class="method-signature"
onclick="popupCode('Base.src/M000364.html');return false;">
<span class="method-name">receive</span><span class="method-args">(raw_email)</span>
</a>
</div>
<div class="method-description">
<p>
Receives a raw email, parses it into an email object, decodes it,
instantiates a new mailer, and passes the email object to the mailer
object‘s <tt><a href="Base.html#M000364">receive</a></tt> method. If
you want your mailer to be able to process incoming messages, you‘ll
need to implement a <tt><a href="Base.html#M000364">receive</a></tt> method
that accepts the email object as a parameter:
</p>
<pre>
class MyMailer < ActionMailer::Base
def receive(mail)
...
end
end
</pre>
</div>
</div>
<div id="method-M000366" class="method-detail">
<a name="M000366"></a>
<div class="method-heading">
<a href="Base.src/M000366.html" target="Code" class="method-signature"
onclick="popupCode('Base.src/M000366.html');return false;">
<span class="method-name">template_root</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<div id="method-M000367" class="method-detail">
<a name="M000367"></a>
<div class="method-heading">
<a href="Base.src/M000367.html" target="Code" class="method-signature"
onclick="popupCode('Base.src/M000367.html');return false;">
<span class="method-name">template_root=</span><span class="method-args">(root)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<h3 class="section-bar">Public Instance methods</h3>
<div id="method-M000362" class="method-detail">
<a name="M000362"></a>
<div class="method-heading">
<span class="method-name">controller_name</span><span class="method-args">(value = nil)</span>
</div>
<div class="method-description">
<p>
Alias for <a href="Base.html#M000359">mailer_name</a>
</p>
</div>
</div>
<div id="method-M000363" class="method-detail">
<a name="M000363"></a>
<div class="method-heading">
<span class="method-name">controller_path</span><span class="method-args">(value = nil)</span>
</div>
<div class="method-description">
<p>
Alias for <a href="Base.html#M000359">mailer_name</a>
</p>
</div>
</div>
<div id="method-M000368" class="method-detail">
<a name="M000368"></a>
<div class="method-heading">
<a href="Base.src/M000368.html" target="Code" class="method-signature"
onclick="popupCode('Base.src/M000368.html');return false;">
<span class="method-name">deliver!</span><span class="method-args">(mail = @mail)</span>
</a>
</div>
<div class="method-description">
<p>
Delivers a <a href="../TMail/Mail.html">TMail::Mail</a> object. By default,
it delivers the cached mail object (from the <tt>create!</tt> method). If
no cached mail object exists, and no alternate has been given as the
parameter, this will fail.
</p>
</div>
</div>
<div id="method-M000359" class="method-detail">
<a name="M000359"></a>
<div class="method-heading">
<a href="Base.src/M000359.html" target="Code" class="method-signature"
onclick="popupCode('Base.src/M000359.html');return false;">
<span class="method-name">mailer_name</span><span class="method-args">(value = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Override the mailer name, which defaults to an inflected version of the
mailer‘s class name. If you want to use a template in a non-standard
location, you can use this to specify that location.
</p>
</div>
</div>
<div id="method-M000360" class="method-detail">
<a name="M000360"></a>
<div class="method-heading">
<a href="Base.src/M000360.html" target="Code" class="method-signature"
onclick="popupCode('Base.src/M000360.html');return false;">
<span class="method-name">mailer_name=</span><span class="method-args">(value)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
</div>
</div>
<div id="validator-badges">
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
bc75e49382dc9b94ff02ee45f6438cf2
>
files
>
56
