5 files changed, 40 insertions, 13 deletions
diff --git a/guides/source/4_2_release_notes.md b/guides/source/4_2_release_notes.md
index aa056f5844..864026e9f2 100644
--- a/guides/source/4_2_release_notes.md
+++ b/guides/source/4_2_release_notes.md
@@ -311,6 +311,9 @@ Please refer to the [Changelog][action-mailer] for detailed changes.
 *   Deprecated `*_path` helpers in mailers. Always use `*_url` helpers instead.
     ([Pull Request](https://github.com/rails/rails/pull/15840))
 
+*   Deprecated `deliver` / `deliver!` in favour of `deliver_now` / `deliver_now!`.
+    ([Pull Request](https://github.com/rails/rails/pull/16582))
+
 ### Notable changes
 
 *   Introduced `deliver_later` which enqueues a job on the application's queue
diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md
index 9ad9319255..6b6ce145e4 100644
--- a/guides/source/action_mailer_basics.md
+++ b/guides/source/action_mailer_basics.md
@@ -159,7 +159,10 @@ $ bin/rake db:migrate
 Now that we have a user model to play with, we will just edit the
 `app/controllers/users_controller.rb` make it instruct the `UserMailer` to deliver
 an email to the newly created user by editing the create action and inserting a
-call to `UserMailer.welcome_email` right after the user is successfully saved:
+call to `UserMailer.welcome_email` right after the user is successfully saved.
+
+Action Mailer is nicely integrated with Active Job so you can send emails outside
+of the request-response cycle, so the user doesn't have to wait on it:
 
 ```ruby
 class UsersController < ApplicationController
@@ -171,7 +174,7 @@ class UsersController < ApplicationController
     respond_to do |format|
       if @user.save
         # Tell the UserMailer to send a welcome email after save
-        UserMailer.welcome_email(@user).deliver
+        UserMailer.welcome_email(@user).deliver_later
 
         format.html { redirect_to(@user, notice: 'User was successfully created.') }
         format.json { render json: @user, status: :created, location: @user }
@@ -184,8 +187,29 @@ class UsersController < ApplicationController
 end
 ```
 
-The method `welcome_email` returns a `Mail::Message` object which can then just
-be told `deliver` to send itself out.
+NOTE: By default Active Job is configured to execute the job `:inline`. So you can
+use `deliver_later` now to send the emails and when you decide to start sending the
+email from a background job you'll just have to setup Active Job to use a queueing
+backend (Sidekiq, Resque, etc).
+
+If you want to send the emails right away (from a cronjob for example) just
+call `deliver_now`:
+
+```ruby
+class SendWeeklySummary
+  def run
+    User.find_each do |user|
+      UserMailer.weekly_summary(user).deliver_now
+    end
+  end
+end
+```
+
+The method `welcome_email` returns a `ActionMailer::MessageDelivery` object which
+can then just be told `deliver_now` or `deliver_later` to send itself out. The
+`ActionMailer::MessageDelivery` object is just a wrapper around a `Mail::Message`. If
+you want to inspect, alter or do anything else with the `Mail::Message` object you can
+access it with the `message` method on the `ActionMailer::MessageDelivery` object.
 
 ### Auto encoding header values
 
diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md
index ae5d21d546..0df4320e36 100644
--- a/guides/source/active_job_basics.md
+++ b/guides/source/active_job_basics.md
@@ -196,10 +196,10 @@ of the request-response cycle, so the user doesn't have to wait on it. Active Jo
 is integrated with Action Mailer so you can easily send emails async:
 
 ```ruby
-# Instead of the classic
-UserMailer.welcome(@user).deliver
+# If you want to send the email now use #deliver_now
+UserMailer.welcome(@user).deliver_now
 
-# use #deliver later to send the email async
+# If you want to send the email through ActiveJob use #deliver_later
 UserMailer.welcome(@user).deliver_later
 ```
 
diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md
index f9b46286c1..cb243c95f5 100644
--- a/guides/source/active_record_querying.md
+++ b/guides/source/active_record_querying.md
@@ -276,7 +276,7 @@ This may appear straightforward:
 ```ruby
 # This is very inefficient when the users table has thousands of rows.
 User.all.each do |user|
-  NewsMailer.weekly(user).deliver
+  NewsMailer.weekly(user).deliver_now
 end
 ```
 
@@ -292,7 +292,7 @@ The `find_each` method retrieves a batch of records and then yields _each_ recor
 
 ```ruby
 User.find_each do |user|
-  NewsMailer.weekly(user).deliver
+  NewsMailer.weekly(user).deliver_now
 end
 ```
 
@@ -300,7 +300,7 @@ To add conditions to a `find_each` operation you can chain other Active Record m
 
 ```ruby
 User.where(weekly_subscriber: true).find_each do |user|
-  NewsMailer.weekly(user).deliver
+  NewsMailer.weekly(user).deliver_now
 end
 ```
 
@@ -316,7 +316,7 @@ The `:batch_size` option allows you to specify the number of records to be retri
 
 ```ruby
 User.find_each(batch_size: 5000) do |user|
-  NewsMailer.weekly(user).deliver
+  NewsMailer.weekly(user).deliver_now
 end
 ```
 
@@ -328,7 +328,7 @@ For example, to send newsletters only to users with the primary key starting fro
 
 ```ruby
 User.find_each(start: 2000, batch_size: 5000) do |user|
-  NewsMailer.weekly(user).deliver
+  NewsMailer.weekly(user).deliver_now
 end
 ```
 
diff --git a/guides/source/testing.md b/guides/source/testing.md
index 2ecd560a87..d91f13699a 100644
--- a/guides/source/testing.md
+++ b/guides/source/testing.md
@@ -949,7 +949,7 @@ class UserMailerTest < ActionMailer::TestCase
   test "invite" do
     # Send the email, then test that it got queued
     email = UserMailer.create_invite('me@example.com',
-                                     'friend@example.com', Time.now).deliver
+                                     'friend@example.com', Time.now).deliver_now
     assert_not ActionMailer::Base.deliveries.empty?
 
     # Test the body of the sent email contains what we expect it to