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.
Files changed (46) hide show
  1. checksums.yaml +5 -5
  2. data/.ruby-env.yml.example +1 -1
  3. data/.travis.yml +8 -5
  4. data/Gemfile +1 -1
  5. data/README.md +77 -9
  6. data/{Domains.md → docs/Domains.md} +18 -0
  7. data/{Events.md → docs/Events.md} +0 -0
  8. data/{MessageBuilder.md → docs/MessageBuilder.md} +24 -5
  9. data/{Messages.md → docs/Messages.md} +3 -3
  10. data/{OptInHandler.md → docs/OptInHandler.md} +0 -0
  11. data/{Snippets.md → docs/Snippets.md} +21 -2
  12. data/docs/Suppressions.md +82 -0
  13. data/{Webhooks.md → docs/Webhooks.md} +1 -1
  14. data/docs/railgun/Overview.md +11 -0
  15. data/docs/railgun/Parameters.md +83 -0
  16. data/lib/mailgun/address.rb +5 -2
  17. data/lib/mailgun/client.rb +39 -8
  18. data/lib/mailgun/events/events.rb +40 -12
  19. data/lib/mailgun/messages/batch_message.rb +3 -2
  20. data/lib/mailgun/messages/message_builder.rb +99 -26
  21. data/lib/mailgun/suppressions.rb +273 -0
  22. data/lib/mailgun/version.rb +1 -1
  23. data/lib/mailgun/webhooks/webhooks.rb +1 -1
  24. data/lib/mailgun-ruby.rb +2 -1
  25. data/lib/railgun/attachment.rb +56 -0
  26. data/lib/railgun/errors.rb +27 -0
  27. data/lib/railgun/mailer.rb +237 -0
  28. data/lib/railgun/message.rb +17 -0
  29. data/lib/railgun/railtie.rb +10 -0
  30. data/lib/railgun.rb +8 -0
  31. data/mailgun.gemspec +12 -12
  32. data/spec/integration/email_validation_spec.rb +14 -0
  33. data/spec/integration/events_spec.rb +9 -1
  34. data/spec/integration/mailgun_spec.rb +0 -0
  35. data/spec/integration/suppressions_spec.rb +142 -0
  36. data/spec/spec_helper.rb +3 -1
  37. data/spec/unit/events/events_spec.rb +36 -2
  38. data/spec/unit/messages/batch_message_spec.rb +1 -0
  39. data/spec/unit/messages/message_builder_spec.rb +95 -19
  40. data/spec/unit/messages/sample_data/unknown.type +0 -0
  41. data/spec/unit/railgun/content_type_spec.rb +71 -0
  42. data/spec/unit/railgun/mailer_spec.rb +242 -0
  43. data/vcr_cassettes/email_validation.yml +57 -9
  44. data/vcr_cassettes/events.yml +48 -1
  45. data/vcr_cassettes/suppressions.yml +727 -0
  46. metadata +68 -36
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 7191c12a6dc2a08445f7cb623f10608e9208c9d2
4
- data.tar.gz: 5033b5cd5eb92f6ce5c2d678222f8c7d9d118c78
2
+ SHA256:
3
+ metadata.gz: 64d4a0d5c1b85d58db90763fc5dbcd0f813f29bf30b328fdda6b7a019fbeb445
4
+ data.tar.gz: 2ddef97a1b88cd9d45c5e2d1b41df3b61e7b3a09a5dcbe4c3b0a62191335aeed
5
5
  SHA512:
6
- metadata.gz: 38dd19ded277a5566d738c88368b811607762ee258eaca48f7f1afe069b6fd84672bef1e6fb9637b028c06762c840dbd84b7a722ec2e6b7bd51828f99eedd406
7
- data.tar.gz: a87aab066601ca346f897d551ff37165b862654d378c156df84b9443714c0795b9bb7299e16e0bce5666511d28900b0d0d7677ffe7ff826b2681d1d9c96ea7cc
6
+ metadata.gz: 18df9ff784b8c39376420fcebe0b16a195318e63b70e6b6f5fb6139fd4cbd276ef1647844de6fd12c1e272906862ddfcdc85bb59ab29460dee6e0e02ec872ee8
7
+ data.tar.gz: 25547234506d03d471ea3f3bbfb46eb6c10e104147f6fc7cbe3b3228b966d31b5a3e53f423554c22f45360c119c5c015659b819559ef8d664c7c5ac47be09d00
@@ -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.3.1
5
- - 2.2
6
- - 2.1
7
- - 2.0.0
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: QTNP+6720w38b8krtvXM25WDEOUxw9BlUwdXgWLrU0MGAOSvVFgnWTJs+7QvGWODjhrIqAfAm11zc+yEpzgD9P8np9cteWv5K7rMxsUMcb14kaGIA+MKO+RRJXlru4teBNX5jtp2GJiNS2mn7urzn5YhE9x9P7pMjcF+j5usoF0=
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
@@ -3,4 +3,4 @@ source 'https://rubygems.org'
3
3
  # Specify your gem's dependencies in mailgun.gemspec
4
4
  gemspec
5
5
 
6
- gem 'json', '~> 1.8', platform: :mri_19
6
+ gem 'json', '~> 2.1', platform: :mri_19
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.1.2'
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 perfer.
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
- - [Message Builder](Messages.md)
143
- - [Batch Message](Messages.md)
144
- - [Opt-In Handler](OptInHandler.md)
145
- - [Domains](Domains.md)
146
- - [Webhooks](Webhooks.md)
147
- - [Events](Events.md)
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
- # Campaign and other headers.
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.add_custom_parameter("h:Customer-Id", "12345");
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("/path/to/file/receipt_123491820.pdf", "Receipt.pdf");
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.delivery_at("tomorrow 8:00AM PST");
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.add_custom_parameter("h:Customer-Id", "12345")
54
- mb_obj.add_attachment("@/tron.jpg")
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.remove 'my.perfect.domain'
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
+ ```
@@ -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
- res = @client.get "address/validate", {:address => address}
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
 
@@ -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] query_string This should be a standard 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