Basic docs for most classes

1 files changed, 21 insertions, 0 deletions

diff --git a/app/models/action_mailbox/inbound_email.rb b/app/models/action_mailbox/inbound_email.rb
index ea564a254e..156e2d4dbc 100644
--- a/app/models/action_mailbox/inbound_email.rb
+++ b/app/models/action_mailbox/inbound_email.rb
@@ -1,5 +1,26 @@
 require "mail"
 
+# The `InboundEmail` is an Active Record that keeps a reference to the raw email stored in Active Storage
+# and tracks the status of processing. By default, incoming emails will go through the following lifecycle:
+#
+# * Pending: Just received by one of the ingress controllers and scheduled for routing.
+# * Processing: During active processing, while a specific mailbox is running its #process method.
+# * Delivered: Successfully processed by the specific mailbox.
+# * Failed: An exception was raised during the specific mailbox's execution of the `#process` method.
+# * Bounced: Rejected processing by the specific mailbox and bounced to sender.
+#
+# Once the `InboundEmail` has reached the status of being either `delivered`, `failed`, or `bounced`, 
+# it'll count as having been `#processed?`. Once processed, the `InboundEmail` will be scheduled for 
+# automatic incineration at a later point.
+#
+# When working with an `InboundEmail`, you'll usually interact with the parsed version of the source,
+# which is available as a `Mail` object from `#mail`. But you can also access the raw source directly
+# using the `#source` method.
+#
+# Examples:
+#
+#   inbound_email.mail.from # => 'david@loudthinking.com'
+#   inbound_email.source # Returns the full rfc822 source of the email as text
 class ActionMailbox::InboundEmail < ActiveRecord::Base
   self.table_name = "action_mailbox_inbound_emails"