mailgun-ruby 1.1.2 → 1.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +5 -5
- data/.ruby-env.yml.example +1 -1
- data/.travis.yml +8 -5
- data/Gemfile +1 -1
- data/README.md +77 -9
- data/{Domains.md → docs/Domains.md} +18 -0
- data/{Events.md → docs/Events.md} +0 -0
- data/{MessageBuilder.md → docs/MessageBuilder.md} +24 -5
- data/{Messages.md → docs/Messages.md} +3 -3
- data/{OptInHandler.md → docs/OptInHandler.md} +0 -0
- data/{Snippets.md → docs/Snippets.md} +21 -2
- data/docs/Suppressions.md +82 -0
- data/{Webhooks.md → docs/Webhooks.md} +1 -1
- data/docs/railgun/Overview.md +11 -0
- data/docs/railgun/Parameters.md +83 -0
- data/lib/mailgun/address.rb +5 -2
- data/lib/mailgun/client.rb +39 -8
- data/lib/mailgun/events/events.rb +40 -12
- data/lib/mailgun/messages/batch_message.rb +3 -2
- data/lib/mailgun/messages/message_builder.rb +99 -26
- data/lib/mailgun/suppressions.rb +273 -0
- data/lib/mailgun/version.rb +1 -1
- data/lib/mailgun/webhooks/webhooks.rb +1 -1
- data/lib/mailgun-ruby.rb +2 -1
- data/lib/railgun/attachment.rb +56 -0
- data/lib/railgun/errors.rb +27 -0
- data/lib/railgun/mailer.rb +237 -0
- data/lib/railgun/message.rb +17 -0
- data/lib/railgun/railtie.rb +10 -0
- data/lib/railgun.rb +8 -0
- data/mailgun.gemspec +12 -12
- data/spec/integration/email_validation_spec.rb +14 -0
- data/spec/integration/events_spec.rb +9 -1
- data/spec/integration/mailgun_spec.rb +0 -0
- data/spec/integration/suppressions_spec.rb +142 -0
- data/spec/spec_helper.rb +3 -1
- data/spec/unit/events/events_spec.rb +36 -2
- data/spec/unit/messages/batch_message_spec.rb +1 -0
- data/spec/unit/messages/message_builder_spec.rb +95 -19
- data/spec/unit/messages/sample_data/unknown.type +0 -0
- data/spec/unit/railgun/content_type_spec.rb +71 -0
- data/spec/unit/railgun/mailer_spec.rb +242 -0
- data/vcr_cassettes/email_validation.yml +57 -9
- data/vcr_cassettes/events.yml +48 -1
- data/vcr_cassettes/suppressions.yml +727 -0
- metadata +68 -36
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
|
-
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: 64d4a0d5c1b85d58db90763fc5dbcd0f813f29bf30b328fdda6b7a019fbeb445
|
4
|
+
data.tar.gz: 2ddef97a1b88cd9d45c5e2d1b41df3b61e7b3a09a5dcbe4c3b0a62191335aeed
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 18df9ff784b8c39376420fcebe0b16a195318e63b70e6b6f5fb6139fd4cbd276ef1647844de6fd12c1e272906862ddfcdc85bb59ab29460dee6e0e02ec872ee8
|
7
|
+
data.tar.gz: 25547234506d03d471ea3f3bbfb46eb6c10e104147f6fc7cbe3b3228b966d31b5a3e53f423554c22f45360c119c5c015659b819559ef8d664c7c5ac47be09d00
|
data/.ruby-env.yml.example
CHANGED
@@ -7,6 +7,6 @@
|
|
7
7
|
# Replace <THESE_VALUES> with yours from
|
8
8
|
# https://mailgun.com/app/dashboard (don't include <brackets>)
|
9
9
|
# and rename to/save as: .ruby-env.yml
|
10
|
-
MAILGUN_APIKEY : '<MAILGUN_APIKEY'
|
10
|
+
MAILGUN_APIKEY : '<MAILGUN_APIKEY>'
|
11
11
|
MAILGUN_PUB_APIKEY : '<MAILGUN_PUBLIC_APIKEY>'
|
12
12
|
MAILGUN_TESTDOMAIN : '<MAILGUN_SANDBOX_DOMAIN>'
|
data/.travis.yml
CHANGED
@@ -1,21 +1,24 @@
|
|
1
1
|
language: ruby
|
2
2
|
sudo: false
|
3
3
|
rvm:
|
4
|
-
- 2.
|
5
|
-
- 2.2
|
6
|
-
- 2.
|
7
|
-
- 2.
|
4
|
+
- 2.2.2
|
5
|
+
- 2.2.10
|
6
|
+
- 2.3.7
|
7
|
+
- 2.4.4
|
8
|
+
- 2.5.1
|
8
9
|
script:
|
10
|
+
- bundle install
|
9
11
|
- bundle exec rake spec
|
10
12
|
- '[[ "${TRAVIS_PULL_REQUEST}" == "false" ]] && ( bundle exec rake spec:integration
|
11
13
|
) || ( echo "Testing PR - No integration tests available")'
|
12
14
|
deploy:
|
13
15
|
provider: rubygems
|
14
16
|
api_key:
|
15
|
-
secure:
|
17
|
+
secure: DoX3w48gRyhDM1o1OLvtWsTi8ehLIarIsErzg/UlNRoLacQt5l5UzwD+u6wqsCEr4+c2uAHNahafpnw/j1rPG3LBPIXOK5A0SYbjovlckutiAC0330Q4PHwOZb73AFN1DG5JTeg4/fguEjdsEBdZObF7mh5gBMBQtNjo1Fos+4w=
|
16
18
|
gemspec: mailgun.gemspec
|
17
19
|
on:
|
18
20
|
tags: true
|
21
|
+
condition: "$TRAVIS_RUBY_VERSION == 2.5.1"
|
19
22
|
notifications:
|
20
23
|
slack:
|
21
24
|
rooms:
|
data/Gemfile
CHANGED
data/README.md
CHANGED
@@ -19,7 +19,7 @@ gem install mailgun-ruby
|
|
19
19
|
Gemfile:
|
20
20
|
|
21
21
|
```ruby
|
22
|
-
gem 'mailgun-ruby', '~>1.
|
22
|
+
gem 'mailgun-ruby', '~>1.2.4'
|
23
23
|
```
|
24
24
|
|
25
25
|
Usage
|
@@ -27,6 +27,8 @@ Usage
|
|
27
27
|
Here's how to send a message using the library:
|
28
28
|
|
29
29
|
```ruby
|
30
|
+
require 'mailgun-ruby'
|
31
|
+
|
30
32
|
# First, instantiate the Mailgun Client with your API key
|
31
33
|
mg_client = Mailgun::Client.new 'your-api-key'
|
32
34
|
|
@@ -54,6 +56,12 @@ domain = 'example.com'
|
|
54
56
|
result = mg_client.get("#{domain}/events", {:event => 'delivered'})
|
55
57
|
```
|
56
58
|
|
59
|
+
If you're using the EU domains, make sure you specify it when creating the client:
|
60
|
+
|
61
|
+
```
|
62
|
+
mg_client = Mailgun::Client.new 'your-api-key', 'api.eu.mailgun.net'
|
63
|
+
```
|
64
|
+
|
57
65
|
Rails
|
58
66
|
-----
|
59
67
|
|
@@ -63,8 +71,41 @@ Mailgun.configure do |config|
|
|
63
71
|
config.api_key = 'your-secret-api-key'
|
64
72
|
end
|
65
73
|
```
|
66
|
-
Or have the initializer read your environment setting if you
|
74
|
+
Or have the initializer read your environment setting if you prefer.
|
75
|
+
|
76
|
+
To use as the ActionMailer delivery method, add this to your `config/environments/whatever.rb`
|
77
|
+
and replace `api-myapikey` and `mydomain.com` with your secret API key and domain, respectively:
|
78
|
+
```ruby
|
79
|
+
config.action_mailer.delivery_method = :mailgun
|
80
|
+
config.action_mailer.mailgun_settings = {
|
81
|
+
api_key: 'api-myapikey',
|
82
|
+
domain: 'mydomain.com',
|
83
|
+
# api_host: 'api.eu.mailgun.net' # Uncomment this line for EU region domains
|
84
|
+
}
|
85
|
+
```
|
67
86
|
|
87
|
+
To specify Mailgun options such as campaign or tags:
|
88
|
+
```ruby
|
89
|
+
class UserMailer < ApplicationMailer
|
90
|
+
def welcome_email
|
91
|
+
mail(to: params[:to], subject: "Welcome!").tap do |message|
|
92
|
+
message.mailgun_options = {
|
93
|
+
"tag" => ["abtest-option-a", "beta-user"],
|
94
|
+
"tracking-opens" => true,
|
95
|
+
"tracking-clicks" => "htmlonly"
|
96
|
+
}
|
97
|
+
end
|
98
|
+
end
|
99
|
+
end
|
100
|
+
```
|
101
|
+
|
102
|
+
To get the Mailgun `message_id` after ActionMailer has successfully delivered the email:
|
103
|
+
|
104
|
+
```ruby
|
105
|
+
mailer = UserNotifier.welcome_email(current_user)
|
106
|
+
mailer_response = mailer.deliver_now
|
107
|
+
mailgun_message_id = mailer_response.message_id
|
108
|
+
```
|
68
109
|
|
69
110
|
Response
|
70
111
|
--------
|
@@ -136,15 +177,17 @@ mg_client.send_message("sending_domain.com", message_params)
|
|
136
177
|
```
|
137
178
|
|
138
179
|
For usage examples on each API endpoint, head over to our official documentation
|
139
|
-
pages. Or the [Snippets](Snippets.md) file.
|
180
|
+
pages. Or the [Snippets](docs/Snippets.md) file.
|
140
181
|
|
141
182
|
This SDK includes the following components:
|
142
|
-
- [
|
143
|
-
- [
|
144
|
-
- [
|
145
|
-
- [
|
146
|
-
- [
|
147
|
-
- [
|
183
|
+
- [Messages](docs/Messages.md)
|
184
|
+
- [Message Builder](docs/MessageBuilder.md)
|
185
|
+
- [Batch Message](docs/MessageBuilder.md)
|
186
|
+
- [Opt-In Handler](docs/OptInHandler.md)
|
187
|
+
- [Domains](docs/Domains.md)
|
188
|
+
- [Webhooks](docs/Webhooks.md)
|
189
|
+
- [Events](docs/Events.md)
|
190
|
+
- [Suppressions](docs/Suppressions.md)
|
148
191
|
|
149
192
|
Message Builder allows you to quickly create the array of parameters, required
|
150
193
|
to send a message, by calling a methods for each parameter.
|
@@ -152,6 +195,31 @@ Batch Message is an extension of Message Builder, and allows you to easily send
|
|
152
195
|
a batch message job within a few seconds. The complexity of
|
153
196
|
batch messaging is eliminated!
|
154
197
|
|
198
|
+
Testing mail deliveries
|
199
|
+
----------------------
|
200
|
+
|
201
|
+
```ruby
|
202
|
+
# First, instantiate the Mailgun Client with your API key
|
203
|
+
mg_client = Mailgun::Client.new 'your-api-key'
|
204
|
+
|
205
|
+
# Put the client in test mode
|
206
|
+
mg_client.enable_test_mode!
|
207
|
+
|
208
|
+
# Define your message parameters
|
209
|
+
message_params = { from: 'bob@sending_domain.com',
|
210
|
+
to: 'sally@example.com',
|
211
|
+
subject: 'The Ruby SDK is awesome!',
|
212
|
+
text: 'It is really easy to send a message!'
|
213
|
+
}
|
214
|
+
|
215
|
+
# Send your message through the client
|
216
|
+
# Note: This will not actually hit the API, and will return a generic OK response.
|
217
|
+
mg_client.send_message('sending_domain.com', message_params)
|
218
|
+
|
219
|
+
# You can now access a copy of message_params
|
220
|
+
Mailgun::Client.deliveries.first[:from] # => 'bob@sending_domain.com'
|
221
|
+
```
|
222
|
+
|
155
223
|
Testing
|
156
224
|
-------
|
157
225
|
|
@@ -30,6 +30,24 @@ domainer.create 'my.new.moreness', { some: 'options' }
|
|
30
30
|
domainer.remove 'this.one.is.not.needed.'
|
31
31
|
```
|
32
32
|
|
33
|
+
Suppressions for a Domain
|
34
|
+
-------------------------
|
35
|
+
|
36
|
+
You can manage domain suppressions (bounces, unsubscribes, complaints) using the
|
37
|
+
[`Mailgun::Suppressions`](/docs/Suppressions.md) client:
|
38
|
+
|
39
|
+
```ruby
|
40
|
+
# Instantiate the Mailgun Client with your API key
|
41
|
+
mg_client = Mailgun::Client.new('your-api-key')
|
42
|
+
supp_client = mg_client.suppressions('example.org')
|
43
|
+
|
44
|
+
# ...
|
45
|
+
```
|
46
|
+
|
47
|
+
See the [Suppressions](/docs/Suppressions.md) for usage samples and
|
48
|
+
[suppressions.rb](/lib/mailgun/suppressions.rb) for suppressions client API.
|
49
|
+
|
50
|
+
|
33
51
|
More Documentation
|
34
52
|
------------------
|
35
53
|
See the official [Mailgun Domain Docs](https://documentation.mailgun.com/api-domains.html)
|
File without changes
|
@@ -24,28 +24,44 @@ mb_obj = Mailgun::MessageBuilder.new()
|
|
24
24
|
|
25
25
|
# Define the from address.
|
26
26
|
mb_obj.from("me@example.com", {"first"=>"Ruby", "last" => "SDK"});
|
27
|
+
|
27
28
|
# Define a to recipient.
|
28
29
|
mb_obj.add_recipient(:to, "john.doe@example.com", {"first" => "John", "last" => "Doe"});
|
30
|
+
|
29
31
|
# Define a cc recipient.
|
30
32
|
mb_obj.add_recipient(:cc, "sally.doe@example.com", {"first" => "Sally", "last" => "Doe"});
|
33
|
+
|
31
34
|
# Define the subject.
|
32
35
|
mb_obj.subject("A message from the Ruby SDK using Message Builder!");
|
36
|
+
|
33
37
|
# Define the body of the message.
|
34
38
|
mb_obj.body_text("This is the text body of the message!");
|
39
|
+
|
35
40
|
# Set the Message-Id header, provide a valid Message-Id.
|
36
41
|
mb_obj.message_id("<20141014000000.11111.11111@example.com>")
|
42
|
+
|
37
43
|
# Or clear the Message-Id header, provide nil or empty string.
|
38
44
|
mb_obj.message_id(nil)
|
39
45
|
mb_obj.message_id('')
|
40
|
-
|
46
|
+
|
47
|
+
# Set the Message-tags at most 3.
|
48
|
+
mb_obj.add_tag("You can track mails as tag-units!")
|
49
|
+
|
50
|
+
# Campaigns and headers.
|
41
51
|
mb_obj.add_campaign_id("My-Awesome-Campaign");
|
42
|
-
mb_obj.
|
52
|
+
mb_obj.header("Customer-Id", "12345");
|
53
|
+
|
54
|
+
# Custom variables
|
55
|
+
mb_obj.variable("Customer-Data", { :first_name => "John", :last_name => "Smith" })
|
43
56
|
|
44
57
|
# Attach a file and rename it.
|
45
|
-
mb_obj.add_attachment
|
58
|
+
mb_obj.add_attachment "/path/to/file/receipt_123491820.pdf", "Receipt.pdf"
|
59
|
+
|
60
|
+
# Attach an image inline.
|
61
|
+
mb_obj.add_inline_image "/path/to/file/header.png"
|
46
62
|
|
47
63
|
# Schedule message in the future
|
48
|
-
mb_obj.
|
64
|
+
mb_obj.deliver_at("tomorrow 8:00AM PST");
|
49
65
|
|
50
66
|
# Finally, send your message using the client
|
51
67
|
result = mg_client.send_message("sending_domain.com", mb_obj)
|
@@ -60,13 +76,16 @@ Here's how to use Batch Message to easily handle batch sending jobs.
|
|
60
76
|
```ruby
|
61
77
|
# First, instantiate the Mailgun Client with your API key
|
62
78
|
mg_client = Mailgun::Client.new("your-api-key")
|
79
|
+
|
63
80
|
# Create a Batch Message object, pass in the client and your domain.
|
64
81
|
mb_obj = Mailgun::BatchMessage.new(mg_client, "example.com")
|
65
82
|
|
66
83
|
# Define the from address.
|
67
|
-
mb_obj.from("me@example.com", {"first"=>"Ruby", "last" => "SDK"});
|
84
|
+
mb_obj.from("me@example.com", {"first" => "Ruby", "last" => "SDK"});
|
85
|
+
|
68
86
|
# Define the subject.
|
69
87
|
mb_obj.subject("A message from the Ruby SDK using Message Builder!");
|
88
|
+
|
70
89
|
# Define the body of the message.
|
71
90
|
mb_obj.body_text("This is the text body of the message!");
|
72
91
|
|
@@ -50,8 +50,8 @@ mb_obj.set_message_id('')
|
|
50
50
|
|
51
51
|
# Other Optional Parameters.
|
52
52
|
mb_obj.add_campaign_id("My-Awesome-Campaign")
|
53
|
-
mb_obj.
|
54
|
-
mb_obj.add_attachment("
|
53
|
+
mb_obj.header("Customer-Id", "12345")
|
54
|
+
mb_obj.add_attachment("./tron.jpg")
|
55
55
|
mb_obj.set_delivery_time("tomorrow 8:00AM PST")
|
56
56
|
mb_obj.set_click_tracking(true)
|
57
57
|
|
@@ -79,7 +79,7 @@ mb_obj.set_text_body("Hello %recipient.first%,
|
|
79
79
|
This is the text body of the message
|
80
80
|
using recipient variables!
|
81
81
|
If you need to include custom data,
|
82
|
-
you could do it like this: %account-id%.")
|
82
|
+
you could do it like this: %recipient.account-id%.")
|
83
83
|
|
84
84
|
mb_obj.add_recipient(:to, "john.doe@example.com", {"first" => "John",
|
85
85
|
"last" => "Doe",
|
File without changes
|
@@ -41,8 +41,7 @@ mg_client.send_message "sending_domain.com", data
|
|
41
41
|
|
42
42
|
```ruby
|
43
43
|
# Don't include a file, pull the file to a string
|
44
|
-
mime_string = '
|
45
|
-
From: Bob Sample <example@example.com>
|
44
|
+
mime_string = 'From: Bob Sample <example@example.com>
|
46
45
|
MIME-Version: 1.0
|
47
46
|
Content-Type: multipart/mixed;
|
48
47
|
boundary="--boundary-goes-here--"
|
@@ -76,6 +75,26 @@ mb_obj.set_text_body "This is the text body."
|
|
76
75
|
mg_client.send_message "sending_domain.com", mb_obj
|
77
76
|
```
|
78
77
|
|
78
|
+
**Build a message with attachments, part by part, with Message Builder:**
|
79
|
+
|
80
|
+
```ruby
|
81
|
+
mb_obj = Mailgun::MessageBuilder.new
|
82
|
+
|
83
|
+
mb_obj.set_from_address "sender@example.com", {'first' => 'Sending', 'last' => 'User'}
|
84
|
+
mb_obj.add_recipient :to, "recipient@example.com", {'first' => 'Recipient', 'last' => 'User'}
|
85
|
+
mb_obj.set_subject "This is the subject!"
|
86
|
+
mb_obj.set_text_body "This is the text body."
|
87
|
+
|
88
|
+
# Add separate attachments
|
89
|
+
mb_obj.add_attachment "/path/to/file/invoice_8675309.pdf", "Order Invoice - 8675309.pdf"
|
90
|
+
mb_obj.add_attachment "/path/to/file/datasheet_00001.pdf", "Product Datasheet - 00001.pdf"
|
91
|
+
|
92
|
+
# Attach inline image to message
|
93
|
+
mb_obj.add_inline_image "/path/to/file/product_image_00001.png"
|
94
|
+
|
95
|
+
mg_client.send_message "sending_domain.com", mb_obj
|
96
|
+
```
|
97
|
+
|
79
98
|
**Send batches of 1000 messages per post:**
|
80
99
|
|
81
100
|
```ruby
|
@@ -0,0 +1,82 @@
|
|
1
|
+
Mailgun - Suppressions
|
2
|
+
====================
|
3
|
+
|
4
|
+
This is the Mailgun Ruby *Suppressions* utilities.
|
5
|
+
|
6
|
+
The below assumes you've already installed the Mailgun Ruby SDK in to your
|
7
|
+
project. If not, go back to the master README for instructions. It currently supports
|
8
|
+
all calls except credentials.
|
9
|
+
|
10
|
+
----
|
11
|
+
|
12
|
+
The Suppressions client lets you manage bounces, unsubscribes, and complaints for a
|
13
|
+
single domain.
|
14
|
+
|
15
|
+
You can view additional samples in the [suppressions_spec.rb](/spec/integration/suppressions_spec.rb)
|
16
|
+
or the Suppressions client API in [suppressions.rb](/lib/mailgun/suppressions.rb).
|
17
|
+
|
18
|
+
|
19
|
+
Usage
|
20
|
+
-----
|
21
|
+
|
22
|
+
To get an instance of the Suppressions client:
|
23
|
+
|
24
|
+
```ruby
|
25
|
+
mg_client = Mailgun::Client.new('api_key')
|
26
|
+
supp_client = mg_client.suppressions('yourdomain.com')
|
27
|
+
```
|
28
|
+
|
29
|
+
----
|
30
|
+
|
31
|
+
To get a list of bounces, unsubscribes, and/or complaints:
|
32
|
+
|
33
|
+
```ruby
|
34
|
+
supp_client.list_bounces
|
35
|
+
supp_client.list_unsubscribes
|
36
|
+
supp_client.list_complaints
|
37
|
+
```
|
38
|
+
|
39
|
+
----
|
40
|
+
|
41
|
+
To batch-add a set of bounces:
|
42
|
+
|
43
|
+
```ruby
|
44
|
+
@addresses = <load or generate some addresses...>
|
45
|
+
|
46
|
+
bounces = []
|
47
|
+
@addresses.each do |addr|
|
48
|
+
bounces.push({
|
49
|
+
:address => addr,
|
50
|
+
:code => 500,
|
51
|
+
:error => 'some bounce because reasons',
|
52
|
+
})
|
53
|
+
end
|
54
|
+
|
55
|
+
response, addt_responses = @supp_client.create_bounces bounces
|
56
|
+
```
|
57
|
+
|
58
|
+
`create_bounces`, `create_unsubscribes`, and `create_complaints` will all
|
59
|
+
return two values - first, a simple `Mailgun::Response` object. Second,
|
60
|
+
a list containing any `Mailgun::Response` objects created recursively, if over 998
|
61
|
+
bounces were provided to `create_*`.
|
62
|
+
|
63
|
+
----
|
64
|
+
|
65
|
+
To delete bounces:
|
66
|
+
|
67
|
+
```ruby
|
68
|
+
@addresses = <load addresses...>
|
69
|
+
|
70
|
+
@addresses.each do |addr|
|
71
|
+
@supp_client.delete_bounce addr
|
72
|
+
end
|
73
|
+
```
|
74
|
+
|
75
|
+
Or, alternatively, to remove *all* bounces:
|
76
|
+
|
77
|
+
```ruby
|
78
|
+
@supp_client.delete_all_bounces
|
79
|
+
```
|
80
|
+
|
81
|
+
The `delete_*` methods are similar for `bounces`, `unsubscribe`, and `complaints` -
|
82
|
+
they all will return a `Mailgun::Response` object.
|
@@ -31,7 +31,7 @@ hook.create 'my.perfect.domain', 'deliver', 'https://the.webhook.url/'
|
|
31
31
|
hook.remove 'my.perfect.domain', 'deliver'
|
32
32
|
|
33
33
|
# Remove all webhooks for a domain
|
34
|
-
hook.
|
34
|
+
hook.remove_all 'my.perfect.domain'
|
35
35
|
```
|
36
36
|
|
37
37
|
More Documentation
|
@@ -0,0 +1,11 @@
|
|
1
|
+
Overview
|
2
|
+
========
|
3
|
+
|
4
|
+
Railgun is a Rails add-on that allows ActionMailer to send via the Mailgun API.
|
5
|
+
|
6
|
+
See [railgun-sample](https://github.com/pirogoeth/railgun-sample/) for examples of integrating Railgun with your Rails app.
|
7
|
+
|
8
|
+
|
9
|
+
## Table of Contents
|
10
|
+
|
11
|
+
- [Parameters](/docs/railgun/Parameters.md)
|
@@ -0,0 +1,83 @@
|
|
1
|
+
Parameters
|
2
|
+
==========
|
3
|
+
|
4
|
+
When sending messages via Railgun, it is often useful to set options, headers, and variables
|
5
|
+
that should be added to the `POST` request against the messages endpoint.
|
6
|
+
|
7
|
+
|
8
|
+
## Options
|
9
|
+
|
10
|
+
See [Mailgun Docs | Sending](https://documentation.mailgun.com/en/latest/api-sending.html#sending) for available options.
|
11
|
+
|
12
|
+
---
|
13
|
+
|
14
|
+
To set options on a message:
|
15
|
+
|
16
|
+
```ruby
|
17
|
+
# app/controllers/some_controller.rb
|
18
|
+
|
19
|
+
message = YourMailer.your_message(@args)
|
20
|
+
|
21
|
+
message.mailgun_options ||= {
|
22
|
+
"tracking-opens" => "true",
|
23
|
+
"tracking-clicks" => "htmlonly",
|
24
|
+
"tag" => "some,tags",
|
25
|
+
}
|
26
|
+
```
|
27
|
+
|
28
|
+
|
29
|
+
## Variables
|
30
|
+
|
31
|
+
See [Mailgun Docs | Attaching Data to Messages](https://documentation.mailgun.com/en/latest/user_manual.html#attaching-data-to-messages) for more information.
|
32
|
+
|
33
|
+
---
|
34
|
+
|
35
|
+
To set variables on a message:
|
36
|
+
|
37
|
+
```ruby
|
38
|
+
# app/controllers/some_controller.rb
|
39
|
+
|
40
|
+
message = YourMailer.your_message(@args)
|
41
|
+
|
42
|
+
message.mailgun_variables ||= {
|
43
|
+
"user_info" => {"id" => "1", "name" => "tstark"},
|
44
|
+
}
|
45
|
+
```
|
46
|
+
|
47
|
+
|
48
|
+
## Headers
|
49
|
+
|
50
|
+
See [Mailgun Docs | Sending](https://documentation.mailgun.com/en/latest/api-sending.html#sending) for more information.
|
51
|
+
|
52
|
+
---
|
53
|
+
|
54
|
+
To set headers on a message *from a controller*:
|
55
|
+
|
56
|
+
```ruby
|
57
|
+
# app/controllers/some_controller.rb
|
58
|
+
|
59
|
+
message = YourMailer.your_message(@args)
|
60
|
+
|
61
|
+
message.mailgun_headers ||= {
|
62
|
+
"X-Sent-From-Rails" => "true",
|
63
|
+
}
|
64
|
+
```
|
65
|
+
|
66
|
+
To set headers on a message *from a mailer*:
|
67
|
+
|
68
|
+
```ruby
|
69
|
+
# app/mailers/your_mailer.rb
|
70
|
+
|
71
|
+
class YourMailer < ApplicationMailer
|
72
|
+
# ...
|
73
|
+
|
74
|
+
def your_message(args)
|
75
|
+
headers({
|
76
|
+
"X-Sent-From-Rails" => "true",
|
77
|
+
})
|
78
|
+
|
79
|
+
mail to: "some-address@example.org", ...
|
80
|
+
end
|
81
|
+
|
82
|
+
end
|
83
|
+
```
|
data/lib/mailgun/address.rb
CHANGED
@@ -18,8 +18,11 @@ module Mailgun
|
|
18
18
|
# Given an arbitrary address, validates it based on defined checks.
|
19
19
|
#
|
20
20
|
# @param [String] address Email address to validate (max 512 chars.)
|
21
|
-
def validate(address)
|
22
|
-
|
21
|
+
def validate(address, mailbox_verification = false)
|
22
|
+
params = {:address => address}
|
23
|
+
params[:mailbox_verification] = true if mailbox_verification
|
24
|
+
|
25
|
+
res = @client.get "address/validate", params
|
23
26
|
return res.to_h!
|
24
27
|
end
|
25
28
|
|
data/lib/mailgun/client.rb
CHANGED
@@ -1,4 +1,5 @@
|
|
1
1
|
require 'mailgun/chains'
|
2
|
+
require 'mailgun/suppressions'
|
2
3
|
require 'mailgun/exceptions/exceptions'
|
3
4
|
|
4
5
|
module Mailgun
|
@@ -13,13 +14,18 @@ module Mailgun
|
|
13
14
|
api_host = 'api.mailgun.net',
|
14
15
|
api_version = 'v3',
|
15
16
|
ssl = true,
|
16
|
-
test_mode = false
|
17
|
+
test_mode = false,
|
18
|
+
timeout = nil)
|
19
|
+
|
20
|
+
rest_client_params = {
|
21
|
+
user: 'api',
|
22
|
+
password: api_key,
|
23
|
+
user_agent: "mailgun-sdk-ruby/#{Mailgun::VERSION}"
|
24
|
+
}
|
25
|
+
rest_client_params[:timeout] = timeout if timeout
|
17
26
|
|
18
27
|
endpoint = endpoint_generator(api_host, api_version, ssl)
|
19
|
-
@http_client = RestClient::Resource.new(endpoint,
|
20
|
-
user: 'api',
|
21
|
-
password: api_key,
|
22
|
-
user_agent: "mailgun-sdk-ruby/#{Mailgun::VERSION}")
|
28
|
+
@http_client = RestClient::Resource.new(endpoint, rest_client_params)
|
23
29
|
@test_mode = test_mode
|
24
30
|
end
|
25
31
|
|
@@ -44,6 +50,13 @@ module Mailgun
|
|
44
50
|
@test_mode
|
45
51
|
end
|
46
52
|
|
53
|
+
# Provides a store of all the emails sent in test mode so you can check them.
|
54
|
+
#
|
55
|
+
# @return [Hash]
|
56
|
+
def self.deliveries
|
57
|
+
@@deliveries ||= []
|
58
|
+
end
|
59
|
+
|
47
60
|
# Simple Message Sending
|
48
61
|
#
|
49
62
|
# @param [String] working_domain This is the domain you wish to send from.
|
@@ -51,7 +64,10 @@ module Mailgun
|
|
51
64
|
# containing required parameters for the requested resource.
|
52
65
|
# @return [Mailgun::Response] A Mailgun::Response object.
|
53
66
|
def send_message(working_domain, data)
|
67
|
+
fail ParameterError.new('Missing working domain', working_domain) unless working_domain
|
68
|
+
|
54
69
|
if test_mode? then
|
70
|
+
Mailgun::Client.deliveries << data
|
55
71
|
return Response.from_hash(
|
56
72
|
{
|
57
73
|
:body => '{"id": "test-mode-mail@localhost", "message": "Queued. Thank you."}',
|
@@ -62,6 +78,11 @@ module Mailgun
|
|
62
78
|
|
63
79
|
case data
|
64
80
|
when Hash
|
81
|
+
# Remove nil values from the data hash
|
82
|
+
# Submitting nils to the API will likely cause an error.
|
83
|
+
# See also: https://github.com/mailgun/mailgun-ruby/issues/32
|
84
|
+
data = data.select { |k, v| v != nil }
|
85
|
+
|
65
86
|
if data.key?(:message)
|
66
87
|
if data[:message].is_a?(String)
|
67
88
|
data[:message] = convert_string_to_file(data[:message])
|
@@ -82,9 +103,10 @@ module Mailgun
|
|
82
103
|
# with. Be sure to include your domain, where necessary.
|
83
104
|
# @param [Hash] data This should be a standard Hash
|
84
105
|
# containing required parameters for the requested resource.
|
106
|
+
# @param [Hash] headers Additional headers to pass to the resource.
|
85
107
|
# @return [Mailgun::Response] A Mailgun::Response object.
|
86
|
-
def post(resource_path, data)
|
87
|
-
response = @http_client[resource_path].post(data)
|
108
|
+
def post(resource_path, data, headers = {})
|
109
|
+
response = @http_client[resource_path].post(data, headers)
|
88
110
|
Response.new(response)
|
89
111
|
rescue => err
|
90
112
|
raise communication_error err
|
@@ -94,8 +116,9 @@ module Mailgun
|
|
94
116
|
#
|
95
117
|
# @param [String] resource_path This is the API resource you wish to interact
|
96
118
|
# with. Be sure to include your domain, where necessary.
|
97
|
-
# @param [Hash]
|
119
|
+
# @param [Hash] params This should be a standard Hash
|
98
120
|
# containing required parameters for the requested resource.
|
121
|
+
# @param [String] accept Acceptable Content-Type of the response body.
|
99
122
|
# @return [Mailgun::Response] A Mailgun::Response object.
|
100
123
|
def get(resource_path, params = nil, accept = '*/*')
|
101
124
|
if params
|
@@ -134,6 +157,14 @@ module Mailgun
|
|
134
157
|
raise communication_error err
|
135
158
|
end
|
136
159
|
|
160
|
+
# Constructs a Suppressions client for the given domain.
|
161
|
+
#
|
162
|
+
# @param [String] domain Domain which suppressions requests will be made for
|
163
|
+
# @return [Mailgun::Suppressions]
|
164
|
+
def suppressions(domain)
|
165
|
+
Suppressions.new(self, domain)
|
166
|
+
end
|
167
|
+
|
137
168
|
private
|
138
169
|
|
139
170
|
# Converts MIME string to file for easy uploading to API
|