mailgun-ruby 1.1.0 → 1.2.5

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 (57) hide show
  1. checksums.yaml +5 -5
  2. data/.gitignore +1 -0
  3. data/.ruby-env.yml.example +1 -1
  4. data/.travis.yml +23 -7
  5. data/Gemfile +2 -0
  6. data/README.md +79 -18
  7. data/{Domains.md → docs/Domains.md} +18 -0
  8. data/{Events.md → docs/Events.md} +0 -0
  9. data/{MessageBuilder.md → docs/MessageBuilder.md} +32 -13
  10. data/{Messages.md → docs/Messages.md} +3 -3
  11. data/{OptInHandler.md → docs/OptInHandler.md} +0 -0
  12. data/{Snippets.md → docs/Snippets.md} +21 -2
  13. data/docs/Suppressions.md +82 -0
  14. data/{Webhooks.md → docs/Webhooks.md} +1 -1
  15. data/docs/railgun/Overview.md +11 -0
  16. data/docs/railgun/Parameters.md +83 -0
  17. data/lib/mailgun/address.rb +48 -0
  18. data/lib/mailgun/client.rb +85 -8
  19. data/lib/mailgun/events/events.rb +40 -12
  20. data/lib/mailgun/exceptions/exceptions.rb +21 -7
  21. data/lib/mailgun/lists/opt_in_handler.rb +0 -1
  22. data/lib/mailgun/messages/batch_message.rb +3 -2
  23. data/lib/mailgun/messages/message_builder.rb +139 -30
  24. data/lib/mailgun/response.rb +7 -0
  25. data/lib/mailgun/suppressions.rb +273 -0
  26. data/lib/mailgun/version.rb +1 -1
  27. data/lib/mailgun/webhooks/webhooks.rb +1 -1
  28. data/lib/mailgun-ruby.rb +2 -0
  29. data/lib/mailgun.rb +1 -0
  30. data/lib/railgun/attachment.rb +56 -0
  31. data/lib/railgun/errors.rb +27 -0
  32. data/lib/railgun/mailer.rb +253 -0
  33. data/lib/railgun/message.rb +18 -0
  34. data/lib/railgun/railtie.rb +10 -0
  35. data/lib/railgun.rb +8 -0
  36. data/mailgun.gemspec +12 -13
  37. data/spec/integration/email_validation_spec.rb +57 -15
  38. data/spec/integration/events_spec.rb +9 -1
  39. data/spec/integration/mailer_spec.rb +67 -0
  40. data/spec/integration/mailgun_spec.rb +51 -1
  41. data/spec/integration/suppressions_spec.rb +142 -0
  42. data/spec/spec_helper.rb +3 -1
  43. data/spec/unit/connection/test_client.rb +16 -0
  44. data/spec/unit/events/events_spec.rb +36 -2
  45. data/spec/unit/mailgun_spec.rb +32 -10
  46. data/spec/unit/messages/batch_message_spec.rb +56 -40
  47. data/spec/unit/messages/message_builder_spec.rb +267 -81
  48. data/spec/unit/messages/sample_data/unknown.type +0 -0
  49. data/spec/unit/railgun/content_type_spec.rb +71 -0
  50. data/spec/unit/railgun/mailer_spec.rb +388 -0
  51. data/vcr_cassettes/email_validation.yml +136 -25
  52. data/vcr_cassettes/events.yml +48 -1
  53. data/vcr_cassettes/exceptions.yml +45 -0
  54. data/vcr_cassettes/mailer_invalid_domain.yml +109 -0
  55. data/vcr_cassettes/message_deliver.yml +149 -0
  56. data/vcr_cassettes/suppressions.yml +727 -0
  57. metadata +65 -40
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 15c6226ce2745501543bd148db41a0297f2d58df
4
- data.tar.gz: 2110bec8de2f21d49fee5d56ad41aef0d4fbc2b7
2
+ SHA256:
3
+ metadata.gz: eeb68d33e0686c3074e829fa7c33c1a9300c31bd9db3b7fde74abfdbdd681a31
4
+ data.tar.gz: dc0cd7912abb804476731ba487186a362595f7806d88f50bbbe2296da8eb0b5b
5
5
  SHA512:
6
- metadata.gz: 04f6a82d67c5d8cda08c7a38956edfab2ff28b9c16b9344fcee2e3ec3caf1e0e69f901797de3a98640a962af9c28fff58d7151deb3cffbc32bee740df48eb901
7
- data.tar.gz: 4fc8aec4b0e5e5c100a707c3cf44151b9eb2fe1e1cd047bf0df3c0122c1443c9264e048d27fe65390e23a9718be2ce5ab8d6009deaaf7ec0f512e9a7217f3552
6
+ metadata.gz: 9469121fbdd8341af7cc6ee395d35d8f487f556b67d8b6a0d2b6cd874f4bb1828384f9aff7c6751377fa56182b7c890947e40444f09d583d97aca8f90c41c642
7
+ data.tar.gz: 2f2b70e53e187c28ea3fcf3d3abc3f208886baca01732af0bb233c154bd171565790279620fe392259f3fa74151276d4e281389606d35ce60047b6f9a922a7cf
data/.gitignore CHANGED
@@ -20,3 +20,4 @@ test.rb
20
20
  ruby
21
21
  .ruby-env.yml
22
22
  .rspec-local
23
+ .tool-versions
@@ -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,9 +1,25 @@
1
1
  language: ruby
2
- rvm:
3
- - 2.2
4
- - 2.1
5
- - 2.0.0
6
- - 1.9.3
7
2
  sudo: false
8
- gemfile: Gemfile
9
- script: bundle exec rake spec
3
+ rvm:
4
+ - 2.2.2
5
+ - 2.2.10
6
+ - 2.3.7
7
+ - 2.4.4
8
+ - 2.5.1
9
+ script:
10
+ - bundle install
11
+ - bundle exec rake spec
12
+ - '[[ "${TRAVIS_PULL_REQUEST}" == "false" ]] && ( bundle exec rake spec:integration
13
+ ) || ( echo "Testing PR - No integration tests available")'
14
+ deploy:
15
+ provider: rubygems
16
+ api_key:
17
+ secure: DoX3w48gRyhDM1o1OLvtWsTi8ehLIarIsErzg/UlNRoLacQt5l5UzwD+u6wqsCEr4+c2uAHNahafpnw/j1rPG3LBPIXOK5A0SYbjovlckutiAC0330Q4PHwOZb73AFN1DG5JTeg4/fguEjdsEBdZObF7mh5gBMBQtNjo1Fos+4w=
18
+ gemspec: mailgun.gemspec
19
+ on:
20
+ tags: true
21
+ condition: "$TRAVIS_RUBY_VERSION == 2.5.1"
22
+ notifications:
23
+ slack:
24
+ rooms:
25
+ secure: G4iBtDfFGeryQslfrKZK4hSPikOy9y3SDnpzwmN8SoB0uIAWE2mLfMUJZonKm7yoz+DbPU0u3c1SwiMLwHkXZhPdnJdC1fb1DpicXnVgGZYdiLGiY+OAwkvcBE9p3piWhpwigTjvmSqTaNSRL/VLhG4qwQbHU0fTl1M1zwU4e6c=
data/Gemfile CHANGED
@@ -2,3 +2,5 @@ source 'https://rubygems.org'
2
2
 
3
3
  # Specify your gem's dependencies in mailgun.gemspec
4
4
  gemspec
5
+
6
+ gem 'json', '~> 2.1', platform: :mri_19
data/README.md CHANGED
@@ -19,14 +19,7 @@ gem install mailgun-ruby
19
19
  Gemfile:
20
20
 
21
21
  ```ruby
22
- gem 'mailgun-ruby', '~>1.0.5', require: 'mailgun'
23
- ```
24
-
25
- Include
26
- --------
27
-
28
- ```ruby
29
- require 'mailgun'
22
+ gem 'mailgun-ruby', '~>1.2.5'
30
23
  ```
31
24
 
32
25
  Usage
@@ -34,6 +27,8 @@ Usage
34
27
  Here's how to send a message using the library:
35
28
 
36
29
  ```ruby
30
+ require 'mailgun-ruby'
31
+
37
32
  # First, instantiate the Mailgun Client with your API key
38
33
  mg_client = Mailgun::Client.new 'your-api-key'
39
34
 
@@ -52,7 +47,7 @@ Or obtain the last couple log items:
52
47
 
53
48
  ```ruby
54
49
  # First, instantiate the Mailgun Client with your API key
55
- mg_client = Mailgun::Client.new 'your-api-key'
50
+ mg_client = Mailgun::Client.new 'your-secret-api-key'
56
51
 
57
52
  # Define the domain you wish to query
58
53
  domain = 'example.com'
@@ -61,17 +56,56 @@ domain = 'example.com'
61
56
  result = mg_client.get("#{domain}/events", {:event => 'delivered'})
62
57
  ```
63
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
+
64
65
  Rails
65
66
  -----
66
67
 
67
68
  The library can be initialized with a Rails initializer containing similar:
68
69
  ```ruby
69
70
  Mailgun.configure do |config|
70
- config.api_key = 'your-secret-key'
71
+ config.api_key = 'your-secret-api-key'
71
72
  end
72
73
  ```
73
- Or have the initializer read your environment setting if you perfer.
74
+ Or have the initializer read your environment setting if you prefer.
74
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
+ ```
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
+ ```
75
109
 
76
110
  Response
77
111
  --------
@@ -143,15 +177,17 @@ mg_client.send_message("sending_domain.com", message_params)
143
177
  ```
144
178
 
145
179
  For usage examples on each API endpoint, head over to our official documentation
146
- pages. Or the [Snippets](Snippets.md) file.
180
+ pages. Or the [Snippets](docs/Snippets.md) file.
147
181
 
148
182
  This SDK includes the following components:
149
- - [Message Builder](Messages.md)
150
- - [Batch Message](Messages.md)
151
- - [Opt-In Handler](OptInHandler.md)
152
- - [Domains](Domains.md)
153
- - [Webhooks](Webhooks.md)
154
- - [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)
155
191
 
156
192
  Message Builder allows you to quickly create the array of parameters, required
157
193
  to send a message, by calling a methods for each parameter.
@@ -159,6 +195,31 @@ Batch Message is an extension of Message Builder, and allows you to easily send
159
195
  a batch message job within a few seconds. The complexity of
160
196
  batch messaging is eliminated!
161
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
+
162
223
  Testing
163
224
  -------
164
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
@@ -23,29 +23,45 @@ mg_client = Mailgun::Client.new("your-api-key")
23
23
  mb_obj = Mailgun::MessageBuilder.new()
24
24
 
25
25
  # Define the from address.
26
- mb_obj.set_from_address("me@example.com", {"first"=>"Ruby", "last" => "SDK"});
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
- mb_obj.set_subject("A message from the Ruby SDK using Message Builder!");
35
+ mb_obj.subject("A message from the Ruby SDK using Message Builder!");
36
+
33
37
  # Define the body of the message.
34
- mb_obj.set_text_body("This is the text body of the message!");
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
- mb_obj.set_message_id("<20141014000000.11111.11111@example.com>")
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
- mb_obj.set_message_id(nil)
39
- mb_obj.set_message_id('')
40
- # Campaign and other headers.
44
+ mb_obj.message_id(nil)
45
+ mb_obj.message_id('')
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.set_delivery_time("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,15 +76,18 @@ 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.set_from_address("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
- mb_obj.set_subject("A message from the Ruby SDK using Message Builder!");
87
+ mb_obj.subject("A message from the Ruby SDK using Message Builder!");
88
+
70
89
  # Define the body of the message.
71
- mb_obj.set_text_body("This is the text body of the message!");
90
+ mb_obj.body_text("This is the text body of the message!");
72
91
 
73
92
 
74
93
  # Loop through all of your recipients
@@ -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
+ ```
@@ -0,0 +1,48 @@
1
+ require 'mailgun/exceptions/exceptions'
2
+
3
+ module Mailgun
4
+
5
+ # Mailgun::Address is a simple interface to the Email Validation API.
6
+ class Address
7
+
8
+ # @param [String] api_key Mailgun API - public key
9
+ def initialize(api_key = "")
10
+ if api_key == "" then
11
+ fail ParameterError.new('Public API key is required for Mailgun::Address.initialize()', nil)
12
+ end
13
+
14
+ @api_key = api_key
15
+ @client = Mailgun::Client.new(api_key = api_key)
16
+ end
17
+
18
+ # Given an arbitrary address, validates it based on defined checks.
19
+ #
20
+ # @param [String] address Email address to validate (max 512 chars.)
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
26
+ return res.to_h!
27
+ end
28
+
29
+ # Parses a delimiter separated list of email addresses into two lists:
30
+ # parsed addresses and unparsable portions. The parsed addresses are a
31
+ # list of addresses that are syntactically valid (and optionally have
32
+ # DNS and ESP specific grammar checks) the unparsable list is a list
33
+ # of characters sequences that the parser was not able to understand.
34
+ # These often align with invalid email addresses, but not always.
35
+ # Delimiter characters are comma (,) and semicolon (;).
36
+ #
37
+ # @param [Array] addresses Addresses to parse
38
+ # @param [TrueClass|FalseClass] syntax_only Perform only syntax checks
39
+ def parse(addresses, syntax_only = true)
40
+ validate_addrs = addresses.join(";")
41
+
42
+ res = @client.get "address/parse", {:addresses => validate_addrs,
43
+ :syntax_only => syntax_only.to_s}
44
+ return res.to_h!
45
+ end
46
+ end
47
+
48
+ end