class ActionMailer::MessageDelivery

The ActionMailer::MessageDelivery class is used by ActionMailer::Base when creating a new mailer. MessageDelivery is a wrapper (Delegator subclass) around a lazy created Mail::Message. You can get direct access to the Mail::Message, deliver the email or schedule the email to be sent through Active Job.

Notifier.welcome(User.first)               # an ActionMailer::MessageDelivery object
Notifier.welcome(User.first).deliver_now   # sends the email
Notifier.welcome(User.first).deliver_later # enqueue email delivery as a job through Active Job
Notifier.welcome(User.first).message       # a Mail::Message object

Public Instance Methods

deliver_later(options = {}) click to toggle source

Enqueues the email to be delivered through Active Job. When the job runs it will send the email using deliver_now.

Notifier.welcome(User.first).deliver_later
Notifier.welcome(User.first).deliver_later(wait: 1.hour)
Notifier.welcome(User.first).deliver_later(wait_until: 10.hours.from_now)
Notifier.welcome(User.first).deliver_later(priority: 10)

Options:

  • :wait - Enqueue the email to be delivered with a delay.

  • :wait_until - Enqueue the email to be delivered at (after) a specific date / time.

  • :queue - Enqueue the email on the specified queue.

  • :priority - Enqueues the email with the specified priority

By default, the email will be enqueued using ActionMailer::DeliveryJob. Each ActionMailer::Base class can specify the job to use by setting the class variable delivery_job.

class AccountRegistrationMailer < ApplicationMailer
  self.delivery_job = RegistrationDeliveryJob
end
# File lib/action_mailer/message_delivery.rb, line 98
def deliver_later(options = {})
  enqueue_delivery :deliver_now, options
end
deliver_later!(options = {}) click to toggle source

Enqueues the email to be delivered through Active Job. When the job runs it will send the email using deliver_now!. That means that the message will be sent bypassing checking perform_deliveries and raise_delivery_errors, so use with caution.

Notifier.welcome(User.first).deliver_later!
Notifier.welcome(User.first).deliver_later!(wait: 1.hour)
Notifier.welcome(User.first).deliver_later!(wait_until: 10.hours.from_now)
Notifier.welcome(User.first).deliver_later!(priority: 10)

Options:

  • :wait - Enqueue the email to be delivered with a delay

  • :wait_until - Enqueue the email to be delivered at (after) a specific date / time

  • :queue - Enqueue the email on the specified queue

  • :priority - Enqueues the email with the specified priority

By default, the email will be enqueued using ActionMailer::DeliveryJob. Each ActionMailer::Base class can specify the job to use by setting the class variable delivery_job.

class AccountRegistrationMailer < ApplicationMailer
  self.delivery_job = RegistrationDeliveryJob
end
# File lib/action_mailer/message_delivery.rb, line 72
def deliver_later!(options = {})
  enqueue_delivery :deliver_now!, options
end
deliver_now() click to toggle source

Delivers an email:

Notifier.welcome(User.first).deliver_now
# File lib/action_mailer/message_delivery.rb, line 117
def deliver_now
  processed_mailer.handle_exceptions do
    message.deliver
  end
end
deliver_now!() click to toggle source

Delivers an email without checking perform_deliveries and raise_delivery_errors, so use with caution.

Notifier.welcome(User.first).deliver_now!
# File lib/action_mailer/message_delivery.rb, line 107
def deliver_now!
  processed_mailer.handle_exceptions do
    message.deliver!
  end
end
message() click to toggle source

Returns the resulting Mail::Message

# File lib/action_mailer/message_delivery.rb, line 39
def message
  __getobj__
end
processed?() click to toggle source

Was the delegate loaded, causing the mailer action to be processed?

# File lib/action_mailer/message_delivery.rb, line 44
def processed?
  @processed_mailer || @mail_message
end

Private Instance Methods

enqueue_delivery(delivery_method, options = {}) click to toggle source
# File lib/action_mailer/message_delivery.rb, line 132
      def enqueue_delivery(delivery_method, options = {})
        if processed?
          ::Kernel.raise "You've accessed the message before asking to " \
            "deliver it later, so you may have made local changes that would " \
            "be silently lost if we enqueued a job to deliver it. Why? Only " \
            "the mailer method *arguments* are passed with the delivery job! " \
            "Do not access the message in any way if you mean to deliver it " \
            "later. Workarounds: 1. don't touch the message before calling " \
            "#deliver_later, 2. only touch the message *within your mailer " \
            "method*, or 3. use a custom Active Job instead of #deliver_later."
        else
          job = @mailer_class.delivery_job

          if use_new_args?(job)
            job.set(options).perform_later(
              @mailer_class.name, @action.to_s, delivery_method.to_s, args: @args)
          elsif job <= DeliveryJob
            job.set(options).perform_later(
              @mailer_class.name, @action.to_s, delivery_method.to_s, *@args)
          else
            ActiveSupport::Deprecation.warn(<<~EOM)
              In Rails 7.0, Action Mailer will pass the mail arguments inside the `:args` keyword argument.
              The `perform` method of the #{job} needs to change and forward the mail arguments
              from the `args` keyword argument.

              The `perform` method should now look like:

              `def perform(mailer, mail_method, delivery, args:)`
            EOM

            job.set(options).perform_later(
              @mailer_class.name, @action.to_s, delivery_method.to_s, *@args)
          end
        end
      end
processed_mailer() click to toggle source

Returns the processed Mailer instance. We keep this instance on hand so we can delegate exception handling to it.

# File lib/action_mailer/message_delivery.rb, line 126
def processed_mailer
  @processed_mailer ||= @mailer_class.new.tap do |mailer|
    mailer.process @action, *@args
  end
end
use_new_args?(job) click to toggle source
# File lib/action_mailer/message_delivery.rb, line 168
def use_new_args?(job)
  parameters = job.public_instance_method(:perform).parameters

  parameters.find do |key, name|
    return true if key == :keyreq && name == :args

    key == :keyrest and name != :**
  end
end