mail_plugger 1.0.0.rc1 → 1.2.0

data/docs/usage_in_script_or_console.md

@@ -1,158 +0,0 @@
-# How to use MailPlugger in a Ruby script or IRB console
-
-First you should be able to `require 'mail'` and `require 'mail_plugger'` to get started.
-
-We need a class which will send the message in the right format via API.
-
-```ruby
-# NOTE: This is just an example for testing...
-class TestApiClientClass
-  def initialize(options = {})
-    @settings = { api_key: '12345' }
-    @options = options
-  end
-
-  def deliver
-    # e.g. API.new(@settings).client.post(generate_mail_hash)
-    puts " >>> settings: #{@settings.inspect}"
-    puts " >>> options: #{@options.inspect}"
-    puts " >>> generate_mail_hash: #{generate_mail_hash.inspect}"
-    { response: 'OK' }
-  end
-
-  private
-
-  def generate_mail_hash
-    {
-      to: generate_recipients,
-      from: {
-        email: @options[:from].first
-      },
-      subject: @options[:subject],
-      content: [
-        {
-          type: 'text/plain',
-          value: @options[:body]
-        }
-      ]
-    }
-  end
-
-  def generate_recipients
-    @options[:to].map do |to|
-      {
-        email: to
-      }
-    end
-  end
-end
-```
-
-We can use `MailPlugger.plug_in` to add our configurations.
-
-```ruby
-MailPlugger.plug_in('test_api_client') do |api|
-  api.delivery_options = %i[from to subject body]
-  api.client = TestApiClientClass
-end
-
-message = Mail.new(from: 'from@example.com', to: 'to@example.com', subject: 'Test email', body: 'Test email body')
-# => #<Mail::Message:1960, Multipart: false, Headers: <From: from@example.com>, <To: to@example.com>, <Subject: Tes...
-
-MailPlugger::DeliveryMethod.new.deliver!(message)
-# >>> settings: {:api_key=>"12345"}
-# >>> options: {"from"=>["from@example.com"], "to"=>["to@example.com"], "subject"=>"Test email", "body"=>"Test email body"}
-# >>> generate_mail_hash: {:to=>[{:email=>"to@example.com"}], :from=>{:email=>"from@example.com"}, :subject=>"Test email", :content=>[{:type=>"text/plain", :value=>"Test email body"}]}
-# => {:response=>"OK"}
-```
-
-Or we can use the `MailPlugger::DeliveryMethod` directly as well.
-
-```ruby
-message = Mail.new(from: 'from@example.com', to: 'to@example.com', subject: 'Test email', body: 'Test email body')
-# => #<Mail::Message:1960, Multipart: false, Headers: <From: from@example.com>, <To: to@example.com>, <Subject: Tes...
-
-MailPlugger::DeliveryMethod.new(delivery_options: %i[from to subject body], client: TestApiClientClass).deliver!(message)
-# >>> settings: {:api_key=>"12345"}
-# >>> options: {"from"=>["from@example.com"], "to"=>["to@example.com"], "subject"=>"Test email", "body"=>"Test email body"}
-# >>> generate_mail_hash: {:to=>[{:email=>"to@example.com"}], :from=>{:email=>"from@example.com"}, :subject=>"Test email", :content=>[{:type=>"text/plain", :value=>"Test email body"}]}
-# => {:response=>"OK"}
-```
-
-Or add `MailPlugger::DeliveryMethod` to `mail.delivery_method`.
-
-```ruby
-mail = Mail.new(from: 'from@example.com', to: 'to@example.com', subject: 'Test email', body: 'Test email body')
-# => #<Mail::Message:1960, Multipart: false, Headers: <From: from@example.com>, <To: to@example.com>, <Subject: Tes...
-
-mail.delivery_method MailPlugger::DeliveryMethod, { delivery_options: %i[from to subject body], client: TestApiClientClass }
-# => #<MailPlugger::DeliveryMethod:0x00007fecbbb2ca00 @delivery_options=[:from, :to, :subject, :body], @client=TestApiClientClass, @default_delivery_system=nil, @delivery_settings=nil, @message=nil>
-
-mail.deliver
-# >>> settings: {:api_key=>"12345"}
-# >>> options: {"from"=>["from@example.com"], "to"=>["to@example.com"], "subject"=>"Test email", "body"=>"Test email body"}
-# >>> generate_mail_hash: {:to=>[{:email=>"to@example.com"}], :from=>{:email=>"from@example.com"}, :subject=>"Test email", :content=>[{:type=>"text/plain", :value=>"Test email body"}]}
-# => #<Mail::Message:1960, Multipart: false, Headers: <From: from@example.com>, <To: to@example.com>, <Subject: Test email>>
-
-# or
-
-mail.deliver!
-# >>> settings: {:api_key=>"12345"}
-# >>> options: {"from"=>["from@example.com"], "to"=>["to@example.com"], "subject"=>"Test email", "body"=>"Test email body"}
-# >>> generate_mail_hash: {:to=>[{:email=>"to@example.com"}], :from=>{:email=>"from@example.com"}, :subject=>"Test email", :content=>[{:type=>"text/plain", :value=>"Test email body"}]}
-# => #<Mail::Message:1960, Multipart: false, Headers: <From: from@example.com>, <To: to@example.com>, <Subject: Test email>>
-```
-
-Let's add delivery settings to the delivery method.
-
-```ruby
-mail = Mail.new(from: 'from@example.com', to: 'to@example.com', subject: 'Test email', body: 'Test email body')
-# => #<Mail::Message:1960, Multipart: false, Headers: <From: from@example.com>, <To: to@example.com>, <Subject: Tes...
-
-mail.delivery_method MailPlugger::DeliveryMethod, { delivery_options: %i[from to subject body], client: TestApiClientClass, delivery_settings: { return_response: true } }
-# => #<MailPlugger::DeliveryMethod:0x00007fecbb9e3630 @delivery_options=[:from, :to, :subject, :body], @client=TestApiClientClass, @default_delivery_system=nil, @delivery_settings={:return_response=>true}, @message=nil>
-
-mail.deliver
-# >>> settings: {:api_key=>"12345"}
-# >>> options: {"from"=>["from@example.com"], "to"=>["to@example.com"], "subject"=>"Test email", "body"=>"Test email body"}
-# >>> generate_mail_hash: {:to=>[{:email=>"to@example.com"}], :from=>{:email=>"from@example.com"}, :subject=>"Test email", :content=>[{:type=>"text/plain", :value=>"Test email body"}]}
-# => #<Mail::Message:1960, Multipart: false, Headers: <From: from@example.com>, <To: to@example.com>, <Subject: Test email>>
-
-# or
-
-mail.deliver!
-# >>> settings: {:api_key=>"12345"}
-# >>> options: {"from"=>["from@example.com"], "to"=>["to@example.com"], "subject"=>"Test email", "body"=>"Test email body"}
-# >>> generate_mail_hash: {:to=>[{:email=>"to@example.com"}], :from=>{:email=>"from@example.com"}, :subject=>"Test email", :content=>[{:type=>"text/plain", :value=>"Test email body"}]}
-# => {:response=>"OK"}
-```
-
-Let's use `MailPlugger.plug_in` method.
-
-```ruby
-MailPlugger.plug_in('test_api_client') do |api|
-  api.delivery_options = %i[from to subject body]
-  api.delivery_settings = { return_response: true }
-  api.client = TestApiClientClass
-end
-
-mail = Mail.new(from: 'from@example.com', to: 'to@example.com', subject: 'Test email', body: 'Test email body')
-# => #<Mail::Message:1960, Multipart: false, Headers: <From: from@example.com>, <To: to@example.com>, <Subject: Tes...
-
-mail.delivery_method MailPlugger::DeliveryMethod
-# => #<MailPlugger::DeliveryMethod:0x00007ffed930b8f0 @delivery_options={"test_api_client"=>[:from, :to, :subject, :body]}, @client={"test_api_client"=>TestApiClientClass}, @default_delivery_system="test_api_client", @delivery_settings={"test_api_client"=>{:return_response=>true}}, @message=nil>
-
-mail.deliver
-# >>> settings: {:api_key=>"12345"}
-# >>> options: {"from"=>["from@example.com"], "to"=>["to@example.com"], "subject"=>"Test email", "body"=>"Test email body"}
-# >>> generate_mail_hash: {:to=>[{:email=>"to@example.com"}], :from=>{:email=>"from@example.com"}, :subject=>"Test email", :content=>[{:type=>"text/plain", :value=>"Test email body"}]}
-# => #<Mail::Message:1960, Multipart: false, Headers: <From: from@example.com>, <To: to@example.com>, <Subject: Test email>>
-
-# or
-
-mail.deliver!
-# >>> settings: {:api_key=>"12345"}
-# >>> options: {"from"=>["from@example.com"], "to"=>["to@example.com"], "subject"=>"Test email", "body"=>"Test email body"}
-# >>> generate_mail_hash: {:to=>[{:email=>"to@example.com"}], :from=>{:email=>"from@example.com"}, :subject=>"Test email", :content=>[{:type=>"text/plain", :value=>"Test email body"}]}
-# => {:response=>"OK"}
-```

data/docs/usage_of_attachments_in_ruby_on_rails.md

@@ -1,110 +0,0 @@
-# How to add attachments to the mailer method in Ruby on Rails
-
-Let's use mailer method which was defined [here](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_in_ruby_on_rails.md).
-
-Change the API and `MailPlugger.plug_in` method in `config/initializers/mail_plugger.rb`.
-
-```ruby
-# NOTE: This is just an example for testing...
-class TestApiClientClass
-  def initialize(options = {})
-    @settings = { api_key: '12345' }
-    @options = options
-  end
-
-  def deliver
-    # e.g. API.new(@settings).client.post(generate_mail_hash)
-    puts " >>> settings: #{@settings.inspect}"
-    puts " >>> options: #{@options.inspect}"
-    puts " >>> generate_mail_hash: #{generate_mail_hash.inspect}"
-    { response: 'OK' }
-  end
-
-  private
-
-  def generate_mail_hash
-    {
-      to: generate_recipients,
-      from: {
-        email: @options[:from].first
-      },
-      subject: @options[:subject],
-      content: [
-        {
-          type: 'text/plain',
-          value: @options[:text_part]
-        },
-        {
-          type: 'text/html; charset=UTF-8',
-          value: @options[:html_part]
-        }
-      ],
-      attachments: generate_attachments
-    }
-  end
-
-  def generate_recipients
-    @options[:to].map do |to|
-      {
-        email: to
-      }
-    end
-  end
-
-  def generate_attachments
-    @options[:attachments].map do |attachment|
-      hash = {
-          filename: attachment[:filename],
-          type: attachment[:type],
-          content: attachment[:content]
-        }
-      hash.merge!(content_id: attachment[:cid]) if attachment.has_key?(:cid)
-
-      hash
-    end
-  end
-end
-
-MailPlugger.plug_in('test_api_client') do |api|
-  api.delivery_options = %i[from to subject text_part html_part attachments]
-  api.delivery_settings = { return_response: true }
-  api.client = TestApiClientClass
-end
-```
-
-Let's change `app/mailers/test_mailer.rb` file.
-
-```ruby
-class TestMailer < ApplicationMailer
-  default from: 'from@example.com'
-
-  def send_test
-    attachments['image1.png'] = File.read('/path/to/image1.png')
-    attachments.inline['image2.png'] = File.read('/path/to/image2.png')
-
-    mail subject: 'Test email', to: 'to@example.com'
-  end
-end
-```
-
-Then change `app/views/test_mailer/send_test.html.erb` and add inline attachment.
-
-```erb
-<p>Test email body</p>
-<%= image_tag attachments['image2.png'].url %>
-```
-
-In the `rails console` we can try it out.
-
-```ruby
-TestMailer.send_test.deliver_now!
-#  Rendering test_mailer/send_test.html.erb within layouts/mailer
-#  Rendered test_mailer/send_test.html.erb within layouts/mailer (4.6ms)
-#  Rendering test_mailer/send_test.text.erb within layouts/mailer
-#  Rendered test_mailer/send_test.text.erb within layouts/mailer (0.3ms)
-#TestMailer#send_test: processed outbound mail in 47.5ms
-# >>> settings: {:api_key=>"12345"}
-# >>> options: {"from"=>["from@example.com"], "to"=>["to@example.com"], "subject"=>"Test email", "text_part"=>"Test email body\n\n", "html_part"=>"<!DOCTYPE html>\n<html>\n  <head>\n    <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\" />\n    <style>\n      /* Email styles need to be inline */\n    </style>\n  </head>\n\n  <body>\n    <p>Test email body</p>\n<img src=\"cid:5ffdd449d282a_163e2ef9c62c0@server.local.mail\" />\n\n  </body>\n</html>\n", "attachments"=>[{"filename"=>"image1.png", "type"=>"image/png", "content"=>"iVBORw0KGgoAAAANSUhEUgAAALQAAABdCAMAAAA7WLggg==\n"}, {"cid"=>"5ffdd449d282a_163e2ef9c62c0@server.local.mail", "filename"=>"image2.png", "type"=>"image/png", "content"=>"iVBORw0KGgoAAAANSUhEUgAAAAggg==\n"}]}
-# >>> generate_mail_hash: {:to=>[{:email=>"to@example.com"}], :from=>{:email=>"from@example.com"}, :subject=>"Test email", :content=>[{:type=>"text/plain", :value=>"Test email body\n\n"}, {:type=>"text/html; charset=UTF-8", :value=>"<!DOCTYPE html>\n<html>\n  <head>\n    <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\" />\n    <style>\n      /* Email styles need to be inline */\n    </style>\n  </head>\n\n  <body>\n    <p>Test email body</p>\n<img src=\"cid:5ffdd449d282a_163e2ef9c62c0@server.local.mail\" />\n\n  </body>\n</html>\n"}], :attachments=>[{:filename=>"image1.png", :type=>"image/png", :content=>"iVBORw0KGgoAAAANSUhEUgAAALQAAABdCAMAAAA7WLggg==\n"}, {:filename=>"image2.png", :type=>"image/png", :content=>"iVBORw0KGgoAAAANSUhEUgAAAAggg==\n", :content_id=>"5ffdd449d282a_163e2ef9c62c0@server.local.mail"}]}
-#=> {:response=>"OK"}
-```

data/docs/usage_of_aws_ses_in_ruby_on_rails.md

@@ -1,136 +0,0 @@
-# How to use AWS SES with MailPlugger in Ruby on Rails
-
-**Please note that these examples were not tested, but I believe it should work.**
-
-Let's use mailer method which was defined [here](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_in_ruby_on_rails.md).
-
-Add `aws-sdk-gem` to the `Gemfile`.
-
-```ruby
-gem 'aws-sdk-ses'
-```
-
-Then run `bundle install` command to deploy the gem.
-
-## Send Email
-
-Change the API and `MailPlugger.plug_in` method in `config/initializers/mail_plugger.rb`.
-
-```ruby
-class AwsSesApiClient
-  def initialize(options = {})
-    @credentials = Aws::Credentials.new(ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY'])
-    @region = ENV['AWS_DEFAULT_REGION']
-    @options = options
-  end
-
-  def deliver
-    Aws::SES::Client.new(credentials: @credentials, region: @region).send_email(generate_mail_hash)
-  end
-
-  private
-
-  def generate_mail_hash
-    {
-      source: @options[:from].first,
-      destination: {
-        to_addresses: @options[:to]
-      },
-      message: {
-        subject: {
-          charset: 'UTF-8',
-          data: @options[:subject]
-        },
-        body: {
-          text: {
-            charset: 'UTF-8',
-            data: @options[:text_part]
-          },
-          html: {
-            charset: 'UTF-8',
-            data: @options[:html_part]
-          }
-        }
-      },
-      tags: [
-        {
-          name: @options[:message_obj].delivery_handler.to_s,
-          value: @options[:tag]
-        }
-      ],
-      configuration_set_name: @options[:configuration_set_name]
-    }
-  end
-end
-
-MailPlugger.plug_in('aws_ses') do |api|
-  api.delivery_options = %i[from to subject text_part html_part message_obj tag configuration_set_name]
-  api.delivery_settings = { return_response: true }
-  api.client = AwsSesApiClient
-end
-```
-
-Then modify the mailer method a little bit.
-
-```ruby
-class TestMailer < ApplicationMailer
-  default from: 'from@example.com'
-
-  def send_test
-    mail subject: 'Test email', to: 'to@example.com', delivery_system: 'aws_ses', tag: 'send_test', configuration_set_name: "#{Rails.env}_events_tracking"
-  end
-end
-```
-
-## Send Raw Email
-
-Change the API and `MailPlugger.plug_in` method in `config/initializers/mail_plugger.rb`.
-
-```ruby
-class AwsSesApiClient
-  def initialize(options = {})
-    @credentials = Aws::Credentials.new(ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY'])
-    @region = ENV['AWS_DEFAULT_REGION']
-    @options = options
-  end
-
-  def deliver
-    Aws::SES::Client.new(credentials: @credentials, region: @region).send_raw_email(generate_mail_hash)
-  end
-
-  private
-
-  def generate_mail_hash
-    {
-      raw_message: {
-        data: @options[:message_obj].to_s
-      },
-      tags: [
-        {
-          name:  @options[:message_obj].delivery_handler.to_s,
-          value: @options[:tag]
-        }
-      ],
-      configuration_set_name: @options[:configuration_set_name]
-    }
-  end
-end
-
-MailPlugger.plug_in('aws_ses') do |api|
-  api.delivery_options = %i[message_obj tag configuration_set_name]
-  api.delivery_settings = { return_response: true }
-  api.client = AwsSesApiClient
-end
-```
-
-Then modify the mailer method a little bit.
-
-```ruby
-class TestMailer < ApplicationMailer
-  default from: 'from@example.com'
-
-  def send_test
-    mail subject: 'Test email', to: 'to@example.com', delivery_system: 'aws_ses', tag: 'send_test', configuration_set_name: "#{Rails.env}_events_tracking"
-  end
-end
-```

data/docs/usage_of_delivery_method.md

@@ -1,104 +0,0 @@
-# How to use MailPlugger::DeliveryMethod class
-
-With this class it can extract data from the Mail::Message object and send message based on the given configurations. We can add these options directly in the `new` method or we can use `MailPlugger.plug_in` method as well.
-
-The `new` method parameter is a Hash where the keys are Symbols.
-
-Hash parameters:
-- `client` which should be a Class (It can be a Hash with this Class as well. In this case the key of the Hash is the `delivery_system` from the `Mail::Message` object or the `default_delivery_system`). This Class is a special class which generates the data and calls the API to send the message.
-- `delivery_options` which should be an Array with Symbols or Strings (It can be a Hash with this Array as well. In this case the key of the Hash is the `delivery_system` from the `Mail::Message` object or the `default_delivery_system`). It will search these options in the `Mail::Message` object like `from`, `to`, `cc`, `bcc`, `subject`, `body`, `text_part`, `html_part`, `attachments` or anything what we will add to this object. Also we can retrieve the `Mail::Message` object with `message_obj`.
-- `delivery_settings` which should be a Hash. The Mail gem can use these settings like `{ return_response: true }` (The keys are should be Symbols).
-- `default_delivery_system` which should be a String or Symbol. This option is needed when `delivery_options` and `client` are Hashes. When `delivery_system` in the `Mail::Message` object is not defined then the `default_delivery_system` value is the key of those Hashes. When `default_delivery_system` is not defined then `default_delivery_system_get` will return with the first key of `delivery_options` or `client` Hash.
-
-Examples:
-
-```ruby
-# NOTE: This is just an example for testing...
-class TestApiClientClass
-  def initialize(options = {})
-    @settings = { api_key: '12345' }
-    @options = options
-  end
-
-  def deliver
-    # e.g. API.new(@settings).client.post(generate_mail_hash)
-    puts " >>> settings: #{@settings.inspect}"
-    puts " >>> options: #{@options.inspect}"
-    puts " >>> generate_mail_hash: #{generate_mail_hash.inspect}"
-    { response: 'OK' }
-  end
-
-  private
-
-  def generate_mail_hash
-    {
-      to: generate_recipients,
-      from: {
-        email: @options[:from].first
-      },
-      subject: @options[:subject],
-      content: [
-        {
-          type: 'text/plain',
-          value: @options[:body]
-        }
-      ]
-    }
-  end
-
-  def generate_recipients
-    @options[:to].map do |to|
-      {
-        email: to
-      }
-    end
-  end
-end
-```
-
-We can add simple options to `MailPlugger::DeliveryMethod`.
-
-```ruby
-message = Mail.new(from: 'from@example.com', to: 'to@example.com', subject: 'Test email', body: 'Test email body')
-
-MailPlugger::DeliveryMethod.new(delivery_options: %i[from to subject body], client: TestApiClientClass).deliver!(message)
-```
-
-Or we can add these options in Hash and set `default_delivery_system`.
-
-```ruby
-message = Mail.new(from: 'from@example.com', to: 'to@example.com', subject: 'Test email', body: 'Test email body')
-
-MailPlugger::DeliveryMethod.new(delivery_options: { 'test_api_client' => %i[from to subject body] }, client: { 'test_api_client' => TestApiClientClass }, default_delivery_system: 'test_api_client').deliver!(message)
-```
-
-Add `delivery_system` in the `Mail::Message` object (it will search this value in the given Hash). The `delivery_system` type in the `Mail::Message` object should match with the given key type of the Hash (if `delivery_system` is String then Hash key should String as well).
-
-```ruby
-message = Mail.new(from: 'from@example.com', to: 'to@example.com', subject: 'Test email', body: 'Test email body', delivery_system: 'test_api_client')
-
-MailPlugger::DeliveryMethod.new(delivery_options: { 'test_api_client' => %i[from to subject body] }, client: { 'test_api_client' => TestApiClientClass }).deliver!(message)
-```
-
-If we are not adding `delivery_system` anywhere then it will use the first key of the Hash.
-
-```ruby
-message = Mail.new(from: 'from@example.com', to: 'to@example.com', subject: 'Test email', body: 'Test email body')
-
-MailPlugger::DeliveryMethod.new(delivery_options: { 'test_api_client' => %i[from to subject body] }, client: { 'test_api_client' => TestApiClientClass }).deliver!(message)
-```
-
-We can use `MailPlugger.plug_in` to add our configurations.
-
-```ruby
-MailPlugger.plug_in('test_api_client') do |api|
-  api.delivery_options = %i[from to subject body]
-  api.client = TestApiClientClass
-end
-
-message = Mail.new(from: 'from@example.com', to: 'to@example.com', subject: 'Test email', body: 'Test email body')
-
-MailPlugger::DeliveryMethod.new.deliver!(message)
-```
-
-If we are using `mail_plugger` gem in Ruby on Rails we don't have to do anything with this class. Rails will load this method automatically. Basically we should use `MailPlugger.plug_in` method to configure this delivery method.