Add contact enpoints

examples/contact_events_api.rb

@@ -0,0 +1,21 @@
+require 'mailtrap'
+
+account_id = 3229
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+contact_events = Mailtrap::ContactEventsAPI.new(account_id, client)
+
+# Submit a custom event for a contact (identifier can be UUID or email)
+contact_events.create(
+  'john.smith@example.com',
+  name: 'UserLogin',
+  params: {
+    user_id: 101,
+    user_name: 'John Smith',
+    is_active: true,
+    last_seen: nil
+  }
+)
+# => #<struct Mailtrap::ContactEvent contact_id="018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132",
+#                                   contact_email="john.smith@example.com",
+#                                   name="UserLogin",
+#                                   params={"user_id"=>101, ...}>

examples/contact_exports_api.rb

@@ -0,0 +1,25 @@
+require 'mailtrap'
+
+account_id = 3229
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+contact_exports = Mailtrap::ContactExportsAPI.new(account_id, client)
+
+# Create a contact export filtered by list IDs
+contact_exports.create(
+  filters: [
+    { name: 'list_id', operator: 'equal', value: [1, 2] }
+  ]
+)
+# => #<struct Mailtrap::ContactExport id=1, status="started", created_at="...", updated_at="...", url=nil>
+
+# Create a contact export filtered by subscription status
+contact_exports.create(
+  filters: [
+    { name: 'subscription_status', operator: 'equal', value: 'subscribed' }
+  ]
+)
+# => #<struct Mailtrap::ContactExport id=2, status="started", ..., url=nil>
+
+# Get a contact export by ID — once status is "finished", `url` is the file location
+contact_exports.get(1)
+# => #<struct Mailtrap::ContactExport id=1, status="finished", ..., url="https://...">

lib/mailtrap.rb

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

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

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

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

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