mailpace-rails 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7d4f376af21674d306c2b4edffecef9a2a74c7476270a385756ba5a3804b17d
+  data.tar.gz: 58112506f977914969364d5e764cc32d9a0099083698f1db23c913e25e725175
+SHA512:
+  metadata.gz: 0d5ae0e7b05188ca5b01539bab467d92bd018a4ebfb3634f384de567ed4e66f252d1a3fec466759717832e0a1fd833fd0f9556f9f82890c5e29ccfb395f86d2c
+  data.tar.gz: 83bf637bbde3f65891960dc4f5f554104080a94aaa9f40d604234ad9a60312ead5fa8c93351d44c6218183baf8dcfafa832321a4f051fa23389d16fcf486fe33

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2020 OhMySMTP
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# MailPace::Rails
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Gem Version](https://badge.fury.io/rb/mailpace-rails.svg)](https://badge.fury.io/rb/mailpace-rails)
+[![MailPace Rails](https://circleci.com/gh/mailpace/mailpace-rails.svg?style=svg)](https://app.circleci.com/pipelines/github/mailpace/mailpace-rails)
+
+[MailPace](https://mailpace.com) lets you send transactional emails from your app over an easy to use API.
+
+The MailPace Rails Gem is a plug in for ActionMailer to send emails via [MailPace](https://mailpace.com) to make sending emails from Rails apps super simple.
+
+> **New in 0.3.0: The ability to consume [inbound emails](https://docs.mailpace.com/guide/inbound/) from MailPace via ActionMailbox**
+
+##  Usage
+
+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 MailPace account with a verified domain and organization with an active plan.
+
+## Installation
+
+### Account Setup 
+
+Set up an account at [MailPace](https://app.mailpace.com/users/sign_up) and complete the Onboarding steps
+
+### Gem Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mailpace-rails'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install mailpace-rails
+```
+
+### Configure the Gem
+
+First you will need to retrieve your API token for your sending domain from [MailPace](https://app.mailpace.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:
+
+```bash
+rails secret
+rails credentials:edit
+```
+
+Then add your token:
+
+```yaml
+mailpace_api_token: "TOKEN_GOES_HERE"
+```
+
+Set MailPace as your mail delivery method in `config/application.rb`:
+
+```ruby
+config.action_mailer.delivery_method = :mailpace
+config.action_mailer.mailpace_settings = { api_token: Rails.application.credentials.mailpace_api_token }
+```
+
+## Tagging
+
+You can tag messages and filter them later in the MailPace UI. To do this, pass the tags as a header by adding a tag variable to your `mail` method call.
+
+```ruby
+class TestMailer < ApplicationMailer
+  default from: 'notifications@example.com',
+          to: 'fake@sdfasdfsdaf.com'
+
+  def single_tag
+    mail(
+      tags: 'test tag' # One tag
+    )
+  end
+
+  def multi_tag
+    mail(
+      tags: "['test tag', 'another-tag']" # Multiple tags
+    )
+  end
+end
+```
+
+Note that this should always be a string, even if using an array of multiple tags.
+
+## List-Unsubscribe
+
+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.mailpace.com/guide/inbound/ for more details) via ActionMailbox. To set this up:
+
+1. Tell Action Mailbox to accept emails from MailPace in `config/environments/production.rb`
+
+```ruby
+config.action_mailbox.ingress = :mailpace
+```
+
+2. Generate a strong password that Action Mailbox can use to authenticate requests to the MailPace 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 MailPace to forward inbound emails to `/rails/action_mailbox/mailpace/inbound_emails` with the username `actionmailbox` and the password you previously generated. If your application lived at `https://example.com` you would configure your MailPace inbound endpoint URL with the following fully-qualified URL:
+
+`https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/mailpace/inbound_emails`
+
+That's it! Emails should start flowing into your app just like magic.
+## Support
+
+For support please check the [MailPace Documentation](https://docs.mailpace.com)  or contact us at support@mailpace.com
+
+## Contributing
+
+Please ensure to add a test for any change you make. To run the tests:
+
+`bin/test`
+
+Pull requests always welcome
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,27 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Mailpace::Rails'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  module Ingresses
+    module Mailpace
+      # Ingests inbound emails from MailPace. 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 MailPace
+      # - <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 MailPace:
+      #
+      #        # config/environments/production.rb
+      #        config.action_mailbox.ingress = :mailpace
+      #
+      # 2. Generate a strong password that Action Mailbox can use to authenticate requests to the MailPace 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 MailPace}[https://docs.mailpace.com/guide/inbound] to forward inbound emails
+      #    to +/rails/action_mailbox/mailpace/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
+      #    MailPace inbound endpoint URL with the following fully-qualified URL:
+      #
+      #        https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/mailpace/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/mailpace/inbound_emails', to: 'action_mailbox/ingresses/mailpace/inbound_emails#create',
+                                                       as: 'rails_mailpace_inbound_emails'
+end

data/lib/mailpace-rails/engine.rb

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

data/lib/mailpace-rails/version.rb

@@ -0,0 +1,5 @@
+module Mailpace
+  module Rails
+    VERSION = '0.3.0'
+  end
+end

data/lib/mailpace-rails.rb

@@ -0,0 +1,88 @@
+require 'action_mailer'
+require 'action_mailbox/engine'
+require 'httparty'
+require 'uri'
+require 'json'
+require 'mailpace-rails/version'
+require 'mailpace-rails/engine' if defined? Rails
+
+module Mailpace
+  # MailPace ActionMailer delivery method
+  class DeliveryMethod
+    attr_accessor :settings
+
+    def initialize(values)
+      check_api_token(values)
+      self.settings = { return_response: true }.merge!(values)
+    end
+
+    def deliver!(mail)
+      check_delivery_params(mail)
+      result = HTTParty.post(
+        'https://app.mailpace.com/api/v1/send',
+        body: {
+          from: mail.header[:from]&.address_list&.addresses&.first.to_s,
+          to: mail.to.join(','),
+          subject: mail.subject,
+          htmlbody: mail.html_part ? mail.html_part.body.decoded : mail.body.to_s,
+          textbody: if mail.multipart?
+                      mail.text_part ? mail.text_part.body.decoded : nil
+                    end,
+          cc: mail.cc&.join(','),
+          bcc: mail.bcc&.join(','),
+          replyto: mail.reply_to,
+          list_unsubscribe: mail.header['list_unsubscribe'].to_s,
+          attachments: format_attachments(mail.attachments),
+          tags: mail.header['tags'].to_s
+        }.delete_if { |_key, value| value.blank? }.to_json,
+        headers: {
+          'User-Agent' => "MailPace Rails Gem v#{Mailpace::Rails::VERSION}",
+          'Accept' => 'application/json',
+          'Content-Type' => 'application/json',
+          'Mailpace-Server-Token' => settings[:api_token]
+        }
+      )
+
+      handle_response(result)
+    end
+
+    private
+
+    def check_api_token(values)
+      return if values[:api_token].present?
+
+      raise ArgumentError, 'MailPace API token is not set'
+    end
+
+    def check_delivery_params(mail)
+      return unless mail.from.nil? || mail.to.nil?
+
+      raise ArgumentError, 'Missing to or from address in email'
+    end
+
+    def handle_response(result)
+      return result unless result.code != 200
+
+      # TODO: Improved error handling
+      res = result.parsed_response
+      raise res['error']&.to_s || res['errors']&.to_s
+    end
+
+    def format_attachments(attachments)
+      attachments.map do |attachment|
+        {
+          name: attachment.filename,
+          content_type: attachment.mime_type,
+          content: Base64.encode64(attachment.body.encoded),
+          cid: attachment.content_id
+        }.compact
+      end
+    end
+  end
+
+  class Error < StandardError; end
+
+  def self.root
+    Pathname.new(File.expand_path(File.join(__dir__, '..')))
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: mailpace-rails
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- MailPace
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-01-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.18.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.18.1
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.4.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.4.1
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+description: The MailPace Rails Gem is a plug in for ActionMailer to send emails via
+  MailPace to make sending emails from Rails apps super simple.
+email:
+- support@mailpace.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/action_mailbox/ingresses/mailpace/inbound_emails_controller.rb
+- config/routes.rb
+- lib/mailpace-rails.rb
+- lib/mailpace-rails/engine.rb
+- lib/mailpace-rails/version.rb
+homepage: https://mailpace.com
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Lets you send transactional emails from your app over an easy to use API
+test_files: []