Add billing API

CHANGELOG.md

@@ -1,5 +1,6 @@
 - Add Sandbox Messages API
 - Add Sending Domains API
+- Add Billing API
 
 ## [2.6.0] - 2026-01-27
 - Add Inboxes API

README.md

@@ -191,6 +191,7 @@ Contact management:
 General API:
 
 - Templates CRUD – [`email_templates_api.rb`](examples/email_templates_api.rb)
+- Billing – [`billing_api.rb`](examples/billing_api.rb)
 - Action Mailer – [`action_mailer.rb`](examples/action_mailer.rb)
 
 ## Migration guide v1 → v2

examples/billing_api.rb

@@ -0,0 +1,9 @@
+require 'mailtrap'
+
+account_id = 3229
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+billing_api = Mailtrap::BillingAPI.new(account_id, client)
+
+# Get billing information for the account
+billing_api.get
+# => #<Mailtrap::Billing billing: { cycle_start: '2026-02-06T12:59:54.000Z', ... }, ...>

lib/mailtrap.rb

@@ -14,6 +14,7 @@
 require_relative 'mailtrap/projects_api'
 require_relative 'mailtrap/inboxes_api'
 require_relative 'mailtrap/sandbox_messages_api'
+require_relative 'mailtrap/billing_api'
 
 module Mailtrap
   # @!macro api_errors

lib/mailtrap/billing.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Billing data
+  # @see https://docs.mailtrap.io/developers/account-management/billing
+  # @attr_reader billing [Hash] The billing cycles
+  # @attr_reader testing [Hash] Testing subscription details
+  # @attr_reader sending [Hash] Sending subscription details
+  #
+  Billing = Struct.new(
+    :billing,
+    :testing,
+    :sending,
+    keyword_init: true
+  )
+end

lib/mailtrap/billing_api.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'billing'
+
+module Mailtrap
+  class BillingAPI
+    include BaseAPI
+
+    self.response_class = Billing
+
+    # Show billing details for the account
+    # @return <Billing> Billing data for account
+    # @!macro api_errors
+    def get
+      response = client.get(base_path)
+      handle_response(response)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/billing/usage"
+    end
+  end
+end

lib/mailtrap/project.rb

@@ -2,7 +2,7 @@
 
 module Mailtrap
   # Data Transfer Object for Project
-  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/ee252e413d78a-create-project
+  # @see https://docs.mailtrap.io/developers/email-sandbox/projects
   # @attr_reader id [Integer] The project ID
   # @attr_reader name [String] The project name
   # @attr_reader share_links [Hash] Admin and viewer share links

spec/mailtrap/billing_api_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+RSpec.describe Mailtrap::BillingAPI, :vcr do
+  subject(:billing_api) { described_class.new(account_id, client) }
+
+  let(:account_id) { ENV.fetch('MAILTRAP_ACCOUNT_ID', 1_111_111) }
+  let(:client) { Mailtrap::Client.new(api_key: ENV.fetch('MAILTRAP_API_KEY', 'local-api-key')) }
+
+  describe '#get' do
+    subject(:get) { billing_api.get }
+
+    it 'maps response data to Billing object' do
+      expect(get).to be_a(Mailtrap::Billing)
+
+      expect(get).to match_struct(
+        billing: { cycle_start: '2026-02-06T12:59:54.000Z', cycle_end: '2026-03-06T12:59:54.000Z' },
+        testing: { plan: { name: 'Team' },
+                   usage: { sent_messages_count: { current: 0, limit: 5000 },
+                            forwarded_messages_count: { current: 0, limit: 500 } } },
+        sending: { plan: { name: 'Basic 10K' }, usage: { sent_messages_count: { current: 0, limit: 10_000 } } }
+      )
+    end
+
+    context 'when api key is incorrect' do
+      let(:client) { Mailtrap::Client.new(api_key: 'incorrect-api-key') }
+
+      it 'raises authorization error' do
+        expect { get }.to raise_error do |error|
+          expect(error).to be_a(Mailtrap::AuthorizationError)
+          expect(error.message).to include('Incorrect API token')
+          expect(error.messages.any? { |msg| msg.include?('Incorrect API token') }).to be true
+        end
+      end
+    end
+  end
+end

spec/mailtrap/billing_spec.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+RSpec.describe Mailtrap::Billing do
+  describe '#initialize' do
+    subject(:billing) { described_class.new(attributes) }
+
+    let(:attributes) do
+      {
+        billing: {
+          cycle_start: '2024-02-15T21:11:59.624Z',
+          cycle_end: '2024-02-15T21:11:59.624Z'
+        },
+        testing: {
+          plan: {
+            name: 'Individual'
+          },
+          usage: {
+            sent_messages_count: {
+              current: 1234,
+              limit: 5000
+            },
+            forwarded_messages_count: {
+              current: 0,
+              limit: 100
+            }
+          }
+        },
+        sending: {
+          plan: {
+            name: 'Basic 10K'
+          },
+          usage: {
+            sent_messages_count: {
+              current: 6789,
+              limit: 10_000
+            }
+          }
+        }
+      }
+    end
+
+    it 'creates a billing data with all attributes' do
+      expect(billing).to match_struct(
+        billing: {
+          cycle_start: '2024-02-15T21:11:59.624Z',
+          cycle_end: '2024-02-15T21:11:59.624Z'
+        },
+        testing: {
+          plan: {
+            name: 'Individual'
+          },
+          usage: {
+            sent_messages_count: {
+              current: 1234,
+              limit: 5000
+            },
+            forwarded_messages_count: {
+              current: 0,
+              limit: 100
+            }
+          }
+        },
+        sending: {
+          plan: {
+            name: 'Basic 10K'
+          },
+          usage: {
+            sent_messages_count: {
+              current: 6789,
+              limit: 10_000
+            }
+          }
+        }
+      )
+    end
+  end
+end