1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
rails--rails/actionmailer
Edouard CHIN 859f3bf024 Deprecate custom Action Mailer delivery job:
- Action Mailer delivery job should modify their `perform` method
  signature in order to receive the new payload that Action Mailer
  sends.

  Before:

  ```ruby
    def perform(mailer, mail_method, delivery_method, *args)
    end
  ```

  After:

  ```ruby
    def perform(mailer, mail_method, delivery_method, args:)
    end
  ```

  This new behaviour was introduced couple years ago in a attempt to
  get rid of the necessity to have a different job for paramterized
  mailers. A deprecation was introduced for custom jobs inheriting
  from `ActionMailer::DeliveryJob` but for jobs that didn't it went
  unnoticed.
  The deprecated behaviour was supposed to be removed in Rails 6.1
  but we couldn't and it got reverted https://github.com/rails/rails/pull/39257
2020-08-26 17:48:47 +02:00
..
bin
lib Deprecate custom Action Mailer delivery job: 2020-08-26 17:48:47 +02:00
test Deprecate custom Action Mailer delivery job: 2020-08-26 17:48:47 +02:00
actionmailer.gemspec Update the Rails mailing list URLs to new discuss discourse URL [ci skip] 2020-04-02 22:00:28 +05:30
CHANGELOG.md Revert "Remove deprecated ActionMailer::DeliveryJob and ActionMailer::Parameterized::DeliveryJob" 2020-05-12 15:20:07 -04:00
MIT-LICENSE Bump license years from 2019 to 2020 [ci skip] 2020-01-01 15:10:31 +05:30
Rakefile
README.rdoc Update the Rails mailing list URLs to new discuss discourse URL [ci skip] 2020-04-02 22:00:28 +05:30

= Action Mailer -- Easy email delivery and testing

Action Mailer is a framework for designing email service layers. These layers
are used to consolidate code for sending out forgotten passwords, welcome
wishes on signup, invoices for billing, and any other use case that requires
a written notification to either a person or another system.

Action Mailer is in essence a wrapper around Action Controller and the
Mail gem.  It provides a way to make emails using templates in the same
way that Action Controller renders views using templates.

Additionally, an Action Mailer class can be used to process incoming email,
such as allowing a blog to accept new posts from an email (which could even
have been sent from a phone).

You can read more about Action Mailer in the {Action Mailer Basics}[https://edgeguides.rubyonrails.org/action_mailer_basics.html] guide.

== Sending emails

The framework works by initializing any instance variables you want to be
available in the email template, followed by a call to +mail+ to deliver
the email.

This can be as simple as:

  class Notifier < ActionMailer::Base
    default from: 'system@loudthinking.com'

    def welcome(recipient)
      @recipient = recipient
      mail(to: recipient,
           subject: "[Signed up] Welcome #{recipient}")
    end
  end

The body of the email is created by using an Action View template (regular
ERB) that has the instance variables that are declared in the mailer action.

So the corresponding body template for the method above could look like this:

  Hello there,

  Mr. <%= @recipient %>

  Thank you for signing up!

If the recipient was given as "david@loudthinking.com", the email
generated would look like this:

  Date: Mon, 25 Jan 2010 22:48:09 +1100
  From: system@loudthinking.com
  To: david@loudthinking.com
  Message-ID: <4b5d84f9dd6a5_7380800b81ac29578@void.loudthinking.com.mail>
  Subject: [Signed up] Welcome david@loudthinking.com
  Mime-Version: 1.0
  Content-Type: text/plain;
  	charset="US-ASCII";
  Content-Transfer-Encoding: 7bit

  Hello there,

  Mr. david@loudthinking.com

  Thank you for signing up!

In order to send mails, you simply call the method and then call +deliver_now+ on the return value.

Calling the method returns a Mail Message object:

  message = Notifier.welcome("david@loudthinking.com")   # => Returns a Mail::Message object
  message.deliver_now                                    # => delivers the email

Or you can just chain the methods together like:

  Notifier.welcome("david@loudthinking.com").deliver_now # Creates the email and sends it immediately

== Setting defaults

It is possible to set default values that will be used in every method in your
Action Mailer class. To implement this functionality, you just call the public
class method +default+ which you get for free from <tt>ActionMailer::Base</tt>.
This method accepts a Hash as the parameter. You can use any of the headers,
email messages have, like +:from+ as the key. You can also pass in a string as
the key, like "Content-Type", but Action Mailer does this out of the box for you,
so you won't need to worry about that. Finally, it is also possible to pass in a
Proc that will get evaluated when it is needed.

Note that every value you set with this method will get overwritten if you use the
same key in your mailer method.

Example:

  class AuthenticationMailer < ActionMailer::Base
    default from: "awesome@application.com", subject: Proc.new { "E-mail was generated at #{Time.now}" }
    .....
  end

== Configuration

The Base class has the full list of configuration options. Here's an example:

  ActionMailer::Base.smtp_settings = {
    address:        'smtp.yourserver.com', # default: localhost
    port:           '25',                  # default: 25
    user_name:      'user',
    password:       'pass',
    authentication: :plain                 # :plain, :login or :cram_md5
  }


== Download and installation

The latest version of Action Mailer can be installed with RubyGems:

  $ gem install actionmailer

Source code can be downloaded as part of the Rails project on GitHub:

* https://github.com/rails/rails/tree/master/actionmailer


== License

Action Mailer is released under the MIT license:

* https://opensource.org/licenses/MIT


== Support

API documentation is at

* https://api.rubyonrails.org

Bug reports for the Ruby on Rails project can be filed here:

* https://github.com/rails/rails/issues

Feature requests should be discussed on the rails-core mailing list here:

* https://discuss.rubyonrails.org/c/rubyonrails-core