mailtrap 2.10.0 → 2.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3a95002cbfb65622fa2d944bf2de1d41dc25a9a7224f8d244982fdf8154776d
-  data.tar.gz: a228f3805ce687e8f34bd410595f6e39f9e7d73a426d1d06ca2b35ec972b5c69
+  metadata.gz: b6606da8d73e2112b813b87000d3aaa63c5490cf2d046dedf59eb5a4f56fc619
+  data.tar.gz: a7647dad5291d79758edd52e2b01c57e3e475d998a271ddcd5f6daf24455f59c
 SHA512:
-  metadata.gz: fcec8536fae46762bd7289b7b098f45728c9d00b79bcd1386b6e4cb384fa0fcf859136db5cc956480da7aa1cb5063ed8dbee2312ac0e2bf6c8ac4b872443e650
-  data.tar.gz: 127126f80cded1f05214a173b1c8e78b8acc6c39bdbf1f168b161ca221a5e4230aa11d098f26c8c188c14778a28c579ac0e2bea52bab2713c82068d43836b677
+  metadata.gz: e8bca46ba63dfa33175e89b2fcdaba9cce1701d904b6eee25a4808e57524b17dd7f97f483e6289c889fdb6006d35ced29c857beacdc1d2431f8c43a26d878161
+  data.tar.gz: 7dbeaaf7198cc263e2ab8264113b0992836a2141745d96edd031f9ff33934649ab4b1cf5bf9a882016a63e243c77d129be61f8f9ab3957b8091019fdb90e2593

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+## [2.11.1] - 2026-07-02
+
+## What's Changed
+* Release v2.11.0 by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/109
+* MT-22022: Add webhook signature verification helper by @Rabsztok in https://github.com/mailtrap/mailtrap-ruby/pull/110
+* Add draft-release workflow placeholder by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/111
+* Implement draft-release workflow by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/112
+
+## New Contributors
+* @Rabsztok made their first contribution in https://github.com/mailtrap/mailtrap-ruby/pull/110
+
+**Full Changelog**: https://github.com/mailtrap/mailtrap-ruby/compare/v2.11.0...v2.11.1
+
+## [2.11.0] - 2026-05-14
+## What's Changed
+* Update sandboxes api by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/103
+* Sending domains endpoints by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/104
+* Add contact endpoints by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/105
+* Account management API by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/106
+* Add api token endpoints by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/107
+* Add webhook endpoints by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/108
+
+
 ## [2.10.0] - 2026-03-23
 
 - Add Email Logs API (list and get email sending logs with filters and cursor pagination)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mailtrap (2.10.0)
+    mailtrap (2.11.1)
       base64
 
 GEM

data/README.md

@@ -8,7 +8,6 @@
 
 This client uses API v2, for v1 refer to [this documentation](https://mailtrap.docs.apiary.io/)
 
-
 ## Prerequisites
 
 To get the most out of this official Mailtrap.io Ruby SDK:
@@ -176,9 +175,10 @@ Email API:
 
 - 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)
+- Sending Domains API – [`sending_domains_api.rb`](examples/sending_domains_api.rb)
 - Sending Stats API – [`stats_api.rb`](examples/stats_api.rb)
 - Email Logs API – [`email_logs_api.rb`](examples/email_logs_api.rb)
+- Webhooks API – [`webhooks_api.rb`](examples/webhooks_api.rb)
 
 Email Sandbox (Testing):
 
@@ -198,6 +198,7 @@ General:
 - Billing API – [`billing_api.rb`](examples/billing_api.rb)
 - Templates API – [`email_templates_api.rb`](examples/email_templates_api.rb)
 - Action Mailer – [`action_mailer.rb`](examples/action_mailer.rb)
+- Verifying webhook signatures – [`webhooks_signature_verification.ru`](examples/webhooks_signature_verification.ru)
 
 ## Migration guide v1 → v2
 
@@ -212,14 +213,14 @@ Bug reports and pull requests are welcome on [GitHub](https://github.com/railswa
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake spec` to run the tests. You can also run `bin/console` for an interactive 
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
 prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
 To release a new version, update the version number in `version.rb`, and then
 run `bundle exec rake release`, which will create a git tag for the version,
-push git commits and the created tag, and push the `.gem` file to 
+push git commits and the created tag, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
 To run the documentation server, first generate the documentation with
@@ -240,4 +241,4 @@ Everyone interacting in the Mailtrap project's codebases, issue trackers, chat r
 
 ## Compatibility with previous releases
 
-Versions of this package up to 2.0.2 were an [unofficial client](https://github.com/vchin/mailtrap-client) developed by [@vchin](https://github.com/vchin). Package version 3 is a completely new package. 
+Versions of this package up to 2.0.2 were an [unofficial client](https://github.com/vchin/mailtrap-client) developed by [@vchin](https://github.com/vchin). Package version 3 is a completely new package.

data/lib/mailtrap/api_token.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for API Token
+  # @attr_reader id [Integer] The API token ID
+  # @attr_reader name [String] Token display name
+  # @attr_reader last_4_digits [String] Last 4 characters of the token
+  # @attr_reader created_by [String] Name of the user or token that created this token
+  # @attr_reader expires_at [String, nil] When the token expires (ISO 8601); nil if it does not expire
+  # @attr_reader resources [Array<Hash>] Permissions granted to this token
+  # @attr_reader token [String, nil] Full token value — only populated by #create and #reset
+  ApiToken = Struct.new(
+    :id,
+    :name,
+    :last_4_digits,
+    :created_by,
+    :expires_at,
+    :resources,
+    :token,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/api_tokens_api.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'api_token'
+
+module Mailtrap
+  class ApiTokensAPI
+    include BaseAPI
+
+    self.supported_options = %i[name resources].freeze
+
+    self.response_class = ApiToken
+
+    # Lists API tokens visible to the current API token
+    # @return [Array<ApiToken>] Array of API tokens
+    # @!macro api_errors
+    def list
+      base_list
+    end
+
+    # Retrieves a single API token by ID
+    # @param token_id [Integer] The API token ID
+    # @return [ApiToken] API token object (the `token` field is nil — full value is only
+    #   returned by #create and #reset)
+    # @!macro api_errors
+    def get(token_id)
+      base_get(token_id)
+    end
+
+    # Creates a new API token. The full `token` value is returned ONLY ONCE — store it securely.
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name Display name for the token
+    # @option options [Array<Hash>] :resources Permissions to assign
+    #   - `{ resource_type:, resource_id:, access_level: }`
+    # @return [ApiToken] Created token (full `token` value populated)
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Expires the requested token and returns a new one with the same permissions.
+    # The old token stops working after a short grace period. The new `token` value is
+    # returned ONLY ONCE — store it securely
+    # @param token_id [Integer] The API token ID
+    # @return [ApiToken] New token (full `token` value populated)
+    # @!macro api_errors
+    def reset(token_id)
+      response = client.post("#{base_path}/#{token_id}/reset")
+      handle_response(response)
+    end
+
+    # Permanently deletes an API token
+    # @param token_id [Integer] The API token ID
+    # @return nil
+    # @!macro api_errors
+    def delete(token_id)
+      base_delete(token_id)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/api_tokens"
+    end
+  end
+end

data/lib/mailtrap/client.rb

@@ -207,6 +207,20 @@ module Mailtrap
       )
     end
 
+    # Performs a PUT request to the specified path
+    # @param path [String] The request path
+    # @param body [Hash] The request body
+    # @return [Hash, String, nil] JSON response or raw response body
+    # @!macro api_errors
+    def put(path, body = nil)
+      perform_request(
+        method: :put,
+        host: general_api_host,
+        path:,
+        body:
+      )
+    end
+
     # Performs a DELETE request to the specified path
     # @param path [String] The request path
     # @return [Hash, String, nil] JSON response or raw response body
@@ -261,6 +275,8 @@ module Mailtrap
                   Net::HTTP::Post.new(uri_or_path)
                 when :patch
                   Net::HTTP::Patch.new(uri_or_path)
+                when :put
+                  Net::HTTP::Put.new(uri_or_path)
                 when :delete
                   Net::HTTP::Delete.new(uri_or_path)
                 else

data/lib/mailtrap/company_info.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Sending Domain Company Info
+  # @see https://docs.mailtrap.io/developers/management/sending-domains
+  # @attr_reader name [String, nil] Company or individual name
+  # @attr_reader address [String, nil] Street address
+  # @attr_reader city [String, nil] City
+  # @attr_reader country [String, nil] Country
+  # @attr_reader phone [String, nil] Phone number
+  # @attr_reader zip_code [String, nil] ZIP or postal code
+  # @attr_reader privacy_policy_url [String, nil] URL to the privacy policy page
+  # @attr_reader terms_of_service_url [String, nil] URL to the terms of service page
+  # @attr_reader website_url [String, nil] Company website URL or LinkedIn / personal website
+  # @attr_reader info_level [String, nil] Whether the sender is a "business" or "individual"
+  CompanyInfo = Struct.new(
+    :name,
+    :address,
+    :city,
+    :country,
+    :phone,
+    :zip_code,
+    :privacy_policy_url,
+    :terms_of_service_url,
+    :website_url,
+    :info_level,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/company_info_api.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'company_info'
+
+module Mailtrap
+  class CompanyInfoAPI
+    include BaseAPI
+
+    self.supported_options = %i[
+      name
+      address
+      city
+      country
+      phone
+      zip_code
+      privacy_policy_url
+      terms_of_service_url
+      website_url
+      info_level
+    ].freeze
+
+    self.response_class = CompanyInfo
+
+    # Gets company information for a sending domain
+    # @param sending_domain_id [Integer] The sending domain ID
+    # @return [CompanyInfo] Company information
+    # @!macro api_errors
+    def get(sending_domain_id)
+      response = client.get(base_path(sending_domain_id))
+      build_entity(response[:data], CompanyInfo)
+    end
+
+    # Creates company information for a sending domain
+    # @param sending_domain_id [Integer] The sending domain ID
+    # @param [Hash] options The company info attributes
+    # @option options [String] :name Company or individual name
+    # @option options [String] :address Street address
+    # @option options [String] :city City
+    # @option options [String] :country Country
+    # @option options [String] :phone Phone number
+    # @option options [String] :zip_code ZIP or postal code
+    # @option options [String] :privacy_policy_url URL to the privacy policy page
+    # @option options [String] :terms_of_service_url URL to the terms of service page
+    # @option options [String] :website_url Company website URL
+    # @option options [String] :info_level Whether the sender is a "business" or "individual"
+    # @return [CompanyInfo] Created company information
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(sending_domain_id, options)
+      validate_options!(options, supported_options)
+      response = client.post(base_path(sending_domain_id), wrap_request(options))
+      build_entity(response[:data], CompanyInfo)
+    end
+
+    # Updates company information for a sending domain
+    # @param sending_domain_id [Integer] The sending domain ID
+    # @param [Hash] options The company info attributes to update
+    # @return [CompanyInfo] Updated company information
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(sending_domain_id, options)
+      validate_options!(options, supported_options)
+      response = client.patch(base_path(sending_domain_id), wrap_request(options))
+      build_entity(response[:data], CompanyInfo)
+    end
+
+    private
+
+    def base_path(sending_domain_id)
+      "/api/accounts/#{account_id}/sending_domains/#{sending_domain_id}/company_info"
+    end
+
+    def wrap_request(options)
+      { company_info: options }
+    end
+  end
+end

data/lib/mailtrap/contact_event.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Contact Event
+  # @attr_reader contact_id [String] The contact ID (UUID)
+  # @attr_reader contact_email [String] The contact email
+  # @attr_reader name [String] The event name
+  # @attr_reader params [Hash] The event parameters (string keys, scalar values)
+  ContactEvent = Struct.new(
+    :contact_id,
+    :contact_email,
+    :name,
+    :params,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/contact_events_api.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'contact_event'
+
+module Mailtrap
+  class ContactEventsAPI
+    include BaseAPI
+
+    self.supported_options = %i[name params].freeze
+
+    self.response_class = ContactEvent
+
+    # Creates a contact event
+    # @param contact_identifier [String] The contact UUID or email address
+    # @param [Hash] options The event parameters
+    # @option options [String] :name The event name (max 255 characters)
+    # @option options [Hash] :params A hash of string keys and scalar values
+    # @return [ContactEvent] Created contact event object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(contact_identifier, options)
+      validate_options!(options, supported_options)
+      response = client.post(base_path(contact_identifier), options)
+      build_entity(response, ContactEvent)
+    end
+
+    private
+
+    def base_path(contact_identifier)
+      "/api/accounts/#{account_id}/contacts/#{contact_identifier}/events"
+    end
+  end
+end

data/lib/mailtrap/contact_export.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Contact Export
+  # @attr_reader id [Integer] The contact export ID
+  # @attr_reader status [String] The export status (created, started, finished)
+  # @attr_reader created_at [String] When the export was created
+  # @attr_reader updated_at [String] When the export was last updated
+  # @attr_reader url [String, nil] URL of the exported file (only when status is "finished")
+  ContactExport = Struct.new(
+    :id,
+    :status,
+    :created_at,
+    :updated_at,
+    :url,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/contact_exports_api.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'contact_export'
+
+module Mailtrap
+  class ContactExportsAPI
+    include BaseAPI
+
+    self.supported_options = %i[filters].freeze
+
+    self.response_class = ContactExport
+
+    # Retrieves a specific contact export
+    # @param export_id [Integer] The contact export ID
+    # @return [ContactExport] Contact export object
+    # @!macro api_errors
+    def get(export_id)
+      base_get(export_id)
+    end
+
+    # Creates a new contact export
+    # @param [Hash] options The export parameters
+    # @option options [Array<Hash>] :filters Filters to apply to the export
+    #   - `{ name: 'list_id', operator: 'equal', value: [Integer, ...] }`
+    #   - `{ name: 'subscription_status', operator: 'equal', value: 'subscribed' | 'unsubscribed' }`
+    # @return [ContactExport] Created contact export object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/contacts/exports"
+    end
+  end
+end

data/lib/mailtrap/inboxes_api.rb

@@ -85,6 +85,24 @@ module Mailtrap
       handle_response(response)
     end
 
+    # Turn the email address of the inbox on/off
+    # @param inbox_id [Integer] The Inbox identifier
+    # @return [Inbox] Updated Inbox object
+    # @!macro api_errors
+    def toggle_email_username(inbox_id)
+      response = client.patch("#{base_path}/#{inbox_id}/toggle_email_username")
+      handle_response(response)
+    end
+
+    # Reset username of email address per inbox
+    # @param inbox_id [Integer] The Inbox identifier
+    # @return [Inbox] Updated Inbox object
+    # @!macro api_errors
+    def reset_email_username(inbox_id)
+      response = client.patch("#{base_path}/#{inbox_id}/reset_email_username")
+      handle_response(response)
+    end
+
     private
 
     def wrap_request(options)

data/lib/mailtrap/permission_resource.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for a node in the Permissions resources tree
+  # @attr_reader id [Integer] Resource ID
+  # @attr_reader name [String] Resource name
+  # @attr_reader type [String] Resource type (account, project, inbox, sending_domain, ...)
+  # @attr_reader access_level [Integer] The access level the current token has on this resource
+  # @attr_reader resources [Array<PermissionResource>] Nested child resources
+  PermissionResource = Struct.new(
+    :id,
+    :name,
+    :type,
+    :access_level,
+    :resources,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/permissions_api.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'permission_resource'
+
+module Mailtrap
+  class PermissionsAPI
+    include BaseAPI
+
+    # Bulk-updates user or token permissions on an account access
+    # @param account_access_id [Integer] The account access ID
+    # @param permissions [Array<Hash>] Array of permission entries
+    #   - `{ resource_id:, resource_type:, access_level: }` to create or update
+    #   - `{ resource_id:, resource_type:, _destroy: true }` to remove
+    # @return [Hash] API response (e.g. `{ message: 'Permissions have been updated!' }`)
+    # @!macro api_errors
+    def bulk_update(account_access_id, permissions)
+      client.put(
+        "#{base_path}/account_accesses/#{account_access_id}/permissions/bulk",
+        { permissions: permissions }
+      )
+    end
+
+    # Returns the recursive tree of resources the current token can access.
+    # Each node carries the token's access_level and any nested child resources.
+    # @return [Array<PermissionResource>] Top-level resources, each with nested children
+    # @!macro api_errors
+    def resources
+      response = client.get("#{base_path}/permissions/resources")
+      build_resource_tree(response)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}"
+    end
+
+    def build_resource_tree(items)
+      items.map do |item|
+        PermissionResource.new(
+          id: item[:id],
+          name: item[:name],
+          type: item[:type],
+          access_level: item[:access_level],
+          resources: build_resource_tree(Array(item[:resources]))
+        )
+      end
+    end
+  end
+end

data/lib/mailtrap/sending_domains_api.rb

@@ -7,7 +7,7 @@ module Mailtrap
   class SendingDomainsAPI
     include BaseAPI
 
-    self.supported_options = %i[domain_name]
+    self.supported_options = %i[open_tracking_enabled click_tracking_enabled auto_unsubscribe_link_enabled]
 
     self.response_class = SendingDomain
 
@@ -34,7 +34,7 @@ module Mailtrap
     # @!macro api_errors
     # @raise [ArgumentError] If invalid options are provided
     def create(options)
-      base_create(options)
+      base_create(options, %i[domain_name])
     end
 
     # Deletes a sending domain
@@ -45,6 +45,19 @@ module Mailtrap
       base_delete(domain_id)
     end
 
+    # Updates configuration settings for a sending domain
+    # @param domain_id [Integer] The sending domain ID
+    # @param [Hash] options The parameters to update
+    # @option options [Boolean] :open_tracking_enabled Enable open tracking for emails sent from this domain
+    # @option options [Boolean] :click_tracking_enabled Enable click tracking for links in emails sent from this domain
+    # @option options [Boolean] :auto_unsubscribe_link_enabled Automatically add an unsubscribe link to emails
+    # @return [SendingDomain] Updated sending domain
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(domain_id, options)
+      base_update(domain_id, options)
+    end
+
     # Email DNS configuration instructions for the sending domain
     # @param domain_id [Integer] The sending domain ID
     # @param email [String] The email for instructions

data/lib/mailtrap/sub_account.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an organization sub account
+  # @attr_reader id [Integer] The sub account ID
+  # @attr_reader name [String] The sub account name
+  SubAccount = Struct.new(
+    :id,
+    :name,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/sub_accounts_api.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'sub_account'
+
+module Mailtrap
+  class SubAccountsAPI
+    include BaseAPI
+
+    attr_reader :organization_id
+
+    self.supported_options = %i[name].freeze
+
+    self.response_class = SubAccount
+
+    # @param organization_id [Integer] The organization ID
+    # @param client [Mailtrap::Client] The client instance
+    # @raise [ArgumentError] If organization_id is nil
+    def initialize(organization_id, client = Mailtrap::Client.new)
+      raise ArgumentError, 'organization_id is required' if organization_id.nil?
+
+      @organization_id = organization_id
+      @client = client
+    end
+
+    # Lists all sub accounts under the organization
+    # @return [Array<SubAccount>] Array of sub accounts
+    # @!macro api_errors
+    def list
+      base_list
+    end
+
+    # Creates a new sub account under the organization
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name Name of the sub account
+    # @return [SubAccount] Created sub account
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    private
+
+    def base_path
+      "/api/organizations/#{organization_id}/sub_accounts"
+    end
+
+    def wrap_request(options)
+      { account: options }
+    end
+  end
+end

data/lib/mailtrap/version.rb

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

data/lib/mailtrap/webhook.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Webhook
+  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/8d553c46c2d33-webhooks
+  # @attr_reader id [Integer] The webhook ID
+  # @attr_reader url [String] The URL that will receive webhook payloads
+  # @attr_reader active [Boolean] Whether the webhook is active
+  # @attr_reader webhook_type [String] The type of webhook (`email_sending` or `audit_log`)
+  # @attr_reader payload_format [String] The webhook payload format (`json` or `jsonlines`)
+  # @attr_reader sending_stream [String, nil] The sending stream (`transactional` or `bulk`).
+  #   Applicable only for `email_sending` webhooks.
+  # @attr_reader domain_id [Integer, nil] The sending domain ID the webhook is scoped to,
+  #   or nil for all domains. Applicable only for `email_sending` webhooks.
+  # @attr_reader event_types [Array<String>] The event types the webhook is subscribed to.
+  #   Applicable only for `email_sending` webhooks.
+  # @attr_reader signing_secret [String, nil] HMAC SHA-256 signing secret. Returned only on creation.
+  Webhook = Struct.new(
+    :id,
+    :url,
+    :active,
+    :webhook_type,
+    :payload_format,
+    :sending_stream,
+    :domain_id,
+    :event_types,
+    :signing_secret,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/webhooks.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Mailtrap
+  # Helpers for working with inbound Mailtrap webhooks.
+  #
+  # @see https://docs.mailtrap.io/email-api-smtp/advanced/webhooks#verifying-the-signature
+  module Webhooks
+    # Hex-encoded HMAC-SHA256 signature length.
+    SIGNATURE_HEX_LENGTH = 64
+
+    # Verifies the HMAC-SHA256 signature of a Mailtrap webhook payload.
+    #
+    # Mailtrap signs every outbound webhook by computing
+    # `HMAC-SHA256(signing_secret, raw_request_body)` and sending the lowercase
+    # hex digest in the `Mailtrap-Signature` HTTP header. Compute the same
+    # digest on your side and compare it in constant time.
+    #
+    # The comparison is performed with {OpenSSL.fixed_length_secure_compare} to
+    # avoid timing side-channels.
+    #
+    # The method never raises on inputs that could plausibly arrive over the
+    # wire (empty strings, wrong-length signatures, non-hex characters, missing
+    # secret) — it simply returns `false`. This makes it safe to call directly
+    # from a controller without rescuing.
+    #
+    # @param payload [String] The raw request body, exactly as received.
+    #   **Do not** parse and re-serialize the JSON — re-encoding may reorder
+    #   keys or alter whitespace and invalidate the signature.
+    # @param signature [String] The value of the `Mailtrap-Signature` HTTP
+    #   header (lowercase hex string).
+    # @param signing_secret [String] The webhook's `signing_secret`, returned
+    #   by {WebhooksAPI#create} on webhook creation.
+    # @return [Boolean] `true` if the signature is valid for the given payload
+    #   and secret, `false` otherwise.
+    def self.verify_signature(payload:, signature:, signing_secret:)
+      return false unless [payload, signature, signing_secret].all? { |v| v.is_a?(String) && !v.empty? }
+      return false if signature.bytesize != SIGNATURE_HEX_LENGTH
+
+      expected = OpenSSL::HMAC.hexdigest('SHA256', signing_secret, payload)
+
+      OpenSSL.fixed_length_secure_compare(expected, signature)
+    rescue ArgumentError
+      # fixed_length_secure_compare raises ArgumentError on length mismatch
+      false
+    end
+  end
+end

data/lib/mailtrap/webhooks_api.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'webhook'
+
+module Mailtrap
+  class WebhooksAPI
+    include BaseAPI
+
+    self.supported_options = %i[url webhook_type active payload_format sending_stream event_types domain_id]
+
+    self.response_class = Webhook
+
+    # Lists all webhooks for the account
+    # @return [Array<Webhook>] Array of webhooks
+    # @!macro api_errors
+    def list
+      response = client.get(base_path)
+      response[:data].map { |item| build_entity(item, response_class) }
+    end
+
+    # Retrieves a specific webhook
+    # @param webhook_id [Integer] The webhook ID
+    # @return [Webhook] Webhook object
+    # @!macro api_errors
+    def get(webhook_id)
+      base_get(webhook_id)
+    end
+
+    # Creates a new webhook
+    # @param [Hash] options The parameters to create
+    # @option options [String] :url The URL that will receive webhook payloads
+    # @option options [String] :webhook_type The type of webhook (`email_sending` or `audit_log`)
+    # @option options [Boolean] :active Whether the webhook is active. Defaults to true.
+    # @option options [String] :payload_format Payload format (`json` or `jsonlines`). Defaults to `json`.
+    # @option options [String] :sending_stream Sending stream (`transactional` or `bulk`).
+    #   Required for `email_sending` webhook type.
+    # @option options [Array<String>] :event_types Event types to subscribe to.
+    #   Required for `email_sending` webhook type.
+    # @option options [Integer] :domain_id Sending domain ID to scope the webhook to.
+    #   Applicable only for `email_sending` webhooks.
+    # @return [Webhook] Created webhook (includes `signing_secret`)
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Updates an existing webhook
+    # @param webhook_id [Integer] The webhook ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :url The URL that will receive webhook payloads
+    # @option options [Boolean] :active Whether the webhook is active
+    # @option options [String] :payload_format Payload format (`json` or `jsonlines`)
+    # @option options [Array<String>] :event_types Event types to subscribe to.
+    #   Applicable only for `email_sending` webhooks.
+    # @return [Webhook] Updated webhook
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(webhook_id, options)
+      base_update(webhook_id, options, %i[url active payload_format event_types])
+    end
+
+    # Deletes a webhook
+    # @param webhook_id [Integer] The webhook ID
+    # @return [Webhook] Deleted webhook
+    # @!macro api_errors
+    def delete(webhook_id)
+      response = client.delete("#{base_path}/#{webhook_id}")
+      handle_response(response) if response
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/webhooks"
+    end
+
+    def wrap_request(options)
+      { webhook: options }
+    end
+
+    def handle_response(response)
+      build_entity(response[:data], response_class)
+    end
+  end
+end

data/lib/mailtrap.rb

@@ -6,20 +6,28 @@ require_relative 'mailtrap/errors'
 require_relative 'mailtrap/version'
 require_relative 'mailtrap/accounts_api'
 require_relative 'mailtrap/account_accesses_api'
+require_relative 'mailtrap/api_tokens_api'
+require_relative 'mailtrap/permissions_api'
+require_relative 'mailtrap/sub_accounts_api'
 require_relative 'mailtrap/billing_api'
 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/contact_exports_api'
+require_relative 'mailtrap/contact_events_api'
 require_relative 'mailtrap/suppressions_api'
 require_relative 'mailtrap/sending_domains_api'
+require_relative 'mailtrap/company_info_api'
 require_relative 'mailtrap/email_logs_api'
 require_relative 'mailtrap/projects_api'
 require_relative 'mailtrap/inboxes_api'
 require_relative 'mailtrap/sandbox_messages_api'
 require_relative 'mailtrap/sandbox_attachments_api'
 require_relative 'mailtrap/stats_api'
+require_relative 'mailtrap/webhooks_api'
+require_relative 'mailtrap/webhooks'
 
 module Mailtrap
   # @!macro api_errors

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailtrap
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 2.11.1
 platform: ruby
 authors:
 - Railsware Products Studio LLC
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -49,12 +50,20 @@ files:
 - lib/mailtrap/action_mailer.rb
 - lib/mailtrap/action_mailer/delivery_method.rb
 - lib/mailtrap/action_mailer/railtie.rb
+- lib/mailtrap/api_token.rb
+- lib/mailtrap/api_tokens_api.rb
 - lib/mailtrap/attachment.rb
 - lib/mailtrap/base_api.rb
 - lib/mailtrap/billing_api.rb
 - lib/mailtrap/billing_usage.rb
 - lib/mailtrap/client.rb
+- lib/mailtrap/company_info.rb
+- lib/mailtrap/company_info_api.rb
 - lib/mailtrap/contact.rb
+- lib/mailtrap/contact_event.rb
+- lib/mailtrap/contact_events_api.rb
+- lib/mailtrap/contact_export.rb
+- lib/mailtrap/contact_exports_api.rb
 - lib/mailtrap/contact_field.rb
 - lib/mailtrap/contact_fields_api.rb
 - lib/mailtrap/contact_import.rb
@@ -76,6 +85,8 @@ files:
 - lib/mailtrap/mail.rb
 - lib/mailtrap/mail/base.rb
 - lib/mailtrap/mail/from_template.rb
+- lib/mailtrap/permission_resource.rb
+- lib/mailtrap/permissions_api.rb
 - lib/mailtrap/project.rb
 - lib/mailtrap/projects_api.rb
 - lib/mailtrap/sandbox_attachment.rb
@@ -87,9 +98,14 @@ files:
 - lib/mailtrap/sending_stat_group.rb
 - lib/mailtrap/sending_stats.rb
 - lib/mailtrap/stats_api.rb
+- lib/mailtrap/sub_account.rb
+- lib/mailtrap/sub_accounts_api.rb
 - lib/mailtrap/suppression.rb
 - lib/mailtrap/suppressions_api.rb
 - lib/mailtrap/version.rb
+- lib/mailtrap/webhook.rb
+- lib/mailtrap/webhooks.rb
+- lib/mailtrap/webhooks_api.rb
 - mailtrap.gemspec
 homepage: https://github.com/mailtrap/mailtrap-ruby
 licenses:
@@ -99,6 +115,7 @@ metadata:
   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: []
 require_paths:
 - lib
@@ -113,7 +130,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Official mailtrap.io API client
 test_files: []