Suppressions Api

Author: sarco3t

examples/suppressions_api.rb

@@ -0,0 +1,35 @@
+require 'mailtrap'
+
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+suppressions = Mailtrap::SuppressionsAPI.new 3229, client
+
+# Set your API credentials as environment variables
+# export MAILTRAP_API_KEY='your-api-key'
+# export MAILTRAP_ACCOUNT_ID=your-account-id
+#
+# suppressions = Mailtrap::SuppressionsAPI.new
+
+# Get all suppressions
+list = suppressions.list
+# =>
+#  [
+#    Mailtrap::Suppression.new(
+#      id: "64d71bf3-1276-417b-86e1-8e66f138acfe",
+#      type: "unsubscription",
+#      created_at: "2024-12-26T09:40:44.161Z",
+#      email: "[email protected]",
+#      sending_stream: "transactional",
+#      domain_name: "sender.com",
+#      message_bounce_category: nil,
+#      message_category: "Welcome email",
+#      message_client_ip: "123.123.123.123",
+#      message_created_at: "2024-12-26T07:10:00.889Z",
+#      message_outgoing_ip: "1.1.1.1",
+#      message_recipient_mx_name: "Other Providers",
+#      message_sender_email: "[email protected]",
+#      message_subject: "Welcome!"
+#    )
+#  ]
+
+# Delete a suppression
+suppressions.delete(list.first.id)

lib/mailtrap.rb

@@ -9,6 +9,7 @@
 require_relative 'mailtrap/contact_lists_api'
 require_relative 'mailtrap/contact_fields_api'
 require_relative 'mailtrap/contact_imports_api'
+require_relative 'mailtrap/suppressions_api'
 
 module Mailtrap
   # @!macro api_errors

lib/mailtrap/base_api.rb

@@ -64,8 +64,8 @@ def base_delete(id)
       client.delete("#{base_path}/#{id}")
     end
 
-    def base_list
-      response = client.get(base_path)
+    def base_list(query_params = {})
+      response = client.get(base_path, query_params)
       response.map { |item| handle_response(item) }
     end
 

lib/mailtrap/client.rb

@@ -157,10 +157,11 @@ def send(mail)
 
     # Performs a GET request to the specified path
     # @param path [String] The request path
+    # @param query_params [Hash] Query parameters to append to the URL (optional)
     # @return [Hash, nil] The JSON response
     # @!macro api_errors
-    def get(path)
-      perform_request(:get, general_api_host, path)
+    def get(path, query_params = {})
+      perform_request(:get, general_api_host, path, nil, query_params)
     end
 
     # Performs a POST request to the specified path
@@ -213,13 +214,21 @@ def batch_request_path
       "/api/batch#{"/#{inbox_id}" if sandbox}"
     end
 
-    def perform_request(method, host, path, body = nil)
+    def perform_request(method, host, path, body = nil, query_params = {})
       http_client = http_client_for(host)
+      path = build_path_with_query(path, query_params) if query_params.any?
+
       request = setup_request(method, path, body)
       response = http_client.request(request)
       handle_response(response)
     end
 
+    def build_path_with_query(base_path, query_params = {})
+      uri = URI(base_path)
+      uri.query = URI.encode_www_form(query_params)
+      uri.to_s
+    end
+
     def setup_request(method, path, body = nil)
       request = case method
                 when :get

lib/mailtrap/suppression.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Suppression
+  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/f8144826d885a-list-and-search-suppressions
+  # @attr_reader id [String] The suppression UUID
+  # @attr_reader type [String] The suppression type
+  # @attr_reader created_at [String] The creation timestamp
+  # @attr_reader email [String] The email address
+  # @attr_reader sending_stream [String] The sending stream
+  # @attr_reader domain_name [String, nil] The domain name
+  # @attr_reader message_bounce_category [String, nil] The bounce category
+  # @attr_reader message_category [String, nil] The message category
+  # @attr_reader message_client_ip [String, nil] The client IP
+  # @attr_reader message_created_at [String, nil] The message creation timestamp
+  # @attr_reader message_esp_response [String, nil] The ESP response
+  # @attr_reader message_esp_server_type [String, nil] The ESP server type
+  # @attr_reader message_outgoing_ip [String, nil] The outgoing IP
+  # @attr_reader message_recipient_mx_name [String, nil] The recipient MX name
+  # @attr_reader message_sender_email [String, nil] The sender email
+  # @attr_reader message_subject [String, nil] The message subject
+  Suppression = Struct.new(
+    :id,
+    :type,
+    :created_at,
+    :email,
+    :sending_stream,
+    :domain_name,
+    :message_bounce_category,
+    :message_category,
+    :message_client_ip,
+    :message_created_at,
+    :message_esp_response,
+    :message_esp_server_type,
+    :message_outgoing_ip,
+    :message_recipient_mx_name,
+    :message_sender_email,
+    :message_subject,
+    keyword_init: true
+  ) do
+    # @return [Hash] The suppression attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+end

lib/mailtrap/suppressions_api.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'suppression'
+
+module Mailtrap
+  class SuppressionsAPI
+    include BaseAPI
+
+    self.response_class = Suppression
+
+    # Lists all suppressions for the account
+    # @param email [String] Email address to filter suppressions (optional)
+    # @return [Array<Suppression>] Array of suppression objects
+    # @!macro api_errors
+    def list(email: nil)
+      query_params = {}
+      query_params[:email] = email if email
+
+      base_list(query_params)
+    end
+
+    # Deletes a suppression
+    # @param suppression_id [String] The suppression UUID
+    # @return nil
+    # @!macro api_errors
+    def delete(suppression_id)
+      client.delete("#{base_path}/#{suppression_id}")
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/suppressions"
+    end
+  end
+end