mail_plugger 1.0.0.beta1 → 1.0.0.rc1

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,119 @@
1
+ # How to use one delivey system with more send methods in Ruby on Rails
2
+
3
+ Let's modify the configuration which was defined [here](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_more_delivery_system_in_ruby_on_rails.md).
4
+
5
+ Change the API and `MailPlugger.plug_in` method in `config/initializers/mail_plugger.rb`.
6
+
7
+ ```ruby
8
+ # NOTE: This is just an example for testing...
9
+ class TestApiClientClass
10
+ def initialize(options = {})
11
+ @settings = { api_key: '12345' }
12
+ @options = options
13
+ end
14
+
15
+ def deliver
16
+ # e.g. API.new(@settings).client.post(generate_mail_hash)
17
+ puts " >>> settings: #{@settings.inspect}"
18
+ puts " >>> options: #{@options.inspect}"
19
+ case @options[:send_method]
20
+ when 'send_email1'
21
+ client.send_email1(generate_mail_hash)
22
+ when 'send_email2'
23
+ client.send_email2(generate_mail_hash)
24
+ end
25
+ end
26
+
27
+ private
28
+
29
+ def client
30
+ Class.new do
31
+ def self.send_email1(params)
32
+ puts " >>>>> send_email1 params: #{params.inspect}"
33
+ { response: 'Send email version 1' }
34
+ end
35
+
36
+ def self.send_email2(params)
37
+ puts " >>>>> send_email2 params: #{params.inspect}"
38
+ { response: 'Send email version 2' }
39
+ end
40
+ end
41
+ end
42
+
43
+ def generate_mail_hash
44
+ {
45
+ to: generate_recipients,
46
+ from: {
47
+ email: @options[:from].first
48
+ },
49
+ subject: @options[:subject],
50
+ content: [
51
+ {
52
+ type: 'text/plain',
53
+ value: @options[:text_part]
54
+ },
55
+ {
56
+ type: 'text/html; charset=UTF-8',
57
+ value: @options[:html_part]
58
+ }
59
+ ]
60
+ }
61
+ end
62
+
63
+ def generate_recipients
64
+ @options[:to].map do |to|
65
+ {
66
+ email: to
67
+ }
68
+ end
69
+ end
70
+ end
71
+
72
+ MailPlugger.plug_in('test_api_client') do |api|
73
+ api.delivery_options = %i[from to subject text_part html_part send_method]
74
+ api.delivery_settings = { return_response: true }
75
+ api.client = TestApiClientClass
76
+ end
77
+ ```
78
+
79
+ Then change `app/mailers/test_mailer.rb` file.
80
+
81
+ ```ruby
82
+ class TestMailer < ApplicationMailer
83
+ default from: 'from@example.com', delivery_system: 'test_api_client'
84
+
85
+ def send_test
86
+ mail subject: 'Test email', to: 'to@example.com', send_method: 'send_email1'
87
+ end
88
+
89
+ def send_test2
90
+ mail subject: 'Test email', to: 'to@example.com', send_method: 'send_email2'
91
+ end
92
+ end
93
+ ```
94
+
95
+ In the `rails console` we can try it out.
96
+
97
+ ```ruby
98
+ TestMailer.send_test.deliver_now!
99
+ # Rendering test_mailer/send_test.html.erb within layouts/mailer
100
+ # Rendered test_mailer/send_test.html.erb within layouts/mailer (0.7ms)
101
+ # Rendering test_mailer/send_test.text.erb within layouts/mailer
102
+ # Rendered test_mailer/send_test.text.erb within layouts/mailer (0.2ms)
103
+ #TestMailer#send_test: processed outbound mail in 31.6ms
104
+ # >>> settings: {:api_key=>"12345"}
105
+ # >>> 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\n </body>\n</html>\n", "send_method"=>"send_email1"}
106
+ # >>>>> send_email1 params: {: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\n </body>\n</html>\n"}]}
107
+ #=> {:response=>"Send email version 1"}
108
+
109
+ TestMailer.send_test2.deliver_now!
110
+ # Rendering test_mailer/send_test2.html.erb within layouts/mailer
111
+ # Rendered test_mailer/send_test2.html.erb within layouts/mailer (0.4ms)
112
+ # Rendering test_mailer/send_test2.text.erb within layouts/mailer
113
+ # Rendered test_mailer/send_test2.text.erb within layouts/mailer (0.3ms)
114
+ #TestMailer#send_test2: processed outbound mail in 17.5ms
115
+ # >>> settings: {:api_key=>"12345"}
116
+ # >>> 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\n </body>\n</html>\n", "send_method"=>"send_email2"}
117
+ # >>>>> send_email2 params: {: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\n </body>\n</html>\n"}]}
118
+ #=> {:response=>"Send email version 2"}
119
+ ```
@@ -0,0 +1,62 @@
1
+ # How to use MailPlugger.plug_in method
2
+
3
+ With `plug_in` method we can add configurations for the delivery method.
4
+
5
+ It has a parameter which calls to `delivery_system`. This parameter is a name of the delivery system like `aws_ses`, `sparkpost`, `sendgrid`, etc. Basically it can be anything which helps to identify this delivery system. The `delivery_system` can be either String or Symbol, but the `delivery_system` type should match with the type of the `Mail::Message` object `delivery_system` parameter (if `delivery_system` is String then in the `Mail::Message` object `delivery_system` parameter should be String as well).
6
+
7
+ It can accept 3 configurations:
8
+ - `client` which should be a Class. This Class is a special class which generates the data and calls the API to send the message.
9
+ - `delivery_options` which should be an Array with Symbols or Strings. 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`.
10
+ - `delivery_settings` which should be a Hash. The Mail gem can use these settings like `{ return_response: true }` (The keys are should be Symbols).
11
+
12
+ Example:
13
+
14
+ ```ruby
15
+ # NOTE: This is just an example for testing...
16
+ class TestApiClientClass
17
+ def initialize(options = {})
18
+ @settings = { api_key: '12345' }
19
+ @options = options
20
+ end
21
+
22
+ def deliver
23
+ # e.g. API.new(@settings).client.post(generate_mail_hash)
24
+ puts " >>> settings: #{@settings.inspect}"
25
+ puts " >>> options: #{@options.inspect}"
26
+ puts " >>> generate_mail_hash: #{generate_mail_hash.inspect}"
27
+ { response: 'OK' }
28
+ end
29
+
30
+ private
31
+
32
+ def generate_mail_hash
33
+ {
34
+ to: generate_recipients,
35
+ from: {
36
+ email: @options[:from].first
37
+ },
38
+ subject: @options[:subject],
39
+ content: [
40
+ {
41
+ type: 'text/plain',
42
+ value: @options[:body]
43
+ }
44
+ ]
45
+ }
46
+ end
47
+
48
+ def generate_recipients
49
+ @options[:to].map do |to|
50
+ {
51
+ email: to
52
+ }
53
+ end
54
+ end
55
+ end
56
+
57
+ MailPlugger.plug_in('test_api_client') do |api|
58
+ api.delivery_options = %i[from to subject body]
59
+ api.delivery_settings = { return_response: true }
60
+ api.client = TestApiClientClass
61
+ end
62
+ ```
@@ -0,0 +1,59 @@
1
+ # How to use Postmark with MailPlugger in Ruby on Rails
2
+
3
+ **Please note that these examples were not tested, but I believe it should work.**
4
+
5
+ Let's use mailer method which was defined [here](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_in_ruby_on_rails.md).
6
+
7
+ Add `postmark` to the `Gemfile`.
8
+
9
+ ```ruby
10
+ gem 'postmark'
11
+ ```
12
+
13
+ Then run `bundle install` command to deploy the gem.
14
+
15
+ Change the API and `MailPlugger.plug_in` method in `config/initializers/mail_plugger.rb`.
16
+
17
+ ```ruby
18
+ class PostmarkApiClient
19
+ def initialize(options = {})
20
+ @settings = { token: ENV['POSTMARK_TOKEN'] }
21
+ @options = options
22
+ end
23
+
24
+ def deliver
25
+ Postmark::ApiClient.new(@settings[:token]).deliver(generate_mail_hash)
26
+ end
27
+
28
+ private
29
+
30
+ def generate_mail_hash
31
+ {
32
+ from: @options[:from].first,
33
+ to: @options[:to],
34
+ subject: @options[:subject],
35
+ text_body: @options[:text_part],
36
+ html_body: @options[:html_part],
37
+ tag: @options[:tag]
38
+ }
39
+ end
40
+ end
41
+
42
+ MailPlugger.plug_in('postmark') do |api|
43
+ api.delivery_options = %i[from to subject text_part html_part tag]
44
+ api.delivery_settings = { return_response: true }
45
+ api.client = PostmarkApiClient
46
+ end
47
+ ```
48
+
49
+ Then modify the mailer method a little bit.
50
+
51
+ ```ruby
52
+ class TestMailer < ApplicationMailer
53
+ default from: 'from@example.com'
54
+
55
+ def send_test
56
+ mail subject: 'Test email', to: 'to@example.com', delivery_system: 'postmark', tag: 'send_test'
57
+ end
58
+ end
59
+ ```
@@ -0,0 +1,90 @@
1
+ # How to add API specific options to the mailer method in Ruby on Rails
2
+
3
+ Let's use mailer method which was defined [here](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_in_ruby_on_rails.md).
4
+
5
+ Change the API and `MailPlugger.plug_in` method in `config/initializers/mail_plugger.rb`.
6
+
7
+ ```ruby
8
+ # NOTE: This is just an example for testing...
9
+ class TestApiClientClass
10
+ def initialize(options = {})
11
+ @settings = { api_key: '12345' }
12
+ @options = options
13
+ end
14
+
15
+ def deliver
16
+ # e.g. API.new(@settings).client.post(generate_mail_hash)
17
+ puts " >>> settings: #{@settings.inspect}"
18
+ puts " >>> options: #{@options.inspect}"
19
+ puts " >>> generate_mail_hash: #{generate_mail_hash.inspect}"
20
+ { response: 'OK' }
21
+ end
22
+
23
+ private
24
+
25
+ def generate_mail_hash
26
+ {
27
+ to: generate_recipients,
28
+ from: {
29
+ email: @options[:from].first
30
+ },
31
+ subject: @options[:subject],
32
+ content: [
33
+ {
34
+ type: 'text/plain',
35
+ value: @options[:text_part]
36
+ },
37
+ {
38
+ type: 'text/html; charset=UTF-8',
39
+ value: @options[:html_part]
40
+ }
41
+ ],
42
+ string: @options[:string],
43
+ boolean: @options[:boolean],
44
+ array: @options[:array],
45
+ hash: @options[:hash]
46
+ }
47
+ end
48
+
49
+ def generate_recipients
50
+ @options[:to].map do |to|
51
+ {
52
+ email: to
53
+ }
54
+ end
55
+ end
56
+ end
57
+
58
+ MailPlugger.plug_in('test_api_client') do |api|
59
+ api.delivery_options = %i[from to subject text_part html_part string boolean array hash]
60
+ api.delivery_settings = { return_response: true }
61
+ api.client = TestApiClientClass
62
+ end
63
+ ```
64
+
65
+ So add special API options to the mailer method. Let's change `app/mailers/test_mailer.rb` file.
66
+
67
+ ```ruby
68
+ class TestMailer < ApplicationMailer
69
+ default from: 'from@example.com'
70
+
71
+ def send_test
72
+ mail subject: 'Test email', to: 'to@example.com', string: 'This is the string', boolean: true, array: ['This', 'is', 'the array'], hash: { this: 'is the hash' }
73
+ end
74
+ end
75
+ ```
76
+
77
+ In the `rails console` we can try it out.
78
+
79
+ ```ruby
80
+ TestMailer.send_test.deliver_now!
81
+ # Rendering test_mailer/send_test.html.erb within layouts/mailer
82
+ # Rendered test_mailer/send_test.html.erb within layouts/mailer (0.9ms)
83
+ # Rendering test_mailer/send_test.text.erb within layouts/mailer
84
+ # Rendered test_mailer/send_test.text.erb within layouts/mailer (0.5ms)
85
+ #TestMailer#send_test: processed outbound mail in 35.3ms
86
+ # >>> settings: {:api_key=>"12345"}
87
+ # >>> 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\n </body>\n</html>\n", "string"=>"This is the string", "boolean"=>true, "array"=>["This", "is", "the array"], "hash"=>{"this"=>"is the hash"}}
88
+ # >>> 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\n </body>\n</html>\n"}], :string=>"This is the string", :boolean=>true, :array=>["This", "is", "the array"], :hash=>{:this=>"is the hash"}}
89
+ #=> {:response=>"OK"}
90
+ ```
@@ -0,0 +1,82 @@
1
+ # How to use SendGrid with MailPlugger in Ruby on Rails
2
+
3
+ **Please note that these examples were not tested, but I believe it should work.**
4
+
5
+ Let's use mailer method which was defined [here](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_in_ruby_on_rails.md).
6
+
7
+ Add `sendgrid-ruby` to the `Gemfile`.
8
+
9
+ ```ruby
10
+ gem 'sendgrid-ruby'
11
+ ```
12
+
13
+ Then run `bundle install` command to deploy the gem.
14
+
15
+ Change the API and `MailPlugger.plug_in` method in `config/initializers/mail_plugger.rb`.
16
+
17
+ ```ruby
18
+ class SendGridApiClient
19
+ def initialize(options = {})
20
+ @settings = { api_key: ENV['SENDGRID_API_KEY'] }
21
+ @options = options
22
+ end
23
+
24
+ def deliver
25
+ SendGrid::API.new(@settings).client.mail._("send").post(generate_mail_hash)
26
+ end
27
+
28
+ private
29
+
30
+ def generate_mail_hash
31
+ {
32
+ request_body: {
33
+ personalizations: [
34
+ {
35
+ to: generate_recipients,
36
+ subject: @options[:subject]
37
+ }
38
+ ],
39
+ from: {
40
+ email: @options[:from].first
41
+ },
42
+ content: [
43
+ {
44
+ type: 'text/plain',
45
+ value: @options[:text_part]
46
+ },
47
+ {
48
+ type: 'text/html',
49
+ value: @options[:html_part]
50
+ }
51
+ ]
52
+ }
53
+ }
54
+ end
55
+
56
+ def generate_recipients
57
+ @options[:to].map do |to|
58
+ {
59
+ email: to
60
+ }
61
+ end
62
+ end
63
+ end
64
+
65
+ MailPlugger.plug_in('sendgrid') do |api|
66
+ api.delivery_options = %i[from to subject text_part html_part]
67
+ api.delivery_settings = { return_response: true }
68
+ api.client = SendGridApiClient
69
+ end
70
+ ```
71
+
72
+ Then modify the mailer method a little bit.
73
+
74
+ ```ruby
75
+ class TestMailer < ApplicationMailer
76
+ default from: 'from@example.com'
77
+
78
+ def send_test
79
+ mail subject: 'Test email', to: 'to@example.com', delivery_system: 'sendgrid'
80
+ end
81
+ end
82
+ ```
@@ -0,0 +1,142 @@
1
+ # How to use SparkPost with MailPlugger in Ruby on Rails
2
+
3
+ **Please note that these examples were not tested, but I believe it should work.**
4
+
5
+ Let's use mailer method which was defined [here](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_in_ruby_on_rails.md).
6
+
7
+ Add `simple_spark` to the `Gemfile`.
8
+
9
+ ```ruby
10
+ gem 'simple_spark'
11
+ ```
12
+
13
+ Then run `bundle install` command to deploy the gem.
14
+
15
+ ## Send Inline Content
16
+
17
+ Change the API and `MailPlugger.plug_in` method in `config/initializers/mail_plugger.rb`.
18
+
19
+ ```ruby
20
+ class SparkPostApiClient
21
+ def initialize(options = {})
22
+ @settings = { api_key: ENV['SPARKPOST_API_KEY'] }
23
+ @options = options
24
+ end
25
+
26
+ def deliver
27
+ SimpleSpark::Client.new(@settings).transmissions.create(generate_mail_hash)
28
+ end
29
+
30
+ private
31
+
32
+ def generate_mail_hash
33
+ {
34
+ options: @options[:options],
35
+ campaign_id: @options[:tag],
36
+ content: {
37
+ from: {
38
+ email: @options[:from].first
39
+ },
40
+ subject: @options[:subject],
41
+ text: @options[:text_part],
42
+ html: @options[:html_part]
43
+ },
44
+ metadata: @options[:metadata],
45
+ recipients: generate_recipients
46
+ }
47
+ end
48
+
49
+ def generate_recipients
50
+ @options[:to].map do |to|
51
+ {
52
+ address: {
53
+ email: to
54
+ },
55
+ tags: [
56
+ @options[:tag]
57
+ ],
58
+ }
59
+ end
60
+ end
61
+ end
62
+
63
+ MailPlugger.plug_in('sparkpost') do |api|
64
+ api.delivery_options = %i[from to subject text_part html_part options tag metadata]
65
+ api.delivery_settings = { return_response: true }
66
+ api.client = SparkPostApiClient
67
+ end
68
+ ```
69
+
70
+ Then modify the mailer method a little bit.
71
+
72
+ ```ruby
73
+ class TestMailer < ApplicationMailer
74
+ default from: 'from@example.com'
75
+
76
+ def send_test
77
+ mail subject: 'Test email', to: 'to@example.com', delivery_system: 'sparkpost', tag: 'send_test', options: { open_tracking: true, click_tracking: false, transactional: true }, metadata: { website: 'testwebsite' }
78
+ end
79
+ end
80
+ ```
81
+
82
+ ## Send RFC822 Content
83
+
84
+ Change the API and `MailPlugger.plug_in` method in `config/initializers/mail_plugger.rb`.
85
+
86
+ ```ruby
87
+ class SparkPostApiClient
88
+ def initialize(options = {})
89
+ @settings = { api_key: ENV['SPARKPOST_API_KEY'] }
90
+ @options = options
91
+ end
92
+
93
+ def deliver
94
+ SimpleSpark::Client.new(@settings).transmissions.create(generate_mail_hash)
95
+ end
96
+
97
+ private
98
+
99
+ def generate_mail_hash
100
+ {
101
+ options: @options[:options],
102
+ campaign_id: @options[:tag],
103
+ content: {
104
+ email_rfc822: @options[:message_obj].to_s
105
+ },
106
+ metadata: @options[:metadata],
107
+ recipients: generate_recipients
108
+ }
109
+ end
110
+
111
+ def generate_recipients
112
+ @options[:to].map do |to|
113
+ {
114
+ address: {
115
+ email: to
116
+ },
117
+ tags: [
118
+ @options[:tag]
119
+ ],
120
+ }
121
+ end
122
+ end
123
+ end
124
+
125
+ MailPlugger.plug_in('sparkpost') do |api|
126
+ api.delivery_options = %i[to options message_obj tag metadata]
127
+ api.delivery_settings = { return_response: true }
128
+ api.client = SparkPostApiClient
129
+ end
130
+ ```
131
+
132
+ Then modify the mailer method a little bit.
133
+
134
+ ```ruby
135
+ class TestMailer < ApplicationMailer
136
+ default from: 'from@example.com'
137
+
138
+ def send_test
139
+ mail subject: 'Test email', to: 'to@example.com', delivery_system: 'sparkpost', tag: 'send_test', options: { open_tracking: true, click_tracking: false, transactional: true }, metadata: { website: 'testwebsite' }
140
+ end
141
+ end
142
+ ```