mailgun-ruby 1.4.3 → 1.4.5

data/spec/integration/webhook_spec.rb

@@ -6,55 +6,74 @@ require 'mailgun'
 vcr_opts = { cassette_name: 'webhooks' }
 
 describe 'For the webhooks endpoint', order: :defined, vcr: vcr_opts do
-  before(:all) do
-    @mg_obj = Mailgun::Client.new(APIKEY, APIHOST, APIVERSION, SSL)
-    @domain = 'DOMAIN.TEST'
-    @testhook = 'accepted'
-    @testhookup = 'accepted'
-  end
+  let(:api_version) { 'v3' }
+  let(:mg_client) { Mailgun::Client.new(APIKEY, APIHOST, api_version, SSL) }
+  let(:mg_obj) { Mailgun::Webhooks.new(mg_client) }
+  let(:domain) { 'DOMAIN.TEST' }
+  let(:testhook) { 'accepted' }
+  let(:testhookup) { 'accepted' }
 
   it 'creates a webhook' do
-    result = @mg_obj.post("domains/#{@domain}/webhooks", { id: @testhook,
-                                                           url: "http://example.com/mailgun/events/#{@testhook}" })
+    result = mg_obj.create(domain, testhook, "http://example.com/mailgun/events/#{testhook}")
 
-    result.to_h!
-    expect(result.body['message']).to eq('Webhook has been created')
-    expect(result.body['webhook']['urls']).to include("http://example.com/mailgun/events/#{@testhook}")
+    expect(result).to be_truthy
   end
 
-  it 'gets a webhook.' do
-    result = @mg_obj.get("domains/#{@domain}/webhooks/#{@testhook}")
+  it 'gets a webhook' do
+    result = mg_obj.get(domain, testhook)
 
-    result.to_h!
-    expect(result.body['webhook']['urls']).to include("http://example.com/mailgun/events/#{@testhook}")
+    expect(result).to include("http://example.com/mailgun/events/#{testhook}")
   end
 
-  it 'gets a list of all webhooks.' do
-    result = @mg_obj.get("domains/#{@domain}/webhooks")
+  it 'gets a list of all webhooks' do
+    result = mg_obj.list(domain)
 
-    result.to_h!
-    expect(result.body['webhooks']['accepted']['urls']).to include("http://example.com/mailgun/events/#{@testhook}")
+    expect(result['accepted']['urls'][0]).to include("http://example.com/mailgun/events/#{testhook}")
   end
 
-  it 'updates a webhook.' do
-    result = @mg_obj.put(
-      "domains/#{@domain}/webhooks/#{@testhook}",
-      {
-        id: @testhook,
-        url: "http://example.com/mailgun/events/#{@testhookup}"
-      }
-    )
+  it 'updates a webhook' do
+    result = mg_obj.update(domain, testhook, "http://example.com/mailgun/events/#{testhookup}")
 
-    result.to_h!
-    expect(result.body['message']).to eq('Webhook has been updated')
-    expect(result.body['webhook']['urls']).to include("http://example.com/mailgun/events/#{@testhookup}")
+    expect(result).to be_truthy
   end
 
   it 'removes a webhook' do
-    result = @mg_obj.delete("domains/#{@domain}/webhooks/#{@testhook}")
+    result = mg_obj.remove(domain, testhook)
+
+    expect(result).to be_truthy
+  end
+end
+
+describe 'For the v4 webhooks endpoint', vcr: { cassette_name: 'webhooks_v4' } do
+  let(:mg_client) { Mailgun::Client.new(APIKEY, APIHOST, 'v4', SSL) }
+  let(:mg_obj) { Mailgun::Webhooks.new(mg_client) }
+  let(:domain) { 'DOMAIN.TEST' }
+  let(:url) { 'http://example.com/mailgun/events/v4' }
+
+  describe '#create_v4' do
+    it 'creates webhooks for multiple event types' do
+      result = mg_obj.create_v4(domain, url: url, event_types: %w[accepted delivered])
+
+      expect(result.keys).to contain_exactly('accepted', 'delivered')
+      expect(result['accepted']['urls']).to include(url)
+      expect(result['delivered']['urls']).to include(url)
+    end
+  end
+
+  describe '#update_v4' do
+    it 'replaces the event types associated with a url' do
+      result = mg_obj.update_v4(domain, url: url, event_types: %w[clicked opened])
+
+      expect(result.keys).to contain_exactly('clicked', 'opened')
+      expect(result['clicked']['urls']).to include(url)
+    end
+  end
+
+  describe '#remove_v4' do
+    it 'removes the urls from all event types' do
+      result = mg_obj.remove_v4(domain, url: [url, 'http://example.com/mailgun/events/v4-other'])
 
-    result.to_h!
-    expect(result.body['message']).to eq('Webhook has been deleted')
-    expect(result.body['webhook']['urls']).to include("http://example.com/mailgun/events/#{@testhookup}")
+      expect(result).to eq({})
+    end
   end
 end

data/spec/spec_helper.rb

@@ -17,6 +17,8 @@ require 'mailgun'
 
 require 'vcr'
 require 'webmock/rspec'
+# Keep repeated query keys (e.g. ?url=a&url=b) instead of collapsing them to the last value
+WebMock::Config.instance.query_values_notation = :flat_array
 require 'rspec/its'
 
 # WebMock.disable_net_connect!(allow_localhost: true)
@@ -43,6 +45,7 @@ VCR.configure do |c|
   c.hook_into :webmock
   c.default_cassette_options = { record: :new_episodes }
   c.filter_sensitive_data('<APIKEY>') { APIKEY }
+  c.filter_sensitive_data('<BASIC_AUTH>') { ["api:#{APIKEY}"].pack('m0') } if APIKEY
   c.filter_sensitive_data('DOMAIN.TEST') { TESTDOMAIN }
   c.filter_sensitive_data('<PUBKEY>') { PUB_APIKEY }
 

data/spec/unit/client_spec.rb

@@ -54,6 +54,30 @@ describe Mailgun::Client do
     it 'supports EU api host' do
       expect { described_class.new(api_key, 'api.eu.mailgun.net') }.not_to raise_error
     end
+
+    context 'when test_mode is not passed' do
+      around do |example|
+        original = Mailgun.test_mode
+        example.run
+      ensure
+        Mailgun.test_mode = original
+      end
+
+      it 'enables test mode when Mailgun.test_mode is true' do
+        Mailgun.test_mode = true
+        expect(described_class.new(api_key).test_mode?).to be(true)
+      end
+
+      it 'disables test mode when Mailgun.test_mode is false' do
+        Mailgun.test_mode = false
+        expect(described_class.new(api_key).test_mode?).to be(false)
+      end
+
+      it 'disables test mode when Mailgun.test_mode is not set' do
+        Mailgun.test_mode = nil
+        expect(described_class.new(api_key).test_mode?).to be(false)
+      end
+    end
   end
 
   # ---------------------------------------------------------------------------

data/spec/unit/webhooks_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Mailgun::Webhooks do
+  let(:client) { double(:client) }
+  let(:webhooks) { described_class.new(client) }
+  let(:domain) { 'example.com' }
+  let(:url) { 'https://example.com/mailgun/events' }
+
+  %i[create_all add_all_webhooks].each do |method|
+    describe "##{method}" do
+      it 'creates every webhook action with the provided URL' do
+        described_class::ACTIONS.each do |action|
+          expect(webhooks).to receive(:create).with(domain, action, url).ordered
+        end
+
+        expect { webhooks.public_send(method, domain, url) }
+          .to output(/`#{method}` method will be deprecated/).to_stderr
+      end
+    end
+  end
+
+  context 'with v3 endpoints' do
+    let(:client) { instance_double(Mailgun::Client, api_version: 'v3') }
+
+    describe '#create' do
+      let(:urls) { [url, 'https://example.com/other'] }
+      let(:response) do
+        instance_double(Mailgun::Response,
+                        to_h: { 'message' => 'Webhook has been created', 'webhook' => { 'urls' => urls } })
+      end
+
+      before { allow(client).to receive(:post).and_return(response) }
+
+      it 'returns true when a single url was created' do
+        expect(webhooks.create(domain, 'delivered', url)).to be(true)
+      end
+
+      it 'returns true when multiple urls were created' do
+        expect(webhooks.create(domain, 'delivered', urls)).to be(true)
+      end
+
+      it 'returns false when a url is missing from the response' do
+        expect(webhooks.create(domain, 'delivered', [url, 'https://example.com/missing'])).to be(false)
+      end
+    end
+
+    describe 'parameter validation' do
+      it 'raises a ParameterError when the domain is missing' do
+        [nil, ''].each do |blank|
+          expect { webhooks.update(blank, 'delivered', url) }
+            .to raise_error(Mailgun::ParameterError, 'Domain not provided to update webhooks')
+          expect { webhooks.remove(blank, 'delivered') }
+            .to raise_error(Mailgun::ParameterError, 'Domain not provided to remove webhook from')
+        end
+      end
+
+      it 'raises a ParameterError when the action is missing' do
+        [nil, ''].each do |blank|
+          expect { webhooks.update(domain, blank, url) }
+            .to raise_error(Mailgun::ParameterError, 'Action not provided to identify webhook to update')
+          expect { webhooks.remove(domain, blank) }
+            .to raise_error(Mailgun::ParameterError, 'Action not provided to identify webhook to remove')
+        end
+      end
+    end
+  end
+
+  context 'with v4 endpoints' do
+    let(:api_version) { 'v4' }
+    let(:client) { instance_double(Mailgun::Client, api_version: api_version) }
+    let(:response) { instance_double(Mailgun::Response, to_h: { 'webhooks' => { 'accepted' => { 'urls' => [url] } } }) }
+
+    describe '#create_v4' do
+      it 'posts the url and event types to the domain webhooks endpoint' do
+        expect(client).to receive(:post)
+          .with("domains/#{domain}/webhooks", { url: url, event_types: %w[accepted delivered] })
+          .and_return(response)
+
+        expect(webhooks.create_v4(domain, url: url, event_types: %w[accepted delivered]))
+          .to eq('accepted' => { 'urls' => [url] })
+      end
+    end
+
+    describe '#update_v4' do
+      it 'puts the url and event types to the domain webhooks endpoint' do
+        expect(client).to receive(:put)
+          .with("domains/#{domain}/webhooks", { url: url, event_types: 'accepted' })
+          .and_return(response)
+
+        expect(webhooks.update_v4(domain, url: url, event_types: 'accepted'))
+          .to eq('accepted' => { 'urls' => [url] })
+      end
+    end
+
+    describe '#remove_v4' do
+      it 'sends the urls as query params' do
+        urls = [url, 'https://example.com/other']
+        expect(client).to receive(:delete)
+          .with("domains/#{domain}/webhooks", { url: urls })
+          .and_return(response)
+
+        webhooks.remove_v4(domain, url: urls)
+      end
+    end
+
+    context 'when the client api version is not v4' do
+      let(:api_version) { 'v3' }
+
+      it 'raises a ParameterError' do
+        expect { webhooks.create_v4(domain, url: url, event_types: 'accepted') }
+          .to raise_error(Mailgun::ParameterError, /must be v4/)
+        expect { webhooks.update_v4(domain, url: url, event_types: 'accepted') }
+          .to raise_error(Mailgun::ParameterError, /must be v4/)
+        expect { webhooks.remove_v4(domain, url: url) }
+          .to raise_error(Mailgun::ParameterError, /must be v4/)
+      end
+    end
+  end
+end

data/vcr_cassettes/account_webhooks.yml

@@ -0,0 +1,269 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://api.mailgun.net/v1/webhooks
+    body:
+      encoding: UTF-8
+      string: description=test&event_types=accepted&url=http%3A%2F%2Fexample.com%2Fmailgun%2Fevents
+    headers:
+      User-Agent:
+      - mailgun-sdk-ruby/1.4.4
+      Accept:
+      - "*/*"
+      Authorization:
+      - Basic xxx
+      Content-Type:
+      - application/x-www-form-urlencoded
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Credentials:
+      - 'true'
+      Access-Control-Allow-Origin:
+      - "*"
+      Cache-Control:
+      - no-store
+      Content-Length:
+      - '42'
+      Content-Type:
+      - application/json; charset=utf-8
+      Date:
+      - Mon, 25 May 2026 09:11:02 GMT
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      X-Mailgun-Key-Id:
+      - xxx
+      X-Xss-Protection:
+      - 1; mode=block
+      Server-Timing:
+      - cfReqDur;dur=382.358
+      Cf-Team:
+      - xxx
+    body:
+      encoding: UTF-8
+      string: '{"webhook_id":"test"}
+
+        '
+  recorded_at: Mon, 25 May 2026 09:11:02 GMT
+- request:
+    method: get
+    uri: https://api.mailgun.net/v1/webhooks?webhook_ids=
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      User-Agent:
+      - mailgun-sdk-ruby/1.4.4
+      Accept:
+      - "*/*"
+      Authorization:
+      - Basic xxx
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Credentials:
+      - 'true'
+      Access-Control-Allow-Origin:
+      - "*"
+      Cache-Control:
+      - no-store
+      Content-Length:
+      - '183'
+      Content-Type:
+      - application/json; charset=utf-8
+      Date:
+      - Mon, 25 May 2026 09:16:27 GMT
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      X-Mailgun-Key-Id:
+      - xxx
+      X-Xss-Protection:
+      - 1; mode=block
+      Server-Timing:
+      - cfReqDur;dur=201.477
+      Cf-Team:
+      - xxx
+    body:
+      encoding: UTF-8
+      string: '{"webhooks":[{"webhook_id":"test","description":"test","url":"http://example.com/mailgun/events","event_types":["accepted"],"created_at":"2026-05-25T09:11:02Z"}]}
+
+        '
+  recorded_at: Mon, 25 May 2026 09:16:27 GMT
+- request:
+    method: get
+    uri: https://api.mailgun.net/v1/webhooks/test
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      User-Agent:
+      - mailgun-sdk-ruby/1.4.4
+      Accept:
+      - "*/*"
+      Authorization:
+      - Basic xxx
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Credentials:
+      - 'true'
+      Access-Control-Allow-Origin:
+      - "*"
+      Cache-Control:
+      - no-store
+      Content-Length:
+      - '168'
+      Content-Type:
+      - application/json; charset=utf-8
+      Date:
+      - Mon, 25 May 2026 09:22:12 GMT
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      X-Mailgun-Key-Id:
+      - xxx
+      X-Xss-Protection:
+      - 1; mode=block
+      Server-Timing:
+      - cfReqDur;dur=234.628
+      Cf-Team:
+      - xxx
+    body:
+      encoding: UTF-8
+      string: '{"webhook_id":"test","description":"test","url":"http://example.com/mailgun/events","event_types":["accepted"],"created_at":"2026-05-25T09:11:02Z"}
+
+        '
+  recorded_at: Mon, 25 May 2026 09:22:12 GMT
+- request:
+    method: put
+    uri: https://api.mailgun.net/v1/webhooks/test
+    body:
+      encoding: UTF-8
+      string: description=test2&event_types=accepted&url=http%3A%2F%2Fexample.com%2Fmailgun%2Fevents
+    headers:
+      User-Agent:
+      - mailgun-sdk-ruby/1.4.4
+      Accept:
+      - "*/*"
+      Authorization:
+      - Basic xxx
+      Content-Type:
+      - application/x-www-form-urlencoded
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+  response:
+    status:
+      code: 204
+      message: No Content
+    headers:
+      Access-Control-Allow-Credentials:
+      - 'true'
+      Access-Control-Allow-Origin:
+      - "*"
+      Cache-Control:
+      - no-store
+      Date:
+      - Mon, 25 May 2026 12:03:17 GMT
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      X-Mailgun-Key-Id:
+      - xxx
+      X-Xss-Protection:
+      - 1; mode=block
+    body:
+      encoding: UTF-8
+      string: ''
+  recorded_at: Mon, 25 May 2026 12:03:17 GMT
+- request:
+    method: delete
+    uri: https://api.mailgun.net/v1/webhooks/test
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      User-Agent:
+      - mailgun-sdk-ruby/1.4.4
+      Accept:
+      - "*/*"
+      Authorization:
+      - Basic xxx
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+  response:
+    status:
+      code: 204
+      message: No Content
+    headers:
+      Access-Control-Allow-Credentials:
+      - 'true'
+      Access-Control-Allow-Origin:
+      - "*"
+      Cache-Control:
+      - no-store
+      Date:
+      - Mon, 25 May 2026 12:08:15 GMT
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      X-Mailgun-Key-Id:
+      - xxx
+      X-Xss-Protection:
+      - 1; mode=block
+    body:
+      encoding: UTF-8
+      string: ''
+  recorded_at: Mon, 25 May 2026 12:08:15 GMT
+- request:
+    method: delete
+    uri: https://api.mailgun.net/v1/webhooks?all=true
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      User-Agent:
+      - mailgun-sdk-ruby/1.4.4
+      Accept:
+      - "*/*"
+      Authorization:
+      - Basic xxx
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+  response:
+    status:
+      code: 204
+      message: No Content
+    headers:
+      Access-Control-Allow-Credentials:
+      - 'true'
+      Access-Control-Allow-Origin:
+      - "*"
+      Cache-Control:
+      - no-store
+      Date:
+      - Mon, 25 May 2026 20:28:16 GMT
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      X-Mailgun-Key-Id:
+      - xxx
+      X-Xss-Protection:
+      - 1; mode=block
+      Server-Timing:
+      - cfReqDur;dur=246.503
+      Cf-Team:
+      - xxx
+    body:
+      encoding: UTF-8
+      string: ''
+  recorded_at: Mon, 25 May 2026 20:28:16 GMT
+recorded_with: VCR 6.4.0