Merge pull request #81 from mailtrap/MT-19854-sending-domains

Add Sending domains API

Author: DagonWat

.github/workflows/main.yml

@@ -9,6 +9,8 @@ jobs:
   build:
     runs-on: ubuntu-latest
     name: Ruby ${{ matrix.ruby }}
+    env:
+      BUNDLE_PATH: vendor/bundle
     strategy:
       matrix:
         ruby:

CHANGELOG.md

@@ -1,3 +1,5 @@
+- Add Sending Domains API
+
 ## [2.6.0] - 2026-01-27
 - Add Inboxes API
 - Add Projects API

README.md

@@ -173,9 +173,10 @@ mail(delivery_method: :mailtrap_bulk)
 Refer to the [`examples`](examples) folder for more examples:
 
 Email API:
-- Full email sending – [`full.rb`](examples/full.rb)
 
-- Batch sending – [`batch.rb`](examples/batch.rb)
+- Full Email Sending – [`full.rb`](examples/full.rb)
+- Batch Sending – [`batch.rb`](examples/batch.rb)
+- Sending Domains API  – [`sending_domains_api.rb`](examples/sending_domains_api.rb)
 
 Email Sandbox (Testing):
 
@@ -184,7 +185,7 @@ Email Sandbox (Testing):
 
 Contact management:
 
-- Contacts CRUD & listing – [`contacts_api.rb`](examples/contacts_api.rb)
+- Contacts CRUD & Listing – [`contacts_api.rb`](examples/contacts_api.rb)
 
 General API:
 

examples/sending_domains_api.rb

@@ -0,0 +1,25 @@
+require 'mailtrap'
+
+account_id = 3229
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+sending_domains = Mailtrap::SendingDomainsAPI.new(account_id, client)
+
+# Create new Sending Domain
+sending_domain = sending_domains.create(domain_name: 'example.com')
+# => #<struct Mailtrap::SendingDomain id=1, domain_name="example.com">
+
+# Get all Sending Domains
+sending_domains.list
+# => [#<struct Mailtrap::SendingDomain id=1, domain_name="example.com">]
+
+# Get sending domain
+sending_domain = sending_domains.get(sending_domain.id)
+# => #<struct Mailtrap::SendingDomain id=1, domain_name="example.com">
+
+# Send setup email
+sending_domains.send_setup_instructions(sending_domain.id, 'jonathan@mail.com')
+# => nil
+
+# Delete sending domain
+sending_domains.delete(sending_domain.id)
+# => nil

lib/mailtrap.rb

@@ -12,6 +12,7 @@
 require_relative 'mailtrap/suppressions_api'
 require_relative 'mailtrap/projects_api'
 require_relative 'mailtrap/inboxes_api'
+require_relative 'mailtrap/sending_domains_api'
 
 module Mailtrap
   # @!macro api_errors

lib/mailtrap/sending_domain.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Sending Domain
+  # @see https://docs.mailtrap.io/developers/management/sending-domains
+  # @attr_reader id [Integer] The sending domain ID
+  # @attr_reader domain_name [String] The sending domain name
+  # @attr_reader demo [Boolean] Whether the sending domain is a demo domain
+  # @attr_reader compliance_status [String] The compliance status of the sending domain
+  # @attr_reader dns_verified [Boolean] Whether the DNS records are verified
+  # @attr_reader dns_verified_at [String, nil] The timestamp when DNS was verified
+  # @attr_reader dns_records [Array] The DNS records for the sending domain
+  # @attr_reader open_tracking_enabled [Boolean] Whether open tracking is enabled
+  # @attr_reader click_tracking_enabled [Boolean] Whether click tracking is enabled
+  # @attr_reader auto_unsubscribe_link_enabled [Boolean] Whether auto unsubscribe link is enabled
+  # @attr_reader custom_domain_tracking_enabled [Boolean] Whether custom domain tracking is enabled
+  # @attr_reader health_alerts_enabled [Boolean] Whether health alerts are enabled
+  # @attr_reader critical_alerts_enabled [Boolean] Whether critical alerts are enabled
+  # @attr_reader alert_recipient_email [String, nil] The email address for alert recipients
+  # @attr_reader permissions [Hash] The permissions for the sending domain
+  #
+  SendingDomain = Struct.new(
+    :id,
+    :domain_name,
+    :demo,
+    :compliance_status,
+    :dns_verified,
+    :dns_verified_at,
+    :dns_records,
+    :open_tracking_enabled,
+    :click_tracking_enabled,
+    :auto_unsubscribe_link_enabled,
+    :custom_domain_tracking_enabled,
+    :health_alerts_enabled,
+    :critical_alerts_enabled,
+    :alert_recipient_email,
+    :permissions,
+    :created_at,
+    :updated_at,
+    keyword_init: true
+  )
+end

lib/mailtrap/sending_domains_api.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'sending_domain'
+
+module Mailtrap
+  class SendingDomainsAPI
+    include BaseAPI
+
+    self.supported_options = %i[domain_name]
+
+    self.response_class = SendingDomain
+
+    # Lists all sending domains for the account
+    # @return [Array<SendingDomain>] Array of sending domains
+    # @!macro api_errors
+    def list
+      response = client.get(base_path)
+      response[:data].map { |item| handle_response(item) }
+    end
+
+    # Retrieves a specific sending domain
+    # @param domain_id [Integer] The sending domain ID
+    # @return [SendingDomain] Sending domain object
+    # @!macro api_errors
+    def get(domain_id)
+      base_get(domain_id)
+    end
+
+    # Creates a new sending domain
+    # @param [Hash] options The parameters to create
+    # @option options [String] :domain_name The sending domain name
+    # @return [SendingDomain] Created sending domain
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Deletes a sending domain
+    # @param domain_id [Integer] The sending domain ID
+    # @return nil
+    # @!macro api_errors
+    def delete(domain_id)
+      base_delete(domain_id)
+    end
+
+    # Email DNS configuration instructions for the sending domain
+    # @param domain_id [Integer] The sending domain ID
+    # @param email [String] The email for instructions
+    # @return nil
+    # @!macro api_errors
+    def send_setup_instructions(domain_id:, email:)
+      client.post("#{base_path}/#{domain_id}/send_setup_instructions", email:)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/sending_domains"
+    end
+
+    def wrap_request(options)
+      { sending_domain: options }
+    end
+  end
+end