delivery_job. Mailers can set this to use a custom queue name.
* deliver_later_queue_name - The queue name used by deliver_later with the default
custom delivery job. Defaults to ActionMailer::MailDeliveryJob.
* delivery_job - The job class used with deliver_later. Mailers can set this to use a
delivery_method :test. Most useful for unit and functional testing.
* deliveries - Keeps an array of all the emails sent out through the Action Mailer with
be turned off to aid in functional testing.
call .deliver on an email message or on an Action Mailer method. This is on by default but can
* perform_deliveries - Determines whether emails are actually sent from Action Mailer when you
implement for a custom delivery agent.
object e.g. MyOwnDeliveryMethodClass. See the Mail gem documentation on the interface you need to
:sendmail, :test, and :file. Or you may provide a custom delivery method
* delivery_method - Defines a delivery method. Possible values are :smtp (default),
* raise_delivery_errors - Whether or not errors should be raised if the email fails to be delivered.
tmp/mails.
* :location - The directory into which emails will be written. Defaults to the application
* file_settings - Allows you to override options for the :file delivery method.
added automatically before the message is sent.
* :arguments - The command line arguments. Defaults to %w[ -i ] with -f sender@address
* :location - The location of the sendmail executable. Defaults to /usr/sbin/sendmail.
* sendmail_settings - Allows you to override options for the :sendmail delivery method.
* :read_timeout Number of seconds to wait until timing-out a read(2) call.
* :open_timeout Number of seconds to wait while attempting to open a connection.
* :ssl/:tls Enables the SMTP connection to use SMTP/TLS (SMTPS: SMTP over direct TLS connection)
(OpenSSL::SSL::VERIFY_NONE or OpenSSL::SSL::VERIFY_PEER).
of an OpenSSL verify constant ('none' or 'peer') or directly the constant
really useful if you need to validate a self-signed and/or a wildcard certificate. You can use the name
* :openssl_verify_mode - When using TLS, you can set how OpenSSL checks the certificate. This is
to use it. Defaults to true.
* :enable_starttls_auto - Detects if STARTTLS is enabled in your SMTP server and starts
to false. Requires at least version 2.7 of the Mail gem.
* :enable_starttls - Use STARTTLS when connecting to your SMTP server and fail if unsupported. Defaults
information and a cryptographic Message Digest 5 algorithm to hash important information)
send the password Base64 encoded) or :cram_md5 (combines a Challenge/Response mechanism to exchange
This is a symbol and one of :plain (will send the password Base64 encoded), :login (will
authentication type here.
* :authentication - If your mail server requires authentication, you need to specify the
* :password - If your mail server requires authentication, set the password in this setting.
* :user_name - If your mail server requires authentication, set the username in this setting.
* :domain - If you need to specify a HELO domain, you can do it here.
* :port - On the off chance that your mail server doesn’t run on port 25, you can change it.
“localhost” setting.
* :address - Allows you to use a remote mail server. Just change it from its default
* smtp_settings - Allows detailed configuration for :smtp delivery method:
Can be set to nil for no logging. Compatible with both Ruby’s own Logger and Log4r loggers.
* logger - the logger is used for generating information on the mailing run if available.
per the above section.
* default_options - You can pass this in at a class level as well as within the class itself as
ActionMailer::Base.raise_delivery_errors = true
These options are specified on the class level, like
== Configuration options
previewing emails.
and register_preview_interceptor if they should operate on both sending and
Note that interceptors need to be registered both with register_interceptor
config.action_mailer.preview_interceptors :css_inline_styler
end
end
# inline CSS styles
def self.previewing_email(message)
class CssInlineStyler
a preview interceptor that has a previewing_email method:
Previews can also be intercepted in a similar manner as deliveries can be by registering
on a running development server instance.
An overview of all previews is accessible at http://localhost:3000/rails/mailers
config.action_mailer.preview_paths << “#{Rails.root}/lib/mailer_previews”
of test/mailers/previews:
mailer preview directories can be configured using the preview_paths option which has a default
method without the additional deliver_now / deliver_later. The location of the
Methods must return a Mail::Message object which can be generated by calling the mailer
end
end
NotifierMailer.welcome(User.first)
def welcome
class NotifierMailerPreview < ActionMailer::Preview
with database data, you’ll need to write some scenarios to load messages with fake data:
ActionMailer::Base.preview_paths. Since most emails do something interesting
You can preview your email templates visually by adding a mailer preview file to the
== Previewing emails
end
end
mail(to: recipient, subject: “Notification”)
def notify(recipient)
end
# …
rescue_from “SomeThirdPartyService::ApiError” do
end
# …
rescue_from ActiveJob::DeserializationError do
class NotifierMailer < ApplicationMailer
:
To rescue errors that occur during any part of the mailing process, use
background job, or errors from a third-party mail delivery service.
outside of rendering – for example, record deserialization errors in a
rescue blocks inside of a mailer method cannot rescue errors that occur
== Rescuing Errors
Action Mailer classes so that headers are parsed properly.
using before_action rather than after_action in your
Note that unless you have a specific reason to do so, you should prefer
inherit from ActionController::Base.
callbacks in the same manner that you would use callbacks in classes that
AbstractController::Callbacks, so you can define and configure
Action callbacks in Action Mailer are implemented using
end
end
Rails.logger.info “Sent email with message id ‘#{message.message_id}’ at #{Time.current}.”
def log_delivery<br><br>end<br>attachments.inline = File.read(‘/path/to/filename.jpg’)
def add_inline_attachment!
private
end
mail
def welcome
after_deliver :log_delivery
before_action :add_inline_attachment!
class NotifierMailer < ApplicationMailer
sent out by a certain mailer class:
For example, when you want to add default inline attachments and log delivery for all messages
and using before_deliver and after_deliver for wrapping the delivery process.
You can specify callbacks using before_action and after_action for configuring your messages,
== Callbacks
config.action_mailer.default_options = { from: “no-reply@example.org” }
the default_options= configuration in config/application.rb:
It is also possible to set these default options that will be used in all mailers through
mailer method, it will get overwritten by the mailer method.
set something in the default hash using a proc, and then set the same thing inside of your
Note that the proc/lambda is evaluated right at the start of the mail message generation, so if you
end
end
’some complex call’
def my_method
private
default ‘X-Special-Header’ => Proc.new { my_method }, to: -> { @inviter.email_address }
class NotifierMailer < ApplicationMailer
so you can define methods that evaluate as the message is being generated:
Finally, Action Mailer also supports passing Proc and Lambda objects into the default hash,
end
content_description: ‘This is a description’
default ‘Content-Transfer-Encoding’ => ‘7bit’,
class NotifierMailer < ApplicationMailer
an underscored symbol, so the following will work:
As you can pass in any header, you need to either quote the header as a string, or pass it in as
but Action Mailer translates them appropriately and sets the correct values.
parts_order and charset are not actually valid Mail::Message header fields,
* parts_order: [ "text/plain", "text/enriched", "text/html" ]
* content_type: "text/plain"
* charset: "UTF-8"
* mime_version: "1.0"
ActionMailer::Base sets the following:
You can pass in any header value that a Mail::Message accepts. Out of the box,
end
default sender: ‘system@example.com’
class NotifierMailer < ApplicationMailer
default method inside the class definition:
Action Mailer provides some intelligent defaults for your emails, these are usually specified in a
== Default Hash
in Mail::Message instance.
the delivery agents. Your class should make any needed modifications directly to the passed
called before the email is sent, allowing you to make modifications to the email before it hits
An interceptor class must implement the :delivering_email(message) method which will be
called once for every email sent after the email has been sent.
An observer class must implement the :delivered_email(message) method which will be
register classes that are called during the mail delivery life cycle.
Action Mailer provides hooks into the Mail observer and interceptor methods. These allow you to
== Observing and Intercepting Mails
<%= image_tag attachments.url, alt: ‘Our Photo’, class: ‘photo’ -%>
<h1>Please Don’t Cringe</h1>
As we are using Action View’s image_tag method, you can pass in any other options you want:
<%= image_tag attachments.url -%>
<h1>Please Don’t Cringe</h1>
url on the attachment to get the relative content id path for the image source:
make a call to image_tag passing in the attachment you want to display and then call
And then to reference the image in the view, you create a welcome.html.erb file and
end
end
mail(to: recipient, subject: “Here is what we look like”)<br>attachments.inline = File.read(‘path/to/photo.png’)
def welcome(recipient)
class NotifierMailer < ApplicationMailer
if you want to display a corporate logo or a photo.
You can also specify that a file should be displayed inline with other HTML. This is useful
== Inline Attachments
end
end
body: “<html><body>Hello there</body></html>”)
content_type: “text/html”,
subject: “New account information”,
mail(to: recipient,<br>attachments = File.read(“path/to/file.pdf”)
def welcome(recipient)
class NotifierMailer < ApplicationMailer
and custom content type like this:
You can also send attachments with HTML template, in this case you need to add body, attachments,
end
end
mail(to: recipient, subject: “New account information”, body: “”)
= File.read(‘path/to/file.pdf’)
def welcome(recipient)
class NotifierMailer < ApplicationMailer
or add an empty body parameter like this:
If you need to send attachments with no content, you need to create an empty view for it,
with the filename free_book.pdf.
and the second being a application/pdf with a Base64 encoded copy of the file.pdf book
the first part being a multipart/alternative with the text and HTML email parts inside,
template in the view directory), send a complete multipart/mixed email with two parts,
Which will (if it had both a welcome.text.erb and welcome.html.erb
end
end
mail(to: recipient, subject: “New account information”)<br>attachments = File.read(‘path/to/file.pdf’)
def welcome(recipient)
class NotifierMailer < ApplicationMailer
Sending attachment in emails is easy:
== Attachments
to multipart/alternative.
This means that you’ll have to manually add each part to the email and set the content type of the email
Implicit template rendering is not performed if any attachments or parts have been added to the email.
body. The same instance variables defined in the action are passed to all email templates.
which indicates that the email contains multiple different representations of the same email
type. The content type for the entire message is automatically set to multipart/alternative,
Each would be rendered and added as a separate part to the message, with the corresponding content
* signup_notification.yml.erb
* signup_notification.xml.builder
* signup_notification.html.erb
* signup_notification.text.erb
For example, if the following templates exist:
type. Each such detected template will be added to the message, as a separate part.
multipart templates, where each template is named after the name of the action, followed by the content
Multipart messages can also be used implicitly because Action Mailer will automatically detect and use
== Multipart Emails
All instance methods are expected to return a message object to be sent.
You never instantiate your mailer class. Rather, you just call the method you defined on the class itself.
Note that deliver_later will execute your method from the background job.
NotifierMailer.welcome(User.first).deliver_later # enqueue the email sending to Active Job
(example: outside of the request-response cycle, so the user doesn’t have to wait on it):
Action Mailer is nicely integrated with Active Job so you can generate and send emails in the background
NotifierMailer.welcome(User.first).message # => a Mail::Message object
you can call the message method on the ActionMailer::MessageDelivery object.
your method to generate the mail. If you want direct access to the delegator, or Mail::Message,
The ActionMailer::MessageDelivery class is a wrapper around a delegate that will call
mail.deliver_now # generates and sends the email now
mail = NotifierMailer.welcome(User.first) # => an ActionMailer::MessageDelivery object
NotifierMailer.welcome(User.first).deliver_now # sends the email
delivery for later:
Once a mailer action and template are defined, you can deliver your message or defer its creation and
== Sending mail
By default when config.force_ssl is true, URLs generated for hosts will use the HTTPS protocol.
default settings per-mailer.
You can also define a default_url_options method on individual mailers to override these
config.action_mailer.default_url_options = { host: “example.com” }
option as a configuration option in config/application.rb:
It is also possible to set a default host that will be used in all mailers by setting the :host
have no concept of a current URL from which to determine a relative path.
named_route_path style (which generates relative URLs), since clients reading the mail will
You should use the named_route_url style (which generates absolute URLs) and avoid using the
<%= users_url(host: “example.com”) %>
When using named routes you only need to supply the :host:
<%= url_for(host: “example.com”, controller: “welcome”, action: “greeting”) %>
When using url_for you’ll need to provide the :host, :controller, and :action:
to provide all of the details needed to generate a URL.
Action Pack, the mailer instance doesn’t have any context about the incoming request, so you’ll need
URLs can be generated in mailer views using url_for or named routes. Unlike controllers from
== Generating URLs
<%= truncate(@note.body, length: 25) %>
You got a new note from <%= message.from %>!
If you need to access the subject, from, or the recipients in the view, you can do that through message object:
<%= truncate(@note.body, length: 25) %>
You got a new note!
You can even use Action View helpers in these views. For example:
Thanks for joining our service! Please check back often.
Hi <%= @account.name %>,
Emails by default are sent in plain text, so a sample view for our model example might look like this:
corresponding view.
Variables defined in the methods of your mailer model are accessible as instance variables in their
app/views/notifier_mailer/welcome.text.erb would be used to generate the email.
name as the method in your mailer model. For example, in the mailer defined above, the template at
To define a template to be used with a mailer, create an .erb file with the same
method of the class looks for a template with its name.
Like Action Controller, each mailer class has a corresponding view directory in which each
== Mailer views
end
format.html { render “some_other_template” }
format.text
mail(to: user.email) do |format|
Or even to render a special view:
end
format.html
format.text(content_transfer_encoding: “base64”)
mail(to: user.email) do |format|
The block syntax is also useful in providing information specific to a part:
end
format.html
format.text
mail(to: user.email) do |format|
If you want to explicitly render only certain templates, pass a block:
file as well as the welcome.html.erb view file in a multipart/alternative email.
the same name as the method, so the above action would send the welcome.text.erb view
The mail method, if not passed a block, will inspect your views and send all the views with
will accept (any valid email header including optional fields).
The hash passed to the mail method allows you to specify any header that a Mail::Message
* mail - Allows you to specify email to be sent.
as headers({'X-No-Spam' => 'True', 'In-Reply-To' => '1234@message.id'})
* headers(hash) - Allows you to specify multiple headers in your email such
will add many fields of the same name. Read #headers doc for more information.
as headers['X-No-Spam'] = 'True'. Note that declaring a header multiple times
* headers[]= - Allows you to specify any header field in your email such
in the same manner as attachments[]=
* attachments.inline[]= - Allows you to add an inline attachment to your email
manner; attachments['filename.png'] = File.read('path/to/filename.png')
* attachments[]= - Allows you to add attachments to your email in an intuitive
Within the mailer method, you have access to the following methods:
end
end
bcc: [“bcc@example.com”, “Order Watcher <watcher@example.com>”])
mail(to: recipient.email_address_with_name,
@account = recipient
def welcome(recipient)
return_path: ‘system@example.com’
default from: ‘no-reply@example.com’,
class NotifierMailer < ApplicationMailer
end
layout ‘mailer’
default from: ‘from@example.com’
class ApplicationMailer < ActionMailer::Base
the mailer views, options on the mail itself such as the :from address, and attachments.
used to generate an email message. In these methods, you can set up variables to be used in
inherits from ActionMailer::Base. A mailer model defines methods
The generated model inherits from ApplicationMailer which in turn
$ bin/rails generate mailer Notifier
To use Action Mailer, you need to create a mailer model.
== Mailer Models
Action Mailer allows you to send email from your application using a mailer model and views.
= Action Mailer Base