Deprecate ActionMailer::Base.receive in favor of Action Mailbox

Author: georgeclaghorn

actionmailer/CHANGELOG.md

@@ -1,3 +1,7 @@
+*   Deprecate `ActionMailer::Base.receive` in favor of [Action Mailbox](https://github.com/rails/rails/tree/master/actionmailbox).
+
+    *George Claghorn*
+
 *   Add `MailDeliveryJob` for delivering both regular and parameterized mail. Deprecate using `DeliveryJob` and `Parameterized::DeliveryJob`.
 
     *Gannon McGibbon*

actionmailer/README.rdoc

@@ -93,42 +93,6 @@ Example:
     .....
   end
 
-== Receiving emails
-
-To receive emails, you need to implement a public instance method called
-+receive+ that takes an email object as its single parameter. The Action Mailer
-framework has a corresponding class method, which is also called +receive+, that
-accepts a raw, unprocessed email as a string, which it then turns into the email
-object and calls the receive instance method.
-
-Example:
-
-  class Mailman < ActionMailer::Base
-    def receive(email)
-      page = Page.find_by(address: email.to.first)
-      page.emails.create(
-        subject: email.subject, body: email.body
-      )
-
-      if email.has_attachments?
-        email.attachments.each do |attachment|
-          page.attachments.create({
-            file: attachment, description: email.subject
-          })
-        end
-      end
-    end
-  end
-
-This Mailman can be the target for Postfix or other MTAs. In Rails, you would use
-the runner in the trivial case like this:
-
-  rails runner 'Mailman.receive(STDIN.read)'
-
-However, invoking Rails in the runner for each mail to be received is very
-resource intensive. A single instance of Rails should be run within a daemon, if
-it is going to process more than just a limited amount of email.
-
 == Configuration
 
 The Base class has the full list of configuration options. Here's an example:

actionmailer/actionmailer.gemspec

@@ -6,8 +6,8 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.name        = "actionmailer"
   s.version     = version
-  s.summary     = "Email composition, delivery, and receiving framework (part of Rails)."
-  s.description = "Email on Rails. Compose, deliver, receive, and test emails using the familiar controller/view pattern. First-class support for multipart email and attachments."
+  s.summary     = "Email composition and delivery framework (part of Rails)."
+  s.description = "Email on Rails. Compose, deliver, and test emails using the familiar controller/view pattern. First-class support for multipart email and attachments."
 
   s.required_ruby_version = ">= 2.5.0"
 

actionmailer/lib/action_mailer/base.rb

@@ -565,6 +565,11 @@ def default(value = nil)
       #     end
       #   end
       def receive(raw_mail)
+        ActiveSupport::Deprecation.warn(<<~MESSAGE.squish)
+          ActionMailer::Base.receive is deprecated and will be removed in Rails 6.1.
+          Use Action Mailbox to process inbound email.
+        MESSAGE
+
         ActiveSupport::Notifications.instrument("receive.action_mailer") do |payload|
           mail = Mail.new(raw_mail)
           set_payload_for_mail(payload, mail)

actionmailer/test/log_subscriber_test.rb

@@ -3,10 +3,11 @@
 require "abstract_unit"
 require "mailers/base_mailer"
 require "active_support/log_subscriber/test_helper"
+require "active_support/testing/stream"
 require "action_mailer/log_subscriber"
 
 class AMLogSubscriberTest < ActionMailer::TestCase
-  include ActiveSupport::LogSubscriber::TestHelper
+  include ActiveSupport::LogSubscriber::TestHelper, ActiveSupport::Testing::Stream
 
   def setup
     super
@@ -53,7 +54,7 @@ def test_deliver_message_when_perform_deliveries_is_false
 
   def test_receive_is_notified
     fixture = File.read(File.expand_path("fixtures/raw_email", __dir__))
-    TestMailer.receive(fixture)
+    silence_stream(STDERR) { TestMailer.receive(fixture) }
     wait
     assert_equal(1, @logger.logged(:info).size)
     assert_match(/Received mail/, @logger.logged(:info).first)