diff options
Diffstat (limited to 'lib/action_mailbox/base.rb')
-rw-r--r-- | lib/action_mailbox/base.rb | 54 |
1 files changed, 54 insertions, 0 deletions
diff --git a/lib/action_mailbox/base.rb b/lib/action_mailbox/base.rb index 55914401e1..0ae83bf691 100644 --- a/lib/action_mailbox/base.rb +++ b/lib/action_mailbox/base.rb @@ -3,6 +3,60 @@ require "active_support/rescuable" require "action_mailbox/callbacks" require "action_mailbox/routing" +# The base class for all application mailboxes. Not intended to be inherited from directly. Inherit from +# `ApplicationMailbox` instead, as that's where the app-specific routing is configured. This routing +# is specified in the following ways: +# +# class ApplicationMailbox < ActionMailbox::Base +# # Any of the recipients of the mail (whether to, cc, bcc) are matched against the regexp. +# route /^replies@/i => :replies +# +# # Any of the recipients of the mail (whether to, cc, bcc) needs to be an exact match for the string. +# route "help@example.com" => :help +# +# # Any callable (proc, lambda, etc) object is passed the inbound_email record and is a match if true. +# route ->(inbound_email) { inbound_email.mail.to.size > 2 } => :multiple_recipients +# +# # Any object responding to #match? is called with the inbound_email record as an argument. Match if true. +# route CustomAddress.new => :custom +# +# # Any inbound_email that has not been already matched will be sent to the BackstopMailbox. +# route :all => :backstop +# end +# +# Application mailboxes need to overwrite the `#process` method, which is invoked by the framework after +# callbacks have been run. The callbacks available are: `before_processing`, `after_processing`, and +# `around_processing`. The primary use case is ensure certain preconditions to processing are fulfilled +# using `before_processing` callbacks. +# +# If a precondition fails to be met, you can halt the processing using the `#bounced!` method, +# which will silently prevent any further processing, but not actually send out any bounce notice. You +# can also pair this behavior with the invocation of an Action Mailer class responsible for sending out +# an actual bounce email. This is done using the `#bounce_with` method, which takes the mail object returned +# by an Action Mailer method, like so: +# +# class ForwardsMailbox < ApplicationMailbox +# before_processing :ensure_sender_is_a_user +# +# private +# def ensure_sender_is_a_user +# unless User.exist?(email_address: mail.from) +# bounce_with UserRequiredMailer.missing(inbound_email) +# end +# end +# end +# +# During the processing of the inbound email, the status will be tracked. Before processing begins, +# the email will normally have the `pending` status. Once processing begins, just before callbacks +# and the `#process` method is called, the status is changed to `processing`. If processing is allowed to +# complete, the status is changed to `delivered`. If a bounce is triggered, then `bounced`. If an unhandled +# exception is bubbled up, then `failed`. +# +# Exceptions can be handled at the class level using the familiar `Rescuable` approach: +# +# class ForwardsMailbox < ApplicationMailbox +# rescue_from(ApplicationSpecificVerificationError) { bounced! } +# end class ActionMailbox::Base include ActiveSupport::Rescuable include ActionMailbox::Callbacks, ActionMailbox::Routing |