Account management API

bin/record-vcr

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Run RSpec against the live Mailtrap API to record (or re-record) VCR cassettes.
+# Real HTTP calls are made — only run this when you intend to update the
+# cassettes under spec/fixtures/vcr_cassettes/. Credentials are injected from
+# 1Password at runtime.
+#
+# Usage:
+#   bin/record-vcr                                              # all specs
+#   bin/record-vcr spec/mailtrap/sending_domains_api_spec.rb    # single file
+#   bin/record-vcr spec/mailtrap/sending_domains_api_spec.rb:42 # single example
+#   bin/record-vcr -e "#update"                                 # filter by name
+#   bin/record-vcr --org spec/mailtrap/sub_accounts_api_spec.rb # use organization API token
+#
+# Pass --org as the first argument to authenticate with the organization-level token
+# (needed for organization-scoped endpoints like SubAccountsAPI). Default is the
+# account-level token.
+#
+# Requires the 1Password CLI (`op`) to be installed and signed in.
+
+set -euo pipefail
+
+export MAILTRAP_ACCOUNT_ID="op://Mailtrap Dev/Mailtrap SDK Dev API Key/account_id"
+export MAILTRAP_ORGANIZATION_ID="op://Mailtrap Dev/Mailtrap SDK Dev API Key/organization_id"
+export MAILTRAP_API_KEY="op://Mailtrap Dev/Mailtrap SDK Dev API Key/account_api_token"
+export MAILTRAP_ORGANIZATION_API_KEY="op://Mailtrap Dev/Mailtrap SDK Dev API Key/organization_api_token"
+
+exec op run -- bundle exec rspec "$@"

examples/api_tokens_api.rb

@@ -0,0 +1,9 @@
+require 'mailtrap'
+
+account_id = 3229
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+api_tokens = Mailtrap::ApiTokensAPI.new(account_id, client)
+
+# List API tokens
+api_tokens.list
+# => [#<struct Mailtrap::ApiToken id=12345, name="My API Token", last_4_digits="x7k9", ..., token=nil>, ...]

examples/permissions_api.rb

@@ -0,0 +1,15 @@
+require 'mailtrap'
+
+account_id = 3229
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+permissions = Mailtrap::PermissionsAPI.new(account_id, client)
+
+# Bulk-update user/token permissions on an account access. Combine create/update with destroy:
+permissions.bulk_update(
+  5142, # account_access_id
+  [
+    { resource_id: '3281', resource_type: 'account', access_level: 'viewer' },
+    { resource_id: '3809', resource_type: 'inbox', _destroy: true }
+  ]
+)
+# => { message: "Permissions have been updated!" }

examples/sub_accounts_api.rb

@@ -0,0 +1,13 @@
+require 'mailtrap'
+
+organization_id = 4567
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+sub_accounts = Mailtrap::SubAccountsAPI.new(organization_id, client)
+
+# List sub accounts under the organization
+sub_accounts.list
+# => [#<struct Mailtrap::SubAccount id=12345, name="Development Team Account">, ...]
+
+# Create a new sub account
+sub_accounts.create(name: 'New Team Account')
+# => #<struct Mailtrap::SubAccount id=12347, name="New Team Account">

lib/mailtrap.rb

@@ -6,6 +6,9 @@
 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'

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

lib/mailtrap/api_tokens_api.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'api_token'
+
+module Mailtrap
+  class ApiTokensAPI
+    include BaseAPI
+
+    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
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/api_tokens"
+    end
+  end
+end

lib/mailtrap/client.rb

@@ -207,6 +207,20 @@ def patch(path, body = nil)
       )
     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 @@ def setup_request(method, uri_or_path, body = nil)
                   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

lib/mailtrap/permissions_api.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+
+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
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}"
+    end
+  end
+end

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

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