mailtrap 2.15.0 → 2.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba78e8e22574eb5404c0e4d14f5a4ad764dabc559a3fd58bc0ae9ba46a49ea3f
-  data.tar.gz: da43055430599e2f496fc794fb145bacb7d589785b2387f6296ed978db57c4ac
+  metadata.gz: cf895b774a80d6579230f2629793150d13be0648536b9c88524f6149ae39feb9
+  data.tar.gz: 50169e072e02c1509a9da6b7b933ad8fe1b6b6d219f50771696d3f5f62cc4674
 SHA512:
-  metadata.gz: 7e5eb305e76d483f99711da0d2c913b1fdab00c8010bd55b697171284bd712d78545096dd5af9ffeab6886c06518b8c8f515edf42cf0b3e41dab4d98f7265a5b
-  data.tar.gz: e9c400428a9e86678a2b6fd6c6ef6ddbada0726ecfac29e9b254021b6a9f9143f912e81f6ba967084fa94c16c4ac19aaaa7e01699ad98a31ef4d3e934d37cd9d
+  metadata.gz: 7da15a7343f680b071be20f34f3223582351e66de800600d48c84afd46ee78d9dad96220fb9885f4498f0d62617cb35b16a0957169d3e79639d071509177c52d
+  data.tar.gz: 4c4a95c0fdbf908287f60e6ae15ff0332a24ee35e217643f80664a6ef379d80216902335c4d7b8108c05301f3f7e46e39ef232f1293e1ee70a9edc41533a0334

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [2.17.0] - 2026-10-07
+
+## What's Changed
+* Add TemplatesAPI for the paginated /api/templates endpoints by @izikaj in https://github.com/mailtrap/mailtrap-ruby/pull/133
+
+## New Contributors
+* @izikaj made their first contribution in https://github.com/mailtrap/mailtrap-ruby/pull/133
+
+**Full Changelog**: https://github.com/mailtrap/mailtrap-ruby/compare/v2.16.0...v2.17.0
+
+## [2.16.0] - 2026-08-31
+
+## What's Changed
+* MT-23076: support expires_at for api token create and reset by @oshchyhol in https://github.com/mailtrap/mailtrap-ruby/pull/122
+* MT-23762: redact api token values from VCR cassettes by @oshchyhol in https://github.com/mailtrap/mailtrap-ruby/pull/125
+
+## New Contributors
+* @oshchyhol made their first contribution in https://github.com/mailtrap/mailtrap-ruby/pull/122
+
+**Full Changelog**: https://github.com/mailtrap/mailtrap-ruby/compare/v2.15.0...v2.16.0
+
 ## [2.15.0] - 2026-08-28
 
 ## What's Changed

data/Gemfile.lock

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

data/README.md

@@ -208,8 +208,11 @@ General:
 
 - Accounts API – [`accounts_api.rb`](examples/accounts_api.rb)
 - Account Accesses API – [`account_accesses_api.rb`](examples/account_accesses_api.rb)
+- API Tokens API – [`api_tokens_api.rb`](examples/api_tokens_api.rb)
 - Billing API – [`billing_api.rb`](examples/billing_api.rb)
-- Templates API – [`email_templates_api.rb`](examples/email_templates_api.rb)
+- Permissions API – [`permissions_api.rb`](examples/permissions_api.rb)
+- Templates API (experimental) – [`templates_api.rb`](examples/templates_api.rb)
+- Email 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)
 

data/lib/mailtrap/api_tokens_api.rb

@@ -7,7 +7,7 @@ module Mailtrap
   class ApiTokensAPI
     include BaseAPI
 
-    self.supported_options = %i[name resources].freeze
+    self.supported_options = %i[name expires_at resources].freeze
 
     self.response_class = ApiToken
 
@@ -30,6 +30,9 @@ module Mailtrap
     # 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 [String, nil] :expires_at Optional token expiration as an ISO 8601 date-time.
+    #   Omit for the server default (a 1-year default is being rolled out). Pass explicit nil for
+    #   a token that never expires. Past or more-than-5-years-ahead values are rejected with 422
     # @option options [Array<Hash>] :resources Permissions to assign
     #   - `{ resource_type:, resource_id:, access_level: }`
     # @return [ApiToken] Created token (full `token` value populated)
@@ -43,10 +46,17 @@ module Mailtrap
     # 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
+    # @param [Hash] options The reset parameters
+    # @option options [String, nil] :expires_at Optional token expiration as an ISO 8601 date-time.
+    #   Omit for the server default (a 1-year default is being rolled out). Pass explicit nil for
+    #   a token that never expires. Past or more-than-5-years-ahead values are rejected with 422
     # @return [ApiToken] New token (full `token` value populated)
     # @!macro api_errors
-    def reset(token_id)
-      response = client.post("#{base_path}/#{token_id}/reset")
+    # @raise [ArgumentError] If invalid options are provided
+    def reset(token_id, options = {})
+      validate_options!(options, %i[expires_at])
+      # An empty hash must not be sent as a body — the endpoint historically takes no body
+      response = client.post("#{base_path}/#{token_id}/reset", options.empty? ? nil : options)
       handle_response(response)
     end
 

data/lib/mailtrap/template.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Template
+  # @attr_reader id [Integer] The template ID
+  # @attr_reader uuid [String] The template UUID
+  # @attr_reader name [String] The template name
+  # @attr_reader subject [String] The email subject
+  # @attr_reader category [String] The template category
+  # @attr_reader body_html [String] The HTML content
+  # @attr_reader body_text [String] The plain text content
+  # @attr_reader created_at [String] The creation timestamp
+  # @attr_reader updated_at [String] The last update timestamp
+  Template = Struct.new(
+    :id,
+    :uuid,
+    :name,
+    :subject,
+    :category,
+    :body_html,
+    :body_text,
+    :created_at,
+    :updated_at,
+    keyword_init: true
+  )
+
+  # Response from listing templates (paginated)
+  # @attr_reader data [Array<Template>] Page of templates
+  # @attr_reader pagination [Hash] Page-token pagination metadata
+  #   (+token+, +prev_token+, +next_token+, +first_url+, +prev_url+, +current_url+, +next_url+)
+  TemplatesListResponse = Struct.new(
+    :data,
+    :pagination,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/templates_api.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'template'
+
+module Mailtrap
+  # @note Experimental: the +/api/templates+ endpoints may change their request and response
+  #   shapes before general availability.
+  class TemplatesAPI
+    include BaseAPI
+
+    self.supported_options = %i[name subject category body_html body_text]
+
+    self.response_class = Template
+
+    # Lists templates for the account, one page at a time. Unlike {EmailTemplatesAPI#list}, it does
+    # not return every template: pass +pagination[:next_token]+ with the same +per_page+ to get the
+    # next page.
+    # @param per_page [Integer, nil] Number of templates per page (max 100, default 50)
+    # @param token [Integer, nil] Page number to retrieve (page-token pagination, default 1)
+    # @return [TemplatesListResponse] The page of templates and pagination metadata
+    # @!macro api_errors
+    def list(per_page: nil, token: nil)
+      query_params = {}
+      query_params[:per_page] = per_page unless per_page.nil?
+      query_params[:token] = token unless token.nil?
+
+      response = client.get(base_path, query_params)
+
+      TemplatesListResponse.new(
+        data: Array(response[:data]).map { |item| build_entity(item, response_class) },
+        pagination: response[:pagination]
+      )
+    end
+
+    # Retrieves a specific template
+    # @param template_id [Integer] The template ID
+    # @return [Template] Template object
+    # @!macro api_errors
+    def get(template_id)
+      base_get(template_id)
+    end
+
+    # Creates a new template
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The template name (required)
+    # @option options [String] :subject The email subject (required)
+    # @option options [String] :category The template category (required)
+    # @option options [String, nil] :body_html The HTML content. Default: nil.
+    # @option options [String, nil] :body_text The plain text content. Default: nil.
+    # @return [Template] Created template object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Updates an existing template. Only the provided attributes are changed.
+    # @param template_id [Integer] The template ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The template name
+    # @option options [String] :subject The email subject
+    # @option options [String] :category The template category
+    # @option options [String, nil] :body_html The HTML content
+    # @option options [String, nil] :body_text The plain text content
+    # @return [Template] Updated template object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(template_id, options)
+      base_update(template_id, options)
+    end
+
+    # Deletes a template
+    # @param template_id [Integer] The template ID
+    # @return [nil]
+    # @!macro api_errors
+    def delete(template_id)
+      base_delete(template_id)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/templates"
+    end
+
+    def handle_response(response)
+      build_entity(response[:data], response_class)
+    end
+  end
+end

data/lib/mailtrap/version.rb

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

data/lib/mailtrap.rb

@@ -11,6 +11,7 @@ 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/templates_api'
 require_relative 'mailtrap/contacts_api'
 require_relative 'mailtrap/contact_lists_api'
 require_relative 'mailtrap/contact_fields_api'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailtrap
 version: !ruby/object:Gem::Version
-  version: 2.15.0
+  version: 2.17.0
 platform: ruby
 authors:
 - Railsware Products Studio LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-28 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -117,6 +117,8 @@ files:
 - lib/mailtrap/sub_accounts_api.rb
 - lib/mailtrap/suppression.rb
 - lib/mailtrap/suppressions_api.rb
+- lib/mailtrap/template.rb
+- lib/mailtrap/templates_api.rb
 - lib/mailtrap/tracking_opt_out.rb
 - lib/mailtrap/tracking_opt_outs_api.rb
 - lib/mailtrap/tracking_opt_outs_list_response.rb