mailtrap 2.4.1 → 2.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9051a9ecb98e5863ddcf088f3f7e46e0adc5c78704feb50cf83d96e5f8291b55
-  data.tar.gz: 991d829e6b2a412c710e45d5731cebd42430546b40aac3147fd618686faa3f82
+  metadata.gz: fbab8dc3de2d25ab941149a0324bde111b57ce174a3b4d6c7f9233a2081edaf6
+  data.tar.gz: 2504ee84dc9fea519b8fef55c9adf9e160f28f2e400a28d9b228db0fb82a3bcf
 SHA512:
-  metadata.gz: c657894990e6ddef1d77f6ab380e56fbbf66f9286087ee3f10e6f14c63708ac09fcecfd547c095cb91240fa7c50674cffa6cbae917c8b5ee75a5b1be91a0a03d
-  data.tar.gz: eb1e87d218d66bcdbb8fe0c9a27d1912e8171836b08270f1221247edb08c1577e3e0932b7b9ef4e8aa29adca4dc56aec7a68b6f821f0065cf2ff1defcf4518a6
+  metadata.gz: 60f24be1ea02688b21315cd2b33c17b7ef09d5e11c2695f7f237c6fadac1bd0c9aa2458b74713f3ffb13421bc1d58237fd12b5b6a5a101be00e5530f9ebf86a5
+  data.tar.gz: 53e05d3a12c3f68cd5ade6cb844e3316902594be51aa85a624941ad7c501765bbf8302d985f6c9a27028034397a794281d4266d06580ffdb5b289d876c3ac28d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mailtrap (2.4.1)
+    mailtrap (2.4.2)
       base64
 
 GEM
@@ -65,7 +65,7 @@ GEM
     regexp_parser (2.10.0)
     reline (0.6.1)
       io-console (~> 0.5)
-    rexml (3.4.1)
+    rexml (3.4.2)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)

data/README.md

@@ -1,4 +1,4 @@
-[![test](https://github.com/railsware/mailtrap-ruby/actions/workflows/main.yml/badge.svg)](https://github.com/railsware/mailtrap-ruby/actions/workflows/main.yml)
+[![test](https://github.com/mailtrap/mailtrap-ruby/actions/workflows/main.yml/badge.svg)](https://github.com/mailtrap/mailtrap-ruby/actions/workflows/main.yml)
 [![docs](https://shields.io/badge/docs-rubydoc.info-blue)](https://rubydoc.info/gems/mailtrap)
 [![gem](https://shields.io/gem/v/mailtrap)](https://rubygems.org/gems/mailtrap)
 [![downloads](https://shields.io/gem/dt/mailtrap)](https://rubygems.org/gems/mailtrap)
@@ -182,7 +182,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on [GitHub](https://github.com/railsware/mailtrap-ruby). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on [GitHub](https://github.com/mailtrap/mailtrap-ruby). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
 
 ## License
 

data/lib/mailtrap/base_api.rb

@@ -64,8 +64,8 @@ module Mailtrap
       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
 

data/lib/mailtrap/client.rb

@@ -119,10 +119,15 @@ module Mailtrap
     # @!macro api_errors
     # @raise [Mailtrap::MailSizeError] If the message is too large.
     def send_batch(base, requests)
-      perform_request(:post, api_host, batch_request_path, {
-                        base:,
-                        requests:
-                      })
+      perform_request(
+        method: :post,
+        host: api_host,
+        path: batch_request_path,
+        body: {
+          base:,
+          requests:
+        }
+      )
     end
 
     # Sends an email
@@ -152,15 +157,26 @@ module Mailtrap
     # @!macro api_errors
     # @raise [Mailtrap::MailSizeError] If the message is too large
     def send(mail)
-      perform_request(:post, api_host, send_path, mail)
+      perform_request(
+        method: :post,
+        host: api_host,
+        path: send_path,
+        body: mail
+      )
     end
 
     # 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(
+        method: :get,
+        host: general_api_host,
+        path:,
+        query_params:
+      )
     end
 
     # Performs a POST request to the specified path
@@ -169,7 +185,12 @@ module Mailtrap
     # @return [Hash, nil] The JSON response
     # @!macro api_errors
     def post(path, body = nil)
-      perform_request(:post, general_api_host, path, body)
+      perform_request(
+        method: :post,
+        host: general_api_host,
+        path:,
+        body:
+      )
     end
 
     # Performs a PATCH request to the specified path
@@ -178,7 +199,12 @@ module Mailtrap
     # @return [Hash, nil] The JSON response
     # @!macro api_errors
     def patch(path, body = nil)
-      perform_request(:patch, general_api_host, path, body)
+      perform_request(
+        method: :patch,
+        host: general_api_host,
+        path:,
+        body:
+      )
     end
 
     # Performs a DELETE request to the specified path
@@ -186,7 +212,11 @@ module Mailtrap
     # @return [Hash, nil] The JSON response
     # @!macro api_errors
     def delete(path)
-      perform_request(:delete, general_api_host, path)
+      perform_request(
+        method: :delete,
+        host: general_api_host,
+        path:
+      )
     end
 
     private
@@ -213,23 +243,27 @@ module Mailtrap
       "/api/batch#{"/#{inbox_id}" if sandbox}"
     end
 
-    def perform_request(method, host, path, body = nil)
+    def perform_request(method:, host:, path:, query_params: {}, body: nil)
       http_client = http_client_for(host)
-      request = setup_request(method, path, body)
+
+      uri = URI::HTTPS.build(host:, path:)
+      uri.query = URI.encode_www_form(query_params) if query_params.any?
+
+      request = setup_request(method, uri, body)
       response = http_client.request(request)
       handle_response(response)
     end
 
-    def setup_request(method, path, body = nil)
+    def setup_request(method, uri_or_path, body = nil)
       request = case method
                 when :get
-                  Net::HTTP::Get.new(path)
+                  Net::HTTP::Get.new(uri_or_path)
                 when :post
-                  Net::HTTP::Post.new(path)
+                  Net::HTTP::Post.new(uri_or_path)
                 when :patch
-                  Net::HTTP::Patch.new(path)
+                  Net::HTTP::Patch.new(uri_or_path)
                 when :delete
-                  Net::HTTP::Delete.new(path)
+                  Net::HTTP::Delete.new(uri_or_path)
                 else
                   raise ArgumentError, "Unsupported HTTP method: #{method}"
                 end
@@ -237,7 +271,7 @@ module Mailtrap
       request.body = body.to_json if body
       request['Authorization'] = "Bearer #{api_key}"
       request['Content-Type'] = 'application/json'
-      request['User-Agent'] = 'mailtrap-ruby (https://github.com/railsware/mailtrap-ruby)'
+      request['User-Agent'] = 'mailtrap-ruby (https://github.com/mailtrap/mailtrap-ruby)'
 
       request
     end

data/lib/mailtrap/contact_import.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Contact Import
+  # @attr_reader id [Integer] The contact import ID
+  # @attr_reader status [String] The status of the import (created, started, finished, failed)
+  # @attr_reader created_contacts_count [Integer, nil] Number of contacts created in this import
+  # @attr_reader updated_contacts_count [Integer, nil] Number of contacts updated in this import
+  # @attr_reader contacts_over_limit_count [Integer, nil] Number of contacts over the allowed limit
+  ContactImport = Struct.new(
+    :id,
+    :status,
+    :created_contacts_count,
+    :updated_contacts_count,
+    :contacts_over_limit_count,
+    keyword_init: true
+  ) do
+    # @return [Hash] The contact attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+end

data/lib/mailtrap/contact_imports_api.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'contact_import'
+require_relative 'contacts_import_request'
+
+module Mailtrap
+  class ContactImportsAPI
+    include BaseAPI
+
+    self.supported_options = %i[email fields list_ids_included list_ids_excluded]
+
+    self.response_class = ContactImport
+
+    # Retrieves a specific contact import
+    # @param import_id [Integer] The contact import identifier
+    # @return [ContactImport] Contact import object
+    # @!macro api_errors
+    def get(import_id)
+      base_get(import_id)
+    end
+
+    # Create contacts import
+    #
+    # @example Using Mailtrap::ContactsImportRequest
+    #   import_request = Mailtrap::ContactsImportRequest.new.tap do |req|
+    #     req.upsert(email: 'jane@example.com', fields: { first_name: 'Jane' })
+    #       .add_to_lists(email: 'jane@example.com', list_ids: [1])
+    #       .remove_from_lists(email: 'jane@example.com', list_ids: [2])
+    #     req.upsert(email: 'john@example.com', fields: { first_name: 'John' })
+    #       .add_to_lists(email: 'john@example.com', list_ids: [1])
+    #       .remove_from_lists(email: 'john@example.com', list_ids: [2])
+    #   end
+    #   contact_imports.create(import_request)
+    #
+    # @example Using plain hash
+    #   contact_imports.create([
+    #     {email: 'john@example.com', fields: { first_name: 'John' }, list_ids_included: [1], list_ids_excluded: [2]},
+    #     {email: 'jane@example.com', fields: { first_name: 'Jane' }, list_ids_included: [1], list_ids_excluded: [2]}
+    #   ])
+    #
+    # @param contacts [Mailtrap::ContactsImportRequest, Array<Hash>] The contacts import request
+    #
+    # @return [ContactImport] Created contact import object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(contacts)
+      contact_data = contacts.to_a.each do |contact|
+        validate_options!(contact, supported_options)
+      end
+      response = client.post(base_path, contacts: contact_data)
+      handle_response(response)
+    end
+    alias start create
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/contacts/imports"
+    end
+  end
+end

data/lib/mailtrap/contacts_import_request.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # A builder class for creating contact import requests
+  # Allows you to build a collection of contacts with their associated fields and list memberships
+  class ContactsImportRequest
+    def initialize
+      @data = Hash.new do |h, k|
+        h[k] = { email: k, fields: {}, list_ids_included: [], list_ids_excluded: [] }
+      end
+    end
+
+    # Creates or updates a contact with the provided email and fields
+    # @param email [String] The contact's email address
+    # @param fields [Hash] Contact fields in the format: field_merge_tag => String, Integer, Float, Boolean, or
+    #   ISO-8601 date string (yyyy-mm-dd)
+    # @return [ContactsImportRequest] Returns self for method chaining
+    def upsert(email:, fields: {})
+      validate_email!(email)
+
+      @data[email][:fields].merge!(fields)
+
+      self
+    end
+
+    # Adds a contact to the specified lists
+    # @param email [String] The contact's email address
+    # @param list_ids [Array<Integer>] Array of list IDs to add the contact to
+    # @return [ContactsImportRequest] Returns self for method chaining
+    def add_to_lists(email:, list_ids:)
+      validate_email!(email)
+
+      append_list_ids email:, list_ids:, key: :list_ids_included
+
+      self
+    end
+
+    # Removes a contact from the specified lists
+    # @param email [String] The contact's email address
+    # @param list_ids [Array<Integer>] Array of list IDs to remove the contact from
+    # @return [ContactsImportRequest] Returns self for method chaining
+    def remove_from_lists(email:, list_ids:)
+      validate_email!(email)
+
+      append_list_ids email:, list_ids:, key: :list_ids_excluded
+
+      self
+    end
+
+    # @return [Array<Hash>] Array of contact objects ready for import
+    def to_a
+      @data.values
+    end
+
+    private
+
+    def validate_email!(email)
+      raise ArgumentError, 'email must be present' if email.nil? || email.empty?
+    end
+
+    def append_list_ids(email:, list_ids:, key:)
+      raise ArgumentError, 'list_ids must be present' if list_ids.empty?
+
+      @data[email][key] |= list_ids
+    end
+  end
+end

data/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

data/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

data/lib/mailtrap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mailtrap
-  VERSION = '2.4.1'
+  VERSION = '2.4.2'
 end

data/lib/mailtrap.rb

@@ -8,6 +8,8 @@ require_relative 'mailtrap/email_templates_api'
 require_relative 'mailtrap/contacts_api'
 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

data/mailtrap.gemspec

@@ -10,13 +10,13 @@ Gem::Specification.new do |spec|
 
   spec.summary = 'Official mailtrap.io API client'
   spec.description = 'Official mailtrap.io API client'
-  spec.homepage = 'https://github.com/railsware/mailtrap-ruby'
+  spec.homepage = 'https://github.com/mailtrap/mailtrap-ruby'
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 3.1.0'
 
   spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://github.com/railsware/mailtrap-ruby'
-  spec.metadata['changelog_uri'] = 'https://github.com/railsware/mailtrap-ruby/blob/main/CHANGELOG.md'
+  spec.metadata['source_code_uri'] = 'https://github.com/mailtrap/mailtrap-ruby'
+  spec.metadata['changelog_uri'] = 'https://github.com/mailtrap/mailtrap-ruby/blob/main/CHANGELOG.md'
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.add_dependency 'base64'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailtrap
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.4.2
 platform: ruby
 authors:
 - Railsware Products Studio LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-22 00:00:00.000000000 Z
+date: 2025-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -51,24 +51,29 @@ files:
 - lib/mailtrap/contact.rb
 - lib/mailtrap/contact_field.rb
 - lib/mailtrap/contact_fields_api.rb
+- lib/mailtrap/contact_import.rb
+- lib/mailtrap/contact_imports_api.rb
 - lib/mailtrap/contact_list.rb
 - lib/mailtrap/contact_lists_api.rb
 - lib/mailtrap/contacts_api.rb
+- lib/mailtrap/contacts_import_request.rb
 - lib/mailtrap/email_template.rb
 - lib/mailtrap/email_templates_api.rb
 - lib/mailtrap/errors.rb
 - lib/mailtrap/mail.rb
 - lib/mailtrap/mail/base.rb
 - lib/mailtrap/mail/from_template.rb
+- lib/mailtrap/suppression.rb
+- lib/mailtrap/suppressions_api.rb
 - lib/mailtrap/version.rb
 - mailtrap.gemspec
-homepage: https://github.com/railsware/mailtrap-ruby
+homepage: https://github.com/mailtrap/mailtrap-ruby
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/railsware/mailtrap-ruby
-  source_code_uri: https://github.com/railsware/mailtrap-ruby
-  changelog_uri: https://github.com/railsware/mailtrap-ruby/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/mailtrap/mailtrap-ruby
+  source_code_uri: https://github.com/mailtrap/mailtrap-ruby
+  changelog_uri: https://github.com/mailtrap/mailtrap-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []