ohmysmtp-rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a597f7e583471f790c1e7b669ad4e9b5f1327675cc176f28016eab512cb0c7dc
-  data.tar.gz: 631b23bdb932677707e24ddc4009c708843702d0ec2f44fc9b658c1beaccca2c
+  metadata.gz: d470ef101954142756a1fbfbf887b46bb526d22aab8db583b05e4b29be70a42a
+  data.tar.gz: feb8b35eae261cd5e7277bba69a1092b6ed9d02036aee20a988f8a2a81908ff2
 SHA512:
-  metadata.gz: 908d2acb45d4b64fe17b2091da1b9289dd614f7c6d4f4a61698f17c39fab396a123994932e1281720a993a6a430b73baec18eec654bcfdb639a046f6bf22c63a
-  data.tar.gz: 9cf4965645ce0f8d51320d8441516b311a5d833b8257159c1cd19d003a22a993a025056712dc02cb29b088c234ba73022ef86297766ed2e450c0e6cf13e390ad
+  metadata.gz: fa90965f77cfce6966a90c1fa6d95cf8e7b79d3d0341738c494673c4f89fb420a9d5a9a82a94dcc05ace98cece53fc694c91a1eda707c7cb490721fc0cfaaf97
+  data.tar.gz: efb761fc6fa8e6ff72f3796dd9be725a18d07667480f6d3aeadd006e9095ab118eb9437415d7c7e1da8cf94c0d14aff4b90a4b203a2447f6765e4af4553371bc

data/README.md

@@ -8,11 +8,13 @@
 
 The OhMySMTP Rails Gem is a plug in for ActionMailer to send emails via [OhMySMTP](https://ohmysmtp.com) to make sending emails from Rails apps super simple.
 
-## Usage
+> **New in 0.3.0: The ability to consume [inbound emails](https://docs.ohmysmtp.com/guide/inbound/) from OhMySMTP via ActionMailbox**
 
-Once installed and configured, continue to send emails using [ActionMailer](https://guides.rubyonrails.org/action_mailer_basics.html) like normal.
+##  Usage
 
-## Requirements
+Once installed and configured, continue to send emails using [ActionMailer](https://guides.rubyonrails.org/action_mailer_basics.html) and receive emails with [ActionMailbox](https://edgeguides.rubyonrails.org/action_mailbox_basics.html) like normal.
+
+## Other Requirements
 
 You will need an OhMySMTP account with a verified domain and organization with an active plan.
 
@@ -42,9 +44,7 @@ $ gem install ohmysmtp-rails
 
 ### Configure the Gem
 
-First you will need to retrieve your API token for your sending domain from [OhMySMTP](https://app.ohmysmtp.com). You can find it under Organization -> Domain -> API Tokens
-
-#### Rails 6
+First you will need to retrieve your API token for your sending domain from [OhMySMTP](https://app.ohmysmtp.com). You can find it under Organization -> Domain -> API Tokens.
 
 Use the encrypted secret management to save your API Token to `config/credentials.yml.enc` by running the following:
 
@@ -66,21 +66,6 @@ config.action_mailer.delivery_method = :ohmysmtp
 config.action_mailer.ohmysmtp_settings = { api_token: Rails.application.credentials.ohmysmtp_api_token }
 ```
 
-#### Rails 3-5
-
-Save your API Token to `config/secrets.yml` using a text editor:
-
-```yaml
-ohmysmtp_api_token: "TOKEN_GOES_HERE"
-```
-
-Set OhMySMTP as your mail delivery method in `config/application.rb`:
-
-```ruby
-config.action_mailer.delivery_method = :ohmysmtp
-config.action_mailer.ohmysmtp_settings = { :api_token => Rails.application.secrets.ohmysmtp_api_token }
-```
-
 ## Tagging
 
 You can tag messages and filter them later in the OhMySMTP UI. To do this, pass the tags as a header by adding a tag variable to your `mail` method call.
@@ -108,8 +93,46 @@ Note that this should always be a string, even if using an array of multiple tag
 
 ## List-Unsubscribe
 
-To add a List-Unsubscribe header: ``
+To add a List-Unsubscribe header, pass a `list_unsubscribe` string to the `mail` function:
+
+```ruby
+class TestMailer < ApplicationMailer
+  default from: 'notifications@example.com',
+          to: 'fake@sdfasdfsdaf.com'
+
+  def list_unsub_header
+    mail(
+      list_unsubscribe: 'https://listunsublink.com'
+    )
+  end
+end
+```
+
+## ActionMailbox (for receiving inbound emails)
+
+As of v0.3.0, this Gem supports handling Inbound Emails (see https://docs.ohmysmtp.com/guide/inbound/ for more details) via ActionMailbox. To set this up:
+
+1. Tell Action Mailbox to accept emails from OhMySMTP in `config/environments/production.rb`
+
+```ruby
+config.action_mailbox.ingress = :ohmysmtp
+```
+
+2. Generate a strong password that Action Mailbox can use to authenticate requests to the OhMySMTP ingress.
+Use `bin/rails credentials:edit` to add the password to your application's encrypted credentials under `action_mailbox.ingress_password`, where Action Mailbox will automatically find it:
+
+```yaml
+action_mailbox:
+  ingress_password: ...
+```
+
+Alternatively, provide the password in the `RAILS_INBOUND_EMAIL_PASSWORD` environment variable.
+
+3. Configure OhMySMTP to forward inbound emails to `/rails/action_mailbox/ohmysmtp/inbound_emails` with the username `actionmailbox` and the password you previously generated. If your application lived at `https://example.com` you would configure your OhMySMTP inbound endpoint URL with the following fully-qualified URL:
+
+`https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/ohmysmtp/inbound_emails`
 
+That's it! Emails should start flowing into your app just like magic.
 ## Support
 
 For support please check the [OhMySMTP Documentation](https://docs.ohmysmtp.com)  or contact us at support@ohmysmtp.com

data/Rakefile

@@ -8,7 +8,7 @@ require 'rdoc/task'
 
 RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'OhMySMTP::Rails'
+  rdoc.title    = 'Ohmysmtp::Rails'
   rdoc.options << '--line-numbers'
   rdoc.rdoc_files.include('README.md')
   rdoc.rdoc_files.include('lib/**/*.rb')

data/app/controllers/action_mailbox/ingresses/ohmysmtp/inbound_emails_controller.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  module Ingresses
+    module Ohmysmtp
+      # Ingests inbound emails from OhMySMTP. Uses the a +raw+ parameter containing the full RFC 822 message.
+      #
+      # Authenticates requests using HTTP basic access authentication. The username is always +actionmailbox+, and the
+      # password is read from the application's encrypted credentials or an environment variable. See the Usage section.
+      #
+      # Returns:
+      #
+      # - <tt>204 No Content</tt> if an inbound email is successfully recorded and enqueued for routing
+      # - <tt>401 Unauthorized</tt> if the request's signature could not be validated
+      # - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails from OhMySMTP
+      # - <tt>422 Unprocessable Entity</tt> if the request is missing the required +RawEmail+ parameter
+      # - <tt>500 Server Error</tt> if the ingress password is not configured, or if one of the Active Record database,
+      #   the Active Storage service, or the Active Job backend is misconfigured or unavailable
+      #
+      # == Usage
+      #
+      # 1. Tell Action Mailbox to accept emails from OhMySMTP:
+      #
+      #        # config/environments/production.rb
+      #        config.action_mailbox.ingress = :ohmysmtp
+      #
+      # 2. Generate a strong password that Action Mailbox can use to authenticate requests to the OhMySMTP ingress.
+      #
+      #    Use <tt>bin/rails credentials:edit</tt> to add the password to your application's encrypted credentials under
+      #    +action_mailbox.ingress_password+, where Action Mailbox will automatically find it:
+      #
+      #        action_mailbox:
+      #          ingress_password: ...
+      #
+      #    Alternatively, provide the password in the +RAILS_INBOUND_EMAIL_PASSWORD+ environment variable.
+      #
+      # 3. {Configure OhMySMTP}[https://docs.ohmysmtp.com/guide/inbound] to forward inbound emails
+      #    to +/rails/action_mailbox/ohmysmtp/inbound_emails+ with the username +actionmailbox+ and the password you
+      #    previously generated. If your application lived at <tt>https://example.com</tt>, you would configure your
+      #    OhMySMTP inbound endpoint URL with the following fully-qualified URL:
+      #
+      #        https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/ohmysmtp/inbound_emails
+      #
+      class InboundEmailsController < ActionMailbox::BaseController
+        before_action :authenticate_by_password
+
+        def create
+          ActionMailbox::InboundEmail.create_and_extract_message_id! params.require('raw')
+        rescue ActionController::ParameterMissing => e
+          logger.error e.message
+
+          head :unprocessable_entity
+        end
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,4 @@
+Rails.application.routes.draw do
+  post 'rails/action_mailbox/ohmysmtp/inbound_emails', to: 'action_mailbox/ingresses/ohmysmtp/inbound_emails#create',
+                                                       as: 'rails_ohmysmtp_inbound_emails'
+end

data/lib/ohmysmtp-rails/engine.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Ohmysmtp
+  # Provides the delivery method & sets up action mailbox
+  class Engine < ::Rails::Engine
+    initializer 'ohmysmtp.add_delivery_method', before: 'action_mailer.set_configs' do
+      ActionMailer::Base.add_delivery_method(:ohmysmtp, Ohmysmtp::DeliveryMethod)
+    end
+
+    config.action_mailbox.ohmysmtp = ActiveSupport::OrderedOptions.new
+  end
+end

data/lib/ohmysmtp-rails/version.rb

@@ -1,5 +1,5 @@
-module OhMySMTP
+module Ohmysmtp
   module Rails
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/ohmysmtp-rails.rb

@@ -1,11 +1,12 @@
 require 'action_mailer'
+require 'action_mailbox/engine'
 require 'httparty'
 require 'uri'
 require 'json'
 require 'ohmysmtp-rails/version'
-require 'ohmysmtp-rails/railtie' if defined? Rails
+require 'ohmysmtp-rails/engine' if defined? Rails
 
-module OhMySMTP
+module Ohmysmtp
   # OhMySMTP ActionMailer delivery method
   class DeliveryMethod
     attr_accessor :settings
@@ -35,7 +36,7 @@ module OhMySMTP
           tags: mail.header['tags'].to_s
         }.delete_if { |_key, value| value.blank? }.to_json,
         headers: {
-          'User-Agent' => "OhMySMTP Rails Gem v#{OhMySMTP::Rails::VERSION}",
+          'User-Agent' => "OhMySMTP Rails Gem v#{Ohmysmtp::Rails::VERSION}",
           'Accept' => 'application/json',
           'Content-Type' => 'application/json',
           'Ohmysmtp-Server-Token' => settings[:api_token]
@@ -78,4 +79,10 @@ module OhMySMTP
       end
     end
   end
+
+  class Error < StandardError; end
+
+  def self.root
+    Pathname.new(File.expand_path(File.join(__dir__, '..')))
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ohmysmtp-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - OhMySMTP
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-02 00:00:00.000000000 Z
+date: 2021-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionmailer
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 6.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 6.0.0
 - !ruby/object:Gem::Dependency
   name: httparty
   requirement: !ruby/object:Gem::Requirement
@@ -77,8 +77,10 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/controllers/action_mailbox/ingresses/ohmysmtp/inbound_emails_controller.rb
+- config/routes.rb
 - lib/ohmysmtp-rails.rb
-- lib/ohmysmtp-rails/railtie.rb
+- lib/ohmysmtp-rails/engine.rb
 - lib/ohmysmtp-rails/version.rb
 homepage: https://ohmysmtp.com
 licenses:

data/lib/ohmysmtp-rails/railtie.rb

@@ -1,7 +0,0 @@
-module OhMySMTP
-  class Railtie < ::Rails::Railtie
-    initializer 'ohmysmtp.add_delivery_method', before: 'action_mailer.set_configs' do
-      ActionMailer::Base.add_delivery_method(:ohmysmtp, OhMySMTP::DeliveryMethod)
-    end
-  end
-end